ckanaction/docs/lib/openapi.yml

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`)"
  '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_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
                  default: ""
                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(())
            }
  '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(())
            }