Tags

Tags help you to easily search for specific content in your environment.

Tags are environment-scoped which means that they exist within and are unique to an environment.

Only tags with visibility public are accessible via the delivery and preview APIs. To learn more about the different tag visibility options, see the tags visibility documentation in the management api reference page.

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 public that makes the tag accessible via the delivery and preview API

Tag Collection

Get all tags

Returns all the tags that exist in a given environment.

Tag

Get a tag

Returns a single tag based on the given identifier.

Tags on entries and 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.

Get an entry

Returns an entry with a metadata property. The metadata property holds a list of tags.

The same behavior applies for assets.

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, see example:

/spaces/yadj1kx9rmg0/environments/staging/entries?access_token=f0aa56e3659d58947f8e3ddd6301c9591c9b73a8b54c35435233b18b3e6752d5&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, see example:

/spaces/yadj1kx9rmg0/environments/staging/entries?access_token=f0aa56e3659d58947f8e3ddd6301c9591c9b73a8b54c35435233b18b3e6752d5&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, see example:

/spaces/yadj1kx9rmg0/environments/staging/entries?access_token=f0aa56e3659d58947f8e3ddd6301c9591c9b73a8b54c35435233b18b3e6752d5&metadata.tags[exists]=true

Returns all entries that are assigned with tags.

This parameter value must be one of “true” or “false”; it is case sensitive, so “True” or “False” are not valid values.