> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://contentful.com/developers/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/developers/docs/_mcp/server. > **Info** > > 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](/references/content-management-api/taxonomy/get-a-concept) [Update a concept](/references/content-management-api/taxonomy/update-a-concept) Update a single concept using [JSON Patch](http://jsonpatch.com/) format. When patching a concept, you need to specify the current version of the concept you are updating with `X-Contentful-Version`. > **Info** > > 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. ```js // may result in a validation error if `note` field is undefined: [{"op": "add", "path": "/note/en-US", "value": "Some note"}] // if the `note` field is undefined, provide the locale in the payload: [{"op": "add", "path": "/note", "value": {"en-US": "Some note"}}] ``` [Delete a concept](/references/content-management-api/taxonomy/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](/references/content-management-api/taxonomy/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](/references/content-management-api/taxonomy/create-a-concept-with-user-defined-id) ## Concept collection Return a list of taxonomy concepts for an organization. [Get concepts](/references/content-management-api/taxonomy/get-concepts) #### 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 | | `query` | Filter results using a full-text search query, looking at `prefLabel`, `altLabels`, `hiddenLabels` and `notations` fields | | `sys.id[in]` | Return only the concepts matching the given comma-separated list of concept IDs | ## Descendants Return a taxonomy concept's list of descendants. [Get descendants of a concept](/references/content-management-api/taxonomy/get-descendants-of-a-concept) ## Ancestors Return a taxonomy concept's list of ancestors. [Get ancestors of a concept](/references/content-management-api/taxonomy/get-ancestors-of-a-concept) ## Total concepts Return the number of taxonomy concepts in an organization. [Get number of concepts](/references/content-management-api/taxonomy/get-number-of-concepts) ## Concept scheme Return a single a taxonomy concept scheme. [Get a concept scheme](/references/content-management-api/taxonomy/get-a-concept-scheme) [Update a concept scheme](/references/content-management-api/taxonomy/update-a-concept-scheme) Update a single concept scheme using [JSON Patch](http://jsonpatch.com/) format. When patching a concept scheme, you need to specify the current version of the concept scheme you are updating with `X-Contentful-Version`. > **Info** > > 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. ```js // may result in a validation error if `definition` field is undefined: [{"op": "add", "path": "/definition/en-US", "value": "Some definition"}] // if the `definition` field is undefined, provide the locale in the payload: [{"op": "add", "path": "/definition", "value": {"en-US": "Some definition"}}] ``` [Delete a concept scheme](/references/content-management-api/taxonomy/delete-a-concept-scheme) ## Create a concept scheme Creates a new taxonomy concept scheme. [Create a concept scheme](/references/content-management-api/taxonomy/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](/references/content-management-api/taxonomy/create-a-concept-scheme-with-user-defined-id) ## Concept scheme collection Return a list of taxonomy concept schemes. [Get concept schemes](/references/content-management-api/taxonomy/get-concept-schemes) ## Total concept schemes Return the number of taxonomy concept schemes in an organization. [Get number of concept schemes](/references/content-management-api/taxonomy/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](/references/content-management-api/entries/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](/references/content-management-api/entries/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](/references/content-management-api/entries/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](/references/content-management-api/content-types) 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](/references/content-management-api/entries/create-an-entry-with-a-specified-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](/references/content-management-api/assets) 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.