DataCite REST API: Facets ("meta") Default Change

What’s changing

By default, requests to the /dois endpoint will no longer include the facets under the "meta" attribute. To retrieve facets, requests must include the URL parameter disable-facets=false. This change will take effect on 1 March 2026.

Why are we making this change?

The meta attribute of the DataCite REST API /dois endpoint currently displays a set of facets (aggregations) about a result set by default. These include attributes like resourceTypes, created, and affiliations. Learn more about what is currently included in the meta attribute here: Retrieving a list of DOIs - What’s in the API response?

As the DataCite Metadata Store has grown, these facets have become less performant, slowing down common REST API use cases like querying DOI metadata and harvesting DOI metadata records.

To better support these important REST API activities, facets will no longer be returned by default. If needed, facets can be easily re-enabled using a disable-facets=false URL parameter.

The total, totalPages, and page attributes will continue to be returned for every /dois list request.

How to update your requests

To continue retrieving the "meta" facets

If you are using facet information from the "meta" section of the response, we recommend updating your REST API requests to include disable-facets=false as soon as possible. This will ensure a smooth transition when we change the default behaviour.

To exclude the "meta" facets

If you are not using facet information from the "meta" section of the response, no change is required.

If you prefer, you can add the parameter disable-facets=true to your requests now. This will ensure there is no change to the response when we change the default to match. It may also improve API response times. (For more information, see How can I make my DOI list query more efficient when using the REST API?)