CMS API | Blog tags - HubSpot docs

Scope requirements

Use the blog tags API to manage tags for your blog posts. Tags help organize your blog content and make it easier for visitors to find related posts. Learn more about how to create and maintain your blog on the HubSpot Knowledge Base.

Changes in V3

The description property has been deprecated and will not be included in the response of any of the V3 endpoints.

Retrieve blog tags

You can retrieve blog tags either individually by ID or by retrieving all blog tags:

To retrieve all blog tags, make a GET request to /cms/v3/blogs/tags.
To retrieve an individual blog tag, make a GET request to /cms/v3/blogs/tags/{tagId}.

Retrieve all blog tags

When retrieving all blog tags, you can filter and sort the returned results using query parameters. For example, the following request would retrieve the first 10 blog tags created after January 1, 2024:

curl https://api.hubapi.com/cms/v3/blogs/tags?createdAfter=2024-01-01T00:00:00Z&limit=10 \
  --request GET \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"

The following query parameters are available:

Parameter	Type	Description
`after`	String	The paging cursor token of the last successfully read resource. Available from `paging.next.after` in paginated responses.
`archived`	Boolean	Whether to return only results that have been archived. Defaults to `false`.
`createdAfter`	String	Only return blog tags created after this date (ISO 8601 format).
`createdAt`	String	Only return blog tags created at exactly this date (ISO 8601 format).
`createdBefore`	String	Only return blog tags created before this date (ISO 8601 format).
`limit`	Integer	Maximum number of results per page. Default is `100`.
`property`	String	Specify specific properties to return from the tags.
`sort`	String	Specify the order in which the blog tags are returned. Valid fields are `name`, `createdAt` (default), `updatedAt`, `createdBy`, `updatedBy`. Prefix with `-` to reverse the order (e.g., `-createdAt`).
`updatedAfter`	String	Only return blog tags last updated after this date (ISO 8601 format).
`updatedAt`	String	Only return blog tags last updated at exactly this date (ISO 8601 format).
`updatedBefore`	String	Only return blog tags last updated before this date (ISO 8601 format).

The response includes a total count and an array of blog tag objects:

{
  "total": 2,
  "results": [
    {
      "id": "184993428780",
      "name": "Marketing",
      "language": "en",
      "translatedFromId": null,
      "created": "2024-01-15T10:30:00.000Z",
      "updated": "2024-01-15T14:45:00.000Z",
      "deletedAt": null
    },
    {
      "id": "184993428781",
      "name": "Sales",
      "language": "en",
      "translatedFromId": null,
      "created": "2024-01-16T09:00:00.000Z",
      "updated": "2024-01-16T09:00:00.000Z",
      "deletedAt": null
    }
  ],
  "paging": {
    "next": {
      "after": "Mg%3D%3D",
      "link": "https://api.hubspot.com/cms/v3/blogs/tags?after=Mg%3D%3D"
    }
  }
}

Retrieve a single blog tag

To retrieve details for a specific blog tag, make a GET request to /cms/v3/blogs/tags/{tagId}. For example, the request below would retrieve the details for the blog tag with ID 184993428780:

curl https://api.hubapi.com/cms/v3/blogs/tags/184993428780 \
  --request GET \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"

You can optionally include the property query parameter to return only specific properties.

Filtering

You can filter blog tags using query parameters. Provide the property name, followed by two underscore characters, then include the associated operator as a suffix. For example, you can filter the results to only include blog tags where the name property contains the word marketing using the parameter: &name__icontains=marketing. You can include any number of filters as query parameters in the request URL. Filters will be combined as AND criteria (you cannot specify filters as OR). The table below lists the properties that can be filtered on, along with their supported filter types.

Property	Supported filters
`id`	`eq`, `in`
`name`	`eq`, `contains`
`slug`	`eq`
`createdAt`	`eq`, `gt`, `gte`, `lt`, `lte`
`deletedAt`	`eq`, `gt`, `gte`, `lt`, `lte`
`createdById`	`eq`
`updatedById`	`eq`
`language`	`in`, `not_null`
`translatedFromId`	`is_null`, `not_null`

Below are the definitions for each operator.

Filter	Operator
Equals	`eq`
Not equal	`ne`
Contains	`contains`
Contains (case insensitive)	`icontains`
Less than	`lt`
Less than or equal	`lte`
Greater than	`gt`
Greater than or equal	`gte`
Null	`is_null`
Not null	`not_null`
Like	`like`
Not like	`not_like`
Starts with	`startswith`
In	`in`

Filtering for multi-language tags

To filter blog tags based on a multi-language group, you can include one of the query parameters from the table below. For example, to get blog tags from the German variation of your blog, you’d include language__in=de as a query parameter.

Description	Query parameters
Primary blog tag in a multi-language group	`translatedFromId__is_null`
Variation blog tag in a multi-language group	`translatedFromId__not_null`
Blog tag with specific language	`language__in=de`

Languages with locales (e.g., en-us) are not supported with the language filter.

Sorting and paginating

You can provide sorting and pagination options as query parameters. Specify the property name as the value to the sort query parameter to return the blog tags in the natural order of that property. You can reverse the sorting order by including a dash character before the property name (e.g., sort=-createdAt). By combining query parameters for filtering, sorting, and pagination, you can retrieve blog tags that match more advanced search criteria. For example, the request below fetches blog tags that have a language assigned, ordered by the most recently updated, and returns the second page of results:

