Last modified: August 22, 2025

Run in Postman

 Use the blog tags API to manage tags for your blog 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.

​
Search blog tags

To retrieve blog tags, make a GET request to /cms/v3/blogs/tags. You can filter and sort the tags returned in the response using the operators and properties below. You can also use the standard filters using the createdAt and updatedAt dates.

​
Filtering

Provide any filters as query parameters in your request by adding 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. All filters are ANDed together. ORing filters is not currently supported. The available filter types are listed below:
OperatorDescription
eqEqual to
neNot equal to
containsContains
icontainsContains (case sensitive)
ltLess than
lteLess than or equal to
gtGreater than
gteGreater than or equal to
is_nullNull
not_nullNot null
likeLike
not_likeNot like
startswithValue starts with
inIn
The table below lists the properties that can be filtered on, along with their supported filter types.
PropertySupported filters
ideq, in
nameeq, contains
slugeq
createdAteq, gt, gte, lt, lte
deletedAteq, gt, gte, lt, lte
createdByIdeq
updatedByIdeq
languagein, not_null
translatedFromIdnull, not_null
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.

​
Please note:

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 paging, 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. Including the limit and offset parameters below returns the second page of results. 
curl
https://api.hubapi.com/cms/v3/blogs/tags?sort=-updatedAt&&language__not_null&limit=10&offset=10 \
  --request POST \
  --header "Content-Type: application/json"

​
Create blog tags

To create a blog tag, make a POST request to /cms/v3/blog/posts and include a JSON payload that represents the blog tag model, as shown in the reference documentation. The name field is required when creating a blog tag. To set the URL of a blog tag listing page, you must include the slug field in your request.

​
Edit blog tags

To update a blog tag, make a PATCH request to /cms/v3/blog/posts/{objectId} where objectId is the ID of the tag you want to update. In your request, include a JSON payload should include the blog tag model, as shown in the reference documentation.

​
Multi-language management

To help you maintain blog tags across multiple languages, HubSpot’s CMS allows you to group together blog tags of language variants of the same content. 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

To create a new language variant for an existing blog tag, make a POST request to /multi-language/create-language-variant and include a JSON payload containing the ID of the blog tag to clone and the language identifier of the new variant.

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

To add a blog tag to an existing multi-language group, make a POST request to the /multi-language/attach-to-lang-group and include a JSON payload containing the ID of the target blog tag, the language identifier of the blog tag being added, and the primaryId 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 remove a blog tag from a multi-language group, make a POST request to /multi-language/detach-from-lang-group and include a JSON payload containing the ID of the target blog tag.