info:
  title: ckanaction
security:
  - apiTokenHeader:
      description: CKAN API token
      type: apiKey
      name: Authorization
      in: header
components:
  securitySchemes:
    apiTokenHeader:
      type: apiKey
      in: header
      name: Authorization
      description: CKAN API token
servers:
  - url: http://localhost:5000/api/3/action
  - url: '{protocol}://{domain}/api/3/action'
    description: Your custom server running the CKAN Actions API (v3).
    variables:
      protocol:
        enum:
          - https
          - http
        default: https
      domain:
        default: 'demo.ckan.org'
paths:
  'current_package_list_with_resources':
    post:
      operationId: current_package_list_with_resources
      summary: current_package_list_with_resources
      description: |
        Return a list of the site's datasets (packages) and their resources.
        
        The list is sorted most-recently-modified first.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                limit:
                  type: integer
                  description: "if given, the list of datasets will be broken into pages of at most `limit` datasets per page and only one page will be returned at a time"
                offset:
                  type: integer
                  description: "when `limit` is given, the offset to start returning packages from"
  'member_list':
    post:
      operationId: member_list
      summary: member_list
      description: |
        Return the members of a group.

        The user must have permission to "get" the group.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: the id or name of the group
                object_type:
                  type: string
                  description: "restrict the members returned to those of a given type, e.g. `'user'` or `'package'` (default: `None`)"
                capacity:
                  type: string
                  description: "restrict the members returned to those with a given capacity, e.g. `'member'`, `'editor'`, `'admin'`, `'public'`, `'private'` (optional, default: `None`)"
  'package_collaborator_list':
    post:
      operationId: package_collaborator_list
      summary: package_collaborator_list
      description: |
        Return the list of all collaborators for a given dataset (package).

        Currently you must be an Admin on the dataset owner organization to manage collaborators.

        Note: This action requires the collaborators feature to be enabled with the [`ckan.auth.allow_dataset_collaborators`](https://docs.ckan.org/en/2.11/maintaining/configuration.html#ckan-auth-allow-dataset-collaborators) configuration option.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: the id or name of the dataset
                capacity:
                  type: string
                  description: if provided, only the users with this capacity are returned
  'package_collaborator_list_for_user':
    post:
      operationId: package_collaborator_list_for_user
      summary: package_collaborator_list_for_user
      description: |
        Return the list of all datasets the user is a collaborator in.

        Note: This action requires the collaborators feature to be enabled with the [`ckan.auth.allow_dataset_collaborators`](https://docs.ckan.org/en/2.11/maintaining/configuration.html#ckan-auth-allow-dataset-collaborators) configuration option.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: the id or name of the user
                capacity:
                  type: string
                  description: if provided, only datasets where the user has this capacity are returned
  'group_list':
    post:
      operationId: group_list
      summary: group_list
      description: |
        Return a list of the names of the site's groups.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: "the type of group to list (default: `'group'`), see docs for `IGroupForm`"
                sort:
                  type: string
                  description: "sorting of the search results. Default: \"title asc\" string of field name and sort-order. The allowed fields are 'name', 'package_count' and 'title'"
                limit:
                  type: integer
                  description: "the maximum number of groups returned. Default: `1000` when `all_fields=false` unless set in site's configuration `ckan.group_and_organization_list_max`. Default: 25 when `all_fields=true` unless set in site's configuration `ckan.group_and_organization_list_all_fields_max`"
                offset:
                  type: integer
                  description: "when `limit` is given, the offset to start returning groups from"
                groups:
                  type: array
                  items:
                    type: string
                  description: a list of names of the groups to return, if given only groups whose names are in this list will be returned
                all_fields:
                  type: boolean
                  description: "return group dictionaries instead of just names. Only core fields are returned - get some more using the include_* options. Returning a list of packages is too expensive, so the *packages* property for each group is deprecated, but there is a count of the packages in the *package_count* property. (default: `False`)"
                include_dataset_count:
                  type: boolean
                  # If `all_fields` is true?
                  description: "if `all_fields`, include the full package_count (default: `True`)"
                include_extras:
                  type: boolean
                  description: "if `all_fields`, include the group extra fields (default: `False`)"
                include_tags:
                  type: boolean
                  description: "if `all_fields`, include the group tags"
                include_groups:
                  type: boolean
                  description: "if `all_fields`, include the groups the groups are in"
                include_users:
                  type: boolean
                  description: "if `all_fields`, include the group users"
  'organization_list':
    post:
      operationId: organization_list
      summary: organization_list
      description: |
        Return a list of the names of the site's organizations.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: "the type of organization to list (default: `'group'`), see docs for `IGroupForm`"
                sort:
                  type: string
                  description: "sorting of the search results. Default: \"title asc\" string of field name and sort-order. The allowed fields are 'name', 'package_count' and 'title'"
                limit:
                  type: integer
                  description: "the maximum number of organizations returned. Default: `1000` when `all_fields=false` unless set in site's configuration `ckan.group_and_organization_list_max`. Default: 25 when `all_fields=true` unless set in site's configuration `ckan.group_and_organization_list_all_fields_max`"
                offset:
                  type: integer
                  description: "when `limit` is given, the offset to start returning organizations from"
                organizations:
                  type: array
                  items:
                    type: string
                  # Original docs typo seems like they say groups instead of organizations
                  description: a list of names of the organizations to return, if given only organizations whose names are in this list will be returned
                all_fields:
                  type: boolean
                  # Original docs typo seems like they say group instead of organization
                  description: "return organization dictionaries instead of just names. Only core fields are returned - get some more using the include_* options. Returning a list of packages is too expensive, so the *packages* property for each group is deprecated, but there is a count of the packages in the *package_count* property. (default: `False`)"
                include_dataset_count:
                  type: boolean
                  # If `all_fields` is true?
                  description: "if `all_fields`, include the full package_count (default: `True`)"
                include_extras:
                  type: boolean
                  description: "if `all_fields`, include the organization extra fields (default: `False`)"
                include_tags:
                  type: boolean
                  description: "if `all_fields`, include the organization tags (default: `False`)"
                include_groups:
                  type: boolean
                  # Modified to organizations instead of groups?
                  description: "if `all_fields`, include the organizations the organizations are in"
                include_users:
                  type: boolean
                  description: "if `all_fields`, include the organization users"
  'group_list_authz':
    post:
      operationId: group_list_authz
      summary: group_list_authz
      description: |
        Return the list of groups that the user is authorized to edit.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                available_only:
                  type: boolean
                  description: "remove the existing groups in the package (default: `False`)"
                am_member:
                  type: boolean
                  description: "if `True` return only the groups the logged-in user is a member of, otherwise return all groups that the user is authorized to edit (for example, sysadmin users are authorized to edit all groups) (default: `False`)"
  'organization_list_for_user':
    post:
      operationId: organization_list_for_user
      summary: organization_list_for_user
      description: |
        Return the organizations that the user has a given permission for.
        
        Specifically it returns the list of organizations that the currently authorized user has a given permission (for example: "manage_group") against.
        
        By default this returns the list of organizations that the currently authorized user is member of, in any capacity.
        
        When a user becomes a member of an organization in CKAN they're given a "capacity" (sometimes called a "role"), for example "member", "editor" or "admin".
        
        Each of these roles has certain permissions associated with it. For example the admin role has the "admin" permission (which means they have permission to do anything). The editor role has permissions like "create_dataset", "update_dataset" and "delete_dataset". The member role has the "read" permission.
        
        This function returns the list of organizations that the authorized user has a given permission for. For example the list of organizations that the user is an admin of, or the list of organizations that the user can create datasets in. This takes account of when permissions cascade down an organization hierarchy.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: the name or id of the user to get the organization list for (defaults to the currently authorized user, logged in or via the API key)
                permission:
                  type: string
                  description: "the permission the user has against the returned organizations, for example `\"read\"` or `\"create_dataset\"` (default: `\"manage_group\"`)"
                include_dataset_count:
                  type: boolean
                  description: "include the package_count in each org (default: `False`)"
  'license_list':
    post:
      operationId: license_list
      summary: license_list
      description: |
        Return the list of licenses available for datasets on the site.
  'tag_list':
    post:
      operationId: tag_list
      summary: tag_list
      description: |
        Return a list of the site's tags.

        By default only free tags (tags that don't belong to a vocabulary) are returned. If the `vocabulary_id` argument is given then only tags belonging to that vocabulary will be returned instead.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: a tag name query to search for, if given only tags whose names contain this string will be returned
                vocabulary_id:
                  type: string
                  # if "give" maybe should be if "given"?
                  description: the id or name of a vocabulary, if give only tags that belong to this vocabulary will be returned
                all_fields:
                  type: boolean
                  description: "return full tag dictionaries instead of just names (default: `False`)"
  'user_list':
    post:
      operationId: user_list
      summary: user_list
      description: |
        Return a list of the site's user accounts.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                q:
                  type: string
                  description: filter the users returned to those whose names contain a string
                email:
                  type: string
                  description: filter the users returned to those whose email match a string (you must be a sysadmin to use this filter)
                order_by:
                  type: string
                  description: "which field to sort the list (default: `'display_name'`)."
                  enum: ["id", "name", "fullname", "display_name", "created", "about", "sysadmin", "number_created_packages"]
                all_fields:
                  type: boolean
                  description: return full user disctionaries instead of just names
                include_site_user:
                  type: boolean
                  description: "add site_user to the result (default: `False`)"
  'package_relationships_list':
    post:
      operationId: package_relationships_list
      summary: package_relationships_list
      description: |
        Return a datset's relationships.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: the id or name of the first package
                id2:
                  type: string
                  description: the id or name of the second package
                rel:
                  type: string
                  description: "relationship as string, see `package_relationship_create()` for the relationship types"
  'package_show':
    post:
      operationId: package_show
      summary: package_show
      description: Return the metadata of a dataset and its resources.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - id
              type: object
              properties:
                id:
                  type: string
                  description: the id or name of the dataset
                use_default_schema:
                  type: boolean
                  description: use default package schema instead of a custom schema defined with an IDatasetForm plugin
                include_plugin_data:
                  type: boolean
                  description: Include the internal plugin data object (sysadmin only)
      x-codeSamples:
        - lang: rust
          label: Rust SDK (ckanaction) example
          source: |
            use dotenvy::dotenv;

            #[tokio::main]
            async fn main() -> Result<(), Box<dyn std::error::Error>> {
                // Load environment variables from .env file
                dotenv()?;

                // Initialize and build CKAN struct
                let ckan = ckanaction::CKAN::builder()
                    .url("http://localhost:5000")
                    .token(dotenvy::var("CKAN_API_TOKEN")?)
                    .build();

                // Send request to /package_show and print output
                let result = ckan.package_show()
                    .id("6b044c6b-e896-4800-a94d-9e5147b25a25".to_string())
                    .call()
                    .await?;
                println!("{result:#?}");

                Ok(())
            }
  'resource_show':
    post:
      operationId: resource_show
      summary: resource_show
      description: Return the metadata of a resource.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: the id of the resource
  'resource_view_show':
    post:
      operationId: resource_view_show
      summary: resource_view_show
      description: Return the metadata of a resource_view.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: the id of the resource_view
  resource_view_list:
    post:
      operationId: resource_view_list
      summary: resource_view_list
      description: Return the list of resource views for a particular resource.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: the id of the resource
  group_show:
    post:
      operationId: group_show
      summary: group_show
      description: Return the details of a group (only its first 1000 datasets are returned).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: the id or name of the group
                include_datasets:
                  type: boolean
                  description: "include a truncated list of the group's datasets (default: `False`)"
                include_dataset_count:
                  type: boolean
                  description: "include the full package_count (default: `True`)"
                include_extras:
                  type: boolean
                  description: "include the group's extra fields (default: `True`)"
                include_users:
                  type: boolean
                  description: "include the group's users (default: `True` if `ckan.auth.public_user_details` is `True` otherwise `False`)"
                include_groups:
                  type: boolean
                  description: "include the group's sub groups (default `True`)"
                include_tags:
                  type: boolean
                  description: "include the group's tags (default: `True`)"
                include_followers:
                  type: boolean
                  description: "include the group's number of followers (default: `True`)"
  organization_show:
    post:
      operationId: organization_show
      summary: organization_show
      # Original docs typo "a" instead of "an"
      description: Return the details of an organization (only its first 10 datasets are returned).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: the id or name of the organization
                include_datasets:
                  type: boolean
                  description: "include a truncated list of the org's datasets (default: `False`)"
                include_dataset_count:
                  type: boolean
                  description: "include the full package_count (default: `True`)"
                include_extras:
                  type: boolean
                  description: "include the organization's extra fields (default: `True`)"
                include_users:
                  type: boolean
                  description: "include the organization's users (default: `True` if `ckan.auth.public_user_details` is `True` otherwise `False`)"
                include_groups:
                  type: boolean
                  description: "include the organization's sub groups (default `True`)"
                include_tags:
                  type: boolean
                  description: "include the organization's tags (default: `True`)"
                include_followers:
                  type: boolean
                  description: "include the organization's number of followers (default: `True`)"                  
  group_package_show:
    post:
      operationId: group_package_show
      summary: group_package_show
      description: Return the datasets (packages) of a group.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: the id or name of the group
                limit:
                  type: integer
                  description: the maximum number of datasets to return
  tag_show:
    post:
      operationId: tag_show
      summary: tag_show
      description: Return the details of a tag and all its datasets.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: the name or id of the tag
                vocabulary_id:
                  type: string
                  description: the id or name of the tag vocabulary that the tag is in - if it is not specified it will assume it is a free tag
                include_datasets:
                  type: boolean
                  description: "include a list of the tag's datasets (up to a limit of 1000 - for more flexibility, use package_search) (default: `False`)"
  user_show:
    post:
      operationId: user_show
      summary: user_show
      description: |
        Return a user account.
        
        Either the `id` should be passed or the user should be logged in.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: the id or name of the user
                include_datasets:
                  type: boolean
                  description: "include a list of datasets the user has created. If it is the same user or a sysadmin requesting, it includes datasets that are draft or private (default: `False`, limit: 50)"
                include_num_followers:
                  type: boolean
                  description: "include the number of followers the user has (default: `False`)"
                include_password_hash:
                  type: boolean
                  description: "include the stored password hash (sysadmin only, default: `False`)"
                include_plugin_extras:
                  type: boolean
                  description: "include the internal plugin extras object (sysadmin only, default: `False`)"
  status_show:
      get:
        operationId: status_show
        summary: status_show
        description: This endpoint shows information about the CKAN instance.
        x-codeSamples:
          - lang: rust
            label: Rust SDK (ckanaction) example
            source: |
              use dotenvy::dotenv;

              #[tokio::main]
              async fn main() -> Result<(), Box<dyn std::error::Error>> {
                  // Load environment variables from .env file
                  dotenv()?;

                  // Initialize and build CKAN struct
                  let ckan = ckanaction::CKAN::builder()
                      .url("http://localhost:5000")
                      .token(dotenvy::var("CKAN_API_TOKEN")?)
                      .build();

                  // Send request to /status_show and print output
                  let result = ckan.status_show().await?;
                  println!("{result:#?}");

                  Ok(())
              }
  'package_list':
    post:
      operationId: package_list
      summary: package_list
      description: This endpoint lists CKAN resources.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              # required:
              #   - project_uuid
              type: object
              properties:
                limit:
                  type: integer
                  description: if given, the list of datasets will be broken into pages of at most `limit` datasets per page and only one page will be returned at a time
                offset:
                  type: integer
                  description: when limit is given, the offset to start returning packages from
      x-codeSamples:
        - lang: rust
          label: Rust SDK (ckanaction) example
          source: |
            use dotenvy::dotenv;

            #[tokio::main]
            async fn main() -> Result<(), Box<dyn std::error::Error>> {
                // Load environment variables from .env file
                dotenv()?;

                // Initialize and build CKAN struct
                let ckan = ckanaction::CKAN::builder()
                    .url("http://localhost:5000")
                    .token(dotenvy::var("CKAN_API_TOKEN")?)
                    .build();

                // Send request to /package_list and print output
                let result = ckan.package_list()
                    .limit(5) // <-- This is an optional parameter you can remove
                    .call()
                    .await?;
                println!("{result:#?}");

                Ok(())
            }
  'package_search':
    post:
      operationId: package_search
      summary: package_search
      description: |
        Searches for packages satisfying a given search criteria.

        This action accepts Solr search query parameters (details below), and returns a dictionary of results, including dictized datasets that match the search criteria, a search count, and also facet information.

        Solr Parameters:

        For more in depth treatment of each parameter, please read the [Solr Documentation](https://solr.apache.org/guide/6_6/common-query-parameters.html).

        This action accepts a subset of Solr's search query parameters.

        The following advanced Solr parameters are supported as well. Note that some of these are only available on particular Solr versions. See Solr's dismax and edismax documentation for further details on them:

        `qf`, `wt`, `bf`, `boost`, `tie`, `defType`, `mm`

        Examples:

        - `q=flood` datasets containing the word *flood*, *floods*, or *flooding*
        - `fq=tags:economy` datasets with the tag *economy*
        - `facet.field=["tags"] facet.limit=10 rows=0` top 10 tags

        <Callout title="Title" type="error">
        There is an issue for the Body dropdown within this UI where an empty object `{}` is set for the `facet` field.
        
        Please either remove this field by clicking "Open JSON editor" in the Body dropdown or set it to `true` (the default value) or `false`.
        </Callout>
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                q:
                  type: string
                  description: the solr query.
                fq:
                  type: string
                  description: "any filter queries to apply. Note: `+site_id:{ckan_site_id}` is added to this string prior to the query being executed."
                fq_list:
                  type: array
                  items:
                    type: string
                  description: additional filter queries to apply.
                sort:
                  type: string
                  description: "sorting of the search results. Default: 'score desc, metadata_modified desc'. As per the Solr documentation, this is a comma-separated string of field names and sort-orderings."
                rows:
                  type: integer
                  description: "the maximum number of matching rows (datasets) to return. (default: 10, upper limit: 1000 unless set in site's configuration `ckan.search.rows_max`)"
                start:
                  type: integer
                  description: the offset in the complete result for where the set of returned datasets should begin.
                facet:
                  type: boolean
                  description: "whether to enable faceted results. Default: `True`"
                facet.mincount:
                  type: integer
                  description: the minimum counts for facet fields should be included in the results.
                facet.limit:
                  type: integer
                  description: the maximum number of values the facet fields return. A negative value means unlimited. This can be set instance-wide with the [search.facets.limit](https://docs.ckan.org/en/2.11/maintaining/configuration.html#search-facets-limit) config option. Default is 50.
                facet.field:
                  type: array
                  items:
                    type: string
                  description: the fields to facet upon. Default empty. If empty, then the returned facet information is empty.
                include_drafts:
                  type: boolean
                  description: "if `True`, draft datasets will be included in the results. A user will only be returned their own draft datasets, and a sysadmin will be returned all draft datasets. Optional, the default is `False`."
                include_deleted:
                  type: boolean
                  description: "if `True`, deleted datasets will be included in the results (site configuration `ckan.search.remove_deleted_packages` must be set to `False`). Optional, the default is `False`."
                include_private:
                  type: boolean
                  description: "if `True`, private datasets will be included in the results. Only private datasets from the user’s organizations will be returned and sysadmins will be returned all private datasets. Optional, the default is `False`."
                use_default_schema:
                  type: boolean
                  description: "use default package schema instead of a custom schema defined with an IDatasetForm plugin (default: `False`)"
      x-codeSamples:
        - lang: rust
          label: Rust SDK (ckanaction) example
          source: |
            use dotenvy::dotenv;

            #[tokio::main]
            async fn main() -> Result<(), Box<dyn std::error::Error>> {
                // Load environment variables from .env file
                dotenv()?;

                // Initialize and build CKAN struct
                let ckan = ckanaction::CKAN::builder()
                    .url("http://localhost:5000")
                    .token(dotenvy::var("CKAN_API_TOKEN")?)
                    .build();

                // Send request to /package_search and print output
                let result = ckan.package_search()
                    .q("*:*".to_string())
                    .call()
                    .await?;
                println!("{result:#?}");

                Ok(())
            }