Taxonomy | Documentation | Contentful Docs

Taxonomy endpoints are available on the Content Preview API. The request and response format is identical to the Content Delivery API taxonomy endpoints. Taxonomy data is organization-level and has no draft/published distinction, so the CPA and CDA return identical taxonomy data. The benefit is being able to use a single token type (CPA) when working in a preview context.

Note: Authenticate with a Content Preview API access token. CDA access tokens will not work on the Preview API and will return a 401 error.

Concept

Get a concept

Returns a single concept based on the given identifier.

Concept collection

Get all concepts

Returns all the concepts that exist in a given organization.

Filters

There are following filters available on this endpoint:

Filter	Description
`limit`	Limits the maximum number of concepts returned (per page)
`pageNext`	Pagination cursor from which to return the next page of concepts. Alternatively, just call the url at `pages.next` in the previous response
`pagePrev`	Pagination cursor from which to return the previous page of concepts. Alternatively, just use the full url from `pages.prev` in the previous response
`order`	Returns results ordered by the value specified. Supports `sys.updatedAt`, `sys.createdAt`, `prefLabel`
`conceptScheme`	Return only concepts belonging to the specified concept scheme

Concept Scheme

Get a concept scheme

Returns a single concept scheme based on the given identifier.

Ancestors

Get ancestors of a concept

Returns the ancestors of a concept. By default, only direct parents are returned (depth=1).

Descendants

Get descendants of a concept

Returns the descendants of a concept. By default, only direct children are returned (depth=1).

Concept scheme collection

Get all concept schemes

Returns all the concepts schemes that exist in a given organization.

Taxonomy concepts on entries and assets

Note:

Entry and Asset payloads come with a metadata property. This metadata property has as its value a concepts list. The concept list contains links to all the concepts that exist on the entry or asset.
You can query for entries by their concepts. The search is across content types.

Use the Get an entry endpoint.

Returns a single entry or asset with a metadata property. The metadata property holds a list of taxonomy concepts.

Querying content based on a set of concepts

The query parameter starts with metadata.concepts.sys.id with operator [all].

To retrieve entries or assets that match a set of concepts values, use the Get all entries of a Space endpoint, see example:

/spaces/yadj1kx9rmg0/environments/staging/entries?metadata.concepts.sys.id[all]=3kZdDUXy9n0l2Xi2cq8TPc

Returns a list of entries or assets according to one or more of the specified concept IDs.

Querying content based on one or more concepts

The query parameter starts with metadata.concepts.sys.id with operator [in].

To retrieve entries or assets that match at least one of the specified concepts values, use the Get all entries of a Space endpoint, see example:

/spaces/yadj1kx9rmg0/environments/staging/entries?metadata.concepts.descendants[in]=3kZdDUXy9n0l2Xi2cq8TPc

Returns a list of entries according to the specified set of concept IDs.

Querying content based on one or more concepts and their descendants

The query parameter starts with metadata.concepts.descendants with operator [in].

To retrieve entries or assets that match at least one of the specified concepts values or their descendants, use the Get all entries of a Space endpoint, see example:

/spaces/yadj1kx9rmg0/environments/staging/entries?metadata.concepts.descendants[in]=3kZdDUXy9n0l2Xi2cq8TPc

Returns a list of entries according to the specified set of concept IDs and their descendant concepts.