> For the complete documentation index, see [llms.txt](https://docs.humdata.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.humdata.org/build/hdx-apis/metadata-endpoints/openapi-specification.md).

# OpenAPI specification

`package_search` needs no token for public datasets. Try it with curl or an API client:

{% code overflow="wrap" %}

```
curl "https://data.humdata.org/api/3/action/package_search?q=*:*&rows=5"
```

{% endcode %}

For a GUI, import the [OpenAPI spec](https://raw.githubusercontent.com/OCHA-DAP/hdx-openapi-specs/main/dist/openapi.json) into Postman, Insomnia, Bruno, or Scalar. Add a token only to include private or draft datasets for organizations to which you belong.

## Search datasets

> Search for datasets (packages) using Solr query syntax. Supports filtering, faceting, sorting, and pagination. No authentication required for public data.\
> \
> Pass parameters as query string arguments (GET) or as a JSON body (POST).

```json
{"openapi":"3.1.0","info":{"title":"HDX APIs","version":"2.11.4"},"servers":[{"url":"https://data.humdata.org/api/3/action","description":"HDX Production"}],"security":[{},{"ApiKeyAuthCatalog":[]}],"components":{"securitySchemes":{"ApiKeyAuthCatalog":{"type":"apiKey","in":"header","name":"Authorization","description":"HDX API token. Optional — public dataset search needs no authentication; a token is only required to include private or draft datasets."}},"schemas":{"PackageSearchResponse":{"properties":{"help":{"description":"URL to the API documentation for this action.","title":"Help","type":"string"},"success":{"description":"Whether the request succeeded.","title":"Success","type":"boolean"},"result":{"$ref":"#/components/schemas/PackageSearchResult"}},"required":["help","success","result"],"title":"PackageSearchResponse","type":"object"},"PackageSearchResult":{"properties":{"count":{"description":"Total number of datasets matching the query.","title":"Count","type":"integer"},"results":{"description":"List of matching dataset objects.","items":{"additionalProperties":true,"type":"object"},"title":"Results","type":"array"},"sort":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Sort string echoed from the request.","title":"Sort"},"facets":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Legacy facet counts. Prefer `search_facets`.","title":"Facets"},"search_facets":{"additionalProperties":true,"description":"Facet counts keyed by field name. Each entry has a `title` and an `items` list of `{name, display_name, count}` objects.","title":"Search Facets","type":"object"},"facet_pivot":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Pivot facet results, if requested.","title":"Facet Pivot"},"facet_queries":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Facet query results, if requested.","title":"Facet Queries"},"expanded":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Expanded results, if requested.","title":"Expanded"}},"required":["count","results","search_facets"],"title":"PackageSearchResult","type":"object"},"ErrorResponse":{"properties":{"success":{"default":false,"description":"Always false for error responses.","title":"Success","type":"boolean"},"error":{"additionalProperties":true,"description":"Error detail object. Always contains a '__type' string. 403/404 errors include a 'message'; validation (409) errors instead carry structured 'query'/'info' fields.","title":"Error","type":"object"}},"required":["error"],"title":"ErrorResponse","type":"object"}}},"paths":{"/package_search":{"get":{"operationId":"package_search_get","summary":"Search datasets","description":"Search for datasets (packages) using Solr query syntax. Supports filtering, faceting, sorting, and pagination. No authentication required for public data.\n\nPass parameters as query string arguments (GET) or as a JSON body (POST).","tags":["Catalog"],"parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"*:*","title":"Q"},"description":"Solr search query. Supports Solr syntax. Defaults to `\"*:*\"` (all datasets)."},{"name":"fq","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Fq"},"description":"Solr filter query. Restricts results without affecting relevance scoring."},{"name":"fq_list","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Fq List"},"description":"Additional filter queries as a list. Each entry is ANDed with `fq`."},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"score desc, metadata_modified desc","title":"Sort"},"description":"Sort order as a Solr sort string. Defaults to `\"score desc, metadata_modified desc\"`."},{"name":"rows","in":"query","required":false,"schema":{"anyOf":[{"maximum":1000,"minimum":0,"type":"integer"},{"type":"null"}],"default":10,"title":"Rows"},"description":"Maximum number of datasets to return. Defaults to `10`, maximum `1000`."},{"name":"start","in":"query","required":false,"schema":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"title":"Start"},"description":"Offset into the result set. Used for pagination."},{"name":"facet","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"true","title":"Facet"},"description":"Enable faceted results. Defaults to `\"true\"`."},{"name":"facet.mincount","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Facet.Mincount"},"description":"Minimum count for a facet value to be included in the response."},{"name":"facet.limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":50,"title":"Facet.Limit"},"description":"Maximum number of values returned per facet field. Defaults to `50`."},{"name":"facet.field","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Facet.Field"},"description":"Fields to facet on."},{"name":"include_drafts","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"title":"Include Drafts"},"description":"Include draft datasets in results. Requires authentication as the owning user or org admin. Defaults to `false`."},{"name":"include_deleted","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"title":"Include Deleted"},"description":"Include deleted datasets in results. Defaults to `false`."},{"name":"include_private","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"title":"Include Private"},"description":"Include private datasets in results. Requires authentication as a member of the owning organisation. Defaults to `false`."},{"name":"use_default_schema","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"title":"Use Default Schema"},"description":"Return results using the default package schema rather than any custom schema configured on the instance. Defaults to `false`."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageSearchResponse"}}}},"403":{"description":"Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found — the requested action or endpoint does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests — rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error — unexpected server-side failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Search datasets (POST)

> Identical to the GET form. Use POST to pass parameters as a JSON body, which is useful for long \`fq\_list\` or \`facet.field\` values.

```json
{"openapi":"3.1.0","info":{"title":"HDX APIs","version":"2.11.4"},"servers":[{"url":"https://data.humdata.org/api/3/action","description":"HDX Production"}],"security":[{},{"ApiKeyAuthCatalog":[]}],"components":{"securitySchemes":{"ApiKeyAuthCatalog":{"type":"apiKey","in":"header","name":"Authorization","description":"HDX API token. Optional — public dataset search needs no authentication; a token is only required to include private or draft datasets."}},"schemas":{"PackageSearchParams":{"properties":{"q":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"*:*","description":"Solr search query. Supports Solr syntax. Defaults to `\"*:*\"` (all datasets).","title":"Q"},"fq":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Solr filter query. Restricts results without affecting relevance scoring.","title":"Fq"},"fq_list":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Additional filter queries as a list. Each entry is ANDed with `fq`.","title":"Fq List"},"sort":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"score desc, metadata_modified desc","description":"Sort order as a Solr sort string. Defaults to `\"score desc, metadata_modified desc\"`.","title":"Sort"},"rows":{"anyOf":[{"maximum":1000,"minimum":0,"type":"integer"},{"type":"null"}],"default":10,"description":"Maximum number of datasets to return. Defaults to `10`, maximum `1000`.","title":"Rows"},"start":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Offset into the result set. Used for pagination.","title":"Start"},"facet":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"true","description":"Enable faceted results. Defaults to `\"true\"`.","title":"Facet"},"facet.mincount":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Minimum count for a facet value to be included in the response.","title":"Facet.Mincount"},"facet.limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum number of values returned per facet field. Defaults to `50`.","title":"Facet.Limit"},"facet.field":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Fields to facet on.","title":"Facet.Field"},"include_drafts":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Include draft datasets in results. Requires authentication as the owning user or org admin. Defaults to `false`.","title":"Include Drafts"},"include_deleted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Include deleted datasets in results. Defaults to `false`.","title":"Include Deleted"},"include_private":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Include private datasets in results. Requires authentication as a member of the owning organisation. Defaults to `false`.","title":"Include Private"},"use_default_schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Return results using the default package schema rather than any custom schema configured on the instance. Defaults to `false`.","title":"Use Default Schema"}},"title":"PackageSearchParams","type":"object"},"PackageSearchResponse":{"properties":{"help":{"description":"URL to the API documentation for this action.","title":"Help","type":"string"},"success":{"description":"Whether the request succeeded.","title":"Success","type":"boolean"},"result":{"$ref":"#/components/schemas/PackageSearchResult"}},"required":["help","success","result"],"title":"PackageSearchResponse","type":"object"},"PackageSearchResult":{"properties":{"count":{"description":"Total number of datasets matching the query.","title":"Count","type":"integer"},"results":{"description":"List of matching dataset objects.","items":{"additionalProperties":true,"type":"object"},"title":"Results","type":"array"},"sort":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Sort string echoed from the request.","title":"Sort"},"facets":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Legacy facet counts. Prefer `search_facets`.","title":"Facets"},"search_facets":{"additionalProperties":true,"description":"Facet counts keyed by field name. Each entry has a `title` and an `items` list of `{name, display_name, count}` objects.","title":"Search Facets","type":"object"},"facet_pivot":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Pivot facet results, if requested.","title":"Facet Pivot"},"facet_queries":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Facet query results, if requested.","title":"Facet Queries"},"expanded":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Expanded results, if requested.","title":"Expanded"}},"required":["count","results","search_facets"],"title":"PackageSearchResult","type":"object"},"ErrorResponse":{"properties":{"success":{"default":false,"description":"Always false for error responses.","title":"Success","type":"boolean"},"error":{"additionalProperties":true,"description":"Error detail object. Always contains a '__type' string. 403/404 errors include a 'message'; validation (409) errors instead carry structured 'query'/'info' fields.","title":"Error","type":"object"}},"required":["error"],"title":"ErrorResponse","type":"object"}}},"paths":{"/package_search":{"post":{"operationId":"package_search_post","summary":"Search datasets (POST)","description":"Identical to the GET form. Use POST to pass parameters as a JSON body, which is useful for long `fq_list` or `facet.field` values.","tags":["Catalog"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageSearchParams"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageSearchResponse"}}}},"403":{"description":"Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found — the requested action or endpoint does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests — rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error — unexpected server-side failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.humdata.org/build/hdx-apis/metadata-endpoints/openapi-specification.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.