Content Management API

Taxonomy

Taxonomy’s infrastructure is not a dedicated infrastructure because it doesn’t rely on reserved capacity specifically for storing, indexing, and delivering content for a single customer. Instead, it operates within a shared or multi-tenant environment, organizing content across various entities without the need for exclusive infrastructure.

Concept

Return, update or delete a single concept.

Get a concept

Update a concept

Update a single concept using JSON Patch format. When patching a concept, you need to specify the current version of the concept you are updating with X-Contentful-Version.

JSON Patch cannot perform operations on non-existent fields. If a field has not been set on the concept yet, the API will return a validation error when you try to perform an operation on this field. The accepted workaround is to pass the entire sub-object to the top-most existing field.
1// may result in a validation error if `note` field is undefined:
2[{"op": "add", "path": "/note/en-US", "value": "Some note"}]
3
4// if the `note` field is undefined, provide the locale in the payload:
5[{"op": "add", "path": "/note", "value": {"en-US": "Some note"}}]

Delete a concept

Deleting concepts does not remove existing references to them in content type validations, or entries.

Create a concept

Create a single taxonomy concept.

Create a concept

Create a concept with user-defined ID

Creates a single taxonomy concept with a user-defined ID.

Create a concept with user-defined ID

Concept collection

Return a list of taxonomy concepts for an organization.

Get concepts

Filters

There are following filters available on this endpoint:

FilterDescription
limitLimits the maximum number of concepts returned (per page)
pageNextPagination cursor from which to return the next page of concepts. Alternatively, just call the url at pages.next in the previous response
pagePrevPagination cursor from which to return the previous page of concepts. Alternatively, just use the full url from pages.prev in the previous response
orderReturns results ordered by the value specified. Supports sys.updatedAt, sys.createdAt, prefLabel
conceptSchemeReturn only concepts belonging to the specified concept scheme
queryFilter results using a full-text search query, looking at prefLabel, altLabels, hiddenLabels and notations fields

Descendants

Return a taxonomy concept’s list of descendants.

Get descendants of a concept

Ancestors

Return a taxonomy concept’s list of ancestors.

Get ancestors of a concept

Total concepts

Return the number of taxonomy concepts in an organization.

Get number of concepts

Concept scheme

Return a single a taxonomy concept scheme.

Get a concept scheme

Update a concept scheme

Update a single concept scheme using JSON Patch format. When patching a concept scheme, you need to specify the current version of the concept scheme you are updating with X-Contentful-Version.

JSON Patch cannot perform operations on non-existent fields. If a field has not been set on the concept scheme yet, the API will return a validation error when you try to perform an operation on this field. The accepted workaround is to pass the entire sub-object to the top-most existing field.
1// may result in a validation error if `definition` field is undefined:
2[{"op": "add", "path": "/definition/en-US", "value": "Some definition"}]
3
4// if the `definition` field is undefined, provide the locale in the payload:
5[{"op": "add", "path": "/definition", "value": {"en-US": "Some definition"}}]

Delete a concept scheme

Create a concept scheme

Creates a new taxonomy concept scheme.

Create a concept scheme

Create a concept scheme with user-defined ID

Creates a new taxonomy concept scheme with a user-defined ID.

Create a concept scheme with user-defined ID

Concept scheme collection

Return a list of taxonomy concept schemes.

Get concept schemes

Total concept schemes

Return the number of taxonomy concept schemes in an organization.

Get number of concept schemes

Querying content based on a set of concepts

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

To retrieve entries that match a set of concepts values, use the Get all entries of a space endpoint with query parameter: metadata.concepts.sys.id[all]=conceptA,conceptB

Returns a list of entries 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 that match at least one of the specified concepts values, use the Get all entries of a space endpoint with query parameter: metadata.concepts.sys.id[in]=conceptA,conceptB

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 that match at least one of the specified concepts values or their descendants, use the Get all entries of a space endpoint with query parameter: metadata.concepts.descendants[in]=conceptA,conceptB

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

Taxonomy on content types

Once a concept or concept scheme is created on the organization, users can define taxonomy validations on content types within an environment. This allows users to assign/change or remove concepts on entries.

Note:

  • Content types payload comes with a metadata property. This metadata property has as its value a taxonomy list. The taxonomy list contains links to all the concepts and concept schemes assigned to that content type.

Use the Create a content type with PUT endpoint to add or remove concepts or concept schemes from a content type by updating the metadata.taxonomy property.

Returns a specified content type with a new metadata property. The metadata property holds the list of concepts added.

Concepts on entries

Once a concept or concept scheme has been assigned to a content type within an environment, users can assign/remove concepts on entries.

Note:

  • Entries payload come with a metadata property. This metadata property has as its value a concepts list. The concepts list contains links to all the concepts assigned to that entry.
  • You can query for entries by their concepts. For entries, the search is across content types.
  • Concept assignment is not localized. A concept is assigned once in metadata.concepts and applies to the entry across all of its locales — there is no per-locale assignment. A concept’s localized labels (prefLabel, altLabels, notes, and so on) live on the concept itself, so all of a concept’s translations are available automatically once it is assigned. You do not need to change the active locale to assign a localized concept.

Use the Create an entry with ID endpoint to add or remove concepts from an entry by updating the metadata.concepts property.

Returns a specified entry with a new metadata property. The metadata property holds the list of concepts added.

Concepts on assets

Once a concept has been created, users can assign/remove concepts on assets.

Note:

  • Assets payload come with a metadata property. This metadata property has as its value a concepts list. The concepts list contains links to all the concepts assigned to that entry.
  • You can query for assets by their concepts.
  • Concept assignment is not localized. A concept is assigned once in metadata.concepts and applies to the asset across all of its locales — there is no per-locale assignment. A concept’s localized labels (prefLabel, altLabels, notes, and so on) live on the concept itself, so all of a concept’s translations are available automatically once it is assigned.

Use the Create an asset with ID endpoint to add or remove concepts from an asset by updating the metadata.concepts property.

Returns a specified asset with a new metadata property. The metadata property holds the list of concepts added.