> 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.

Taxonomy endpoints are available on the Content Preview API. The request and response format is identical to the [Content Delivery API taxonomy endpoints](/references/content-delivery-api/overview). 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.

> **Info**
>
> **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](/references/content-preview-api/taxonomy/get-a-concept)

Returns a single concept based on the given identifier.

## Concept collection

[Get all concepts](/references/content-preview-api/taxonomy/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](/references/content-preview-api/taxonomy/get-a-concept-scheme)

Returns a single concept scheme based on the given identifier.

## Ancestors

### Get ancestors of a concept

[Get ancestors of a concept](/references/content-preview-api/taxonomy/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

[Get descendants of a concept](/references/content-preview-api/taxonomy/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](/references/content-preview-api/taxonomy/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.
* Taxonomy concepts are assigned at the entry or asset level and are not localized — the `metadata.concepts` links are the same regardless of the locale you request the entry or asset in. A concept's localized labels (`prefLabel`, `altLabels`, and so on) live on the concept itself; retrieve them from the taxonomy concept endpoints above.

Use the [Get an entry](/references/content-preview-api/entries/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](/references/content-preview-api/entries/get-all-entries) 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](/references/content-preview-api/entries/get-all-entries) 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](/references/content-preview-api/entries/get-all-entries) 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.