curl 'https://api.hubapi.com/cms/v3/blogs/tags?sort=-updatedAt&language__not_null&limit=10&after=MTA%3D' \
  --request GET \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"

Create a blog tag

To create a new blog tag, make a POST request to /cms/v3/blogs/tags. For example, the request below would create a new blog tag:

curl https://api.hubapi.com/cms/v3/blogs/tags \
  --request POST \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Marketing Tips",
    "language": "en"
  }'

The following request body parameters are available:

Parameter	Type	Description
`name`	String	The name of the blog tag.
`language`	String	The ISO 639 language code for the tag (e.g., `en`, `de`, `fr`). If not set, the tag is considered global and can be used on all blog posts.

A tag with a language set may only be used on blog posts of the same language. Tags that do not have a language set are considered global and may be used on all blog posts.

Update a blog tag

To update an existing blog tag, make a PATCH request to /cms/v3/blogs/tags/{tagId}. For example, the request below would update the name of a blog tag:

curl https://api.hubapi.com/cms/v3/blogs/tags/184993428780 \
  --request PATCH \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Marketing Strategies"
  }'

The following request body parameters are available:

Parameter	Type	Description
`name`	String	The name of the blog tag.
`language`	String	The ISO 639 language code for the tag.

Delete a blog tag

To delete an existing blog tag, make a DELETE request to /cms/v3/blogs/tags/{tagId}. For example, the request below would delete the blog tag with ID 184993428780:

curl https://api.hubapi.com/cms/v3/blogs/tags/184993428780 \
  --request DELETE \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"

A successful deletion returns a 204 No Content response with no body.

Multi-language management

To help you maintain blog tags across multiple languages, HubSpot’s CMS allows you to group together language variants of the same tag. A tag with a language set may only be used on blog posts of the same language. Tags that do not have a language set are considered global and may be used on all blog posts. To learn more about working with multi-language blog tags, check out this Knowledge Base article.

Create a new language variant

You can create a new language variant for an existing blog tag by making a POST request to the /cms/v3/blogs/tags/multi-language/create-language-variation endpoint.

curl https://api.hubapi.com/cms/v3/blogs/tags/multi-language/create-language-variation \
  --request POST \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "id": "184993428780",
    "name": "Marketing-Tips",
    "language": "de"
  }'

Parameter	Type	Description
`id`	String	The ID of the blog tag to clone.
`name`	String	The name for the new language variant.
`language`	String	The language code of the new variant (e.g., `de`, `fr`, `es`).

Attach a blog tag to an existing multi-language group

You can add a blog tag to an existing multi-language group by making a POST request to the /cms/v3/blogs/tags/multi-language/attach-to-lang-group endpoint.

curl https://api.hubapi.com/cms/v3/blogs/tags/multi-language/attach-to-lang-group \
  --request POST \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "id": "184993428781",
    "language": "de",
    "primaryId": "184993428780"
  }'

Parameter	Type	Description
`id`	String	The ID of the target blog tag to attach.
`language`	String	The language identifier of the blog tag being added.
`primaryId`	String	The ID of the blog tag designated as the primary blog tag in the target multi-language group.

Detach a blog tag from a multi-language group

To detach a blog tag from a multi-language group, make a POST request to /cms/v3/blogs/tags/multi-language/detach-from-lang-group.

curl https://api.hubapi.com/cms/v3/blogs/tags/multi-language/detach-from-lang-group \
  --request POST \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "id": "184993428781"
  }'

Set a new primary language

To change the primary language of a multi-language group, make a PUT request to /cms/v3/blogs/tags/multi-language/set-new-lang-primary:

curl https://api.hubapi.com/cms/v3/blogs/tags/multi-language/set-new-lang-primary \
  --request PUT \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "id": "184993428781"
  }'

Update languages in a multi-language group

To explicitly set new languages for each tag in a multi-language group, make a POST request to /cms/v3/blogs/tags/multi-language/update-languages:

curl https://api.hubapi.com/cms/v3/blogs/tags/multi-language/update-languages \
  --request POST \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "primaryId": "184993428780",
    "languages": {
      "184993428780": "en",
      "184993428781": "de",
      "184993428782": "fr"
    }
  }'

Parameter	Type	Description
`primaryId`	String	The ID of the primary blog tag in the multi-language group.
`languages`	Object	A map of blog tag IDs to their associated language codes.

​Changes in V3

​Retrieve blog tags

​Retrieve all blog tags

​Retrieve a single blog tag

​Filtering

​Filtering for multi-language tags

​Sorting and paginating

​Create a blog tag

​Update a blog tag

​Delete a blog tag

​Multi-language management

​Create a new language variant

​Attach a blog tag to an existing multi-language group

​Detach a blog tag from a multi-language group

​Set a new primary language

​Update languages in a multi-language group

Changes in V3

Retrieve blog tags

Retrieve all blog tags

Retrieve a single blog tag

Filtering

Filtering for multi-language tags

Sorting and paginating

Create a blog tag

Update a blog tag

Delete a blog tag

Multi-language management

Create a new language variant

Attach a blog tag to an existing multi-language group

Detach a blog tag from a multi-language group

Set a new primary language

Update languages in a multi-language group