Content Management API

Tags

Tags are assigned to entries and assets to group them in your environment. Tags help you to easily search and organize content.

Tags are environment-scoped which means that they exist within and are unique to an environment. All tags are available via the Content Management API.

To learn how to use tags in the web app, please refer to our Tags category in our Help Center.


A tag includes the following properties:

  • name: A human-readable unique identifier for the tag
  • id: A unique identifier for referencing the tag
  • visibility: A sys property with value of public or private that determines if a tag is publicly accessible or not

Note: Only space admins and users with permission to manage tags can create and manage tags.

Tag visibility

There are two visibility options for Tags:

  • private: Tags with this visibility option are only available via the Content Management API to all users with relevant permissions within the space. This is the default visibility.
  • public: Tags with this visibility option are available via all our APIs (CDA, CMA and CPA).
1{
2    "name": "Tag Name",
3    "sys": {
4        "visibility": "public | private", // The new visibility property
5        "id": "TagID",
6        ... // Other sys properties
7    }
8}

Note: The tag visibility cannot be changed after the tag is created.

Tag collection

Get all tags

Returns all the tags that exist in a given environment.

Tag

Create a tag

Creates a new tag and returns it.

Note:

  • Both name and ID must be unique to each environment. Tag names can be modified after creation, but the tag ID cannot.
  • The tag visibility can be set in the header with X-Contentful-Tag-Visibility. The visibility value set in the header overrides that in the payload.
  • The tag visibility is set to private if there’s no visibility specified in the payload or the header.

Get a tag

Returns a single tag based on the given identifier.

To update a tag, use the Create a tag endpoint with the ID of the tag you want to update. Returns an updated tag.

Delete a tag

Deletes a tag from the entries and/or assets that reference it.

Querying tags

Tags can be queried by the name, ID sys.id or visibility sys.visibility of the tag.

To query tag by visibility, use the Get all tags endpoint with query parameters like sys.visibility=public. Returns all tags that have the same visibility type.

Tags on entries and assets

Once a tag is created in an environment, users can add the tag to entries and/or assets within that environment. They can also remove the tag from the entries and/or assets.

Note:

  • Entries and assets payload come with a metadata property. This metadata property has as its value a tags list. The tags list contains links to all the tags that exist on the entry or asset.
  • You can query for entries and assets by their tags. For entries, the search is across content types.

Use the Create an entry with ID or Create or update an asset endpoints to add or remove tags from entries and assets by updating the metadata.tags property. When a tag is added, it returns a specified entry with a new metadata property. The metadata property holds the list of tags added. When a tag is removed, if no other tags exist on the entry, the metadata property will hold an empty list of tags.

Querying content based on a set of tags

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

To retrieve entries or assets that match a specific set of tag values, use the Get all entries of a space endpoint with query parameter: metadata.tags.sys.id[all]=tagA,tagB.

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

Querying content based on one or more tags

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

To retrieve entries or assets that match at least one of the specified tag values, use the Get all entries of a space endpoint with query parameter: metadata.tags.sys.id[in]=tagA,tagB.

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

Querying content based on the tag presence

The query parameter starts with metadata.tags with operator [exists].

To check the presence of a tag on entries or assets, use the Get all entries of a space endpoint with query parameter: metadata.tags[exists]=true.

Returns all entries that are assigned with tags.

This parameter value is case sensitive: “True” or “False” are not valid values.