Blog topics
This is a stable API but uses an older format. This means some functionality may not be available (for example test calls and Postman integration).
Use the blog topics API to create and manage blog topics in a HubSpot account.
Retrieve all blog tags as a part of a content audit, then update and merge specific tags to support an upcoming company rebrand.
/blogs/v3/topics
List all blog topics. Supports paging and filtering.
Some parameters support "range" filters via double-underscored param suffixes, like __gt
. If a parameter supports a filter type of 'gt', that means you can append a double-underscore and 'gt' to the parameter name to find all items greater than a specified value.
For example, the following query will find all items with the 'updated' time greater than 1364424600000: https://api.hubapi.com/blogs/v3/topics?created__gt=1364424600000
Requirements
Parameters
Search for topics by id. Supports exact value matching and the 'in' range filter (e.g. id__in=348109009,348109019
)
Search for topics by name. Supports exact value matching, 'contains'
searching, and 'icontains' case-insensitive searching (e.g.
name__contains=topic1
)
Search for topics by slug. Supports exact value matching
Filter results by creation date, in milliseconds since the epoch. Supports exact value matching and the following range filters: range, gt, gte, lt, lte
The maximum number of items to return. Defaults to 20.
The offset from the beginning of the result set from which to start returning results. Used for paging. Defaults to 0.
Use the casing=snake parameter to change the API's casing for all query parameters (including those above) and JSON fields (below) to snake_case, rather than camelCase, which is the default. This option is provided for backwards-compatibility and ease of migration from Content v2 APIs, which used snake_case.
Response
<h3>Example GET URL</h3>
<a href="https://api.hubapi.com/blogs/v3/topics" target="_blank">https://api.hubapi.com/blogs/v3/topics</a>
Example GET response:
{
"objects": [
{
"id": 349001328,
"portalId": 62515,
"name": "api-docs",
"slug": "api-docs",
"description": "",
"created": 1381896200000,
"updated": 1381896200000,
"deletedAt": 0
},
{
"id": 447332568,
"portalId": 62515,
"name": "Test Topic 20140110160733",
"slug": "test-topic-20140110160733",
"description": "",
"created": 1389388053000,
"updated": 1389388053000,
"deletedAt": 0
},
{
"id": 450113517,
"portalId": 62515,
"name": "Test",
"slug": "test",
"description": "",
"created": 1389387669000,
"updated": 1389387669000,
"deletedAt": 0
JSON Fields returned in the response
Field name | Type | Description |
---|---|---|
id | long | The unique id of the topic |
portalId | int | The hub id |
created | long | When the topic was first created, in milliseconds since the epoch |
updated | long | When the topic was last updated, in milliseconds since the epoch |
deletedAt | long | When the topic was deleted, in milliseconds since the epoch. Zero if the topic was never deleted. Use a DELETE request to properly soft delete a topic - do not set this value directly. |
name | string | The topic name |
slug | string | The URL-friendly version of the topic, used in blog urls |
description | string | The topic description |
/blogs/v3/topics/search
Search for blog topics by various criteria. See the options below for details about filtering. Supports paging for the case where a large number of topics match the criteria.
Some parameters support "range" filters via double-underscored param suffixes, like __gt
. If a parameter supports a filter type of 'gt', that means you can append a double-underscore and 'gt' to the parameter name to find all items greater than a specified value.
For example, the following query will find all items with the 'updated' time greater than 1364424600000: https://api.hubapi.com/blogs/v3/topics/search?created__gt=1364424600000
Requirements
Parameters
Search for topics by id. Supports exact value matching and the 'in' range filter (e.g. id__in=348109009,348109019
)
Search for topics by name. Supports exact value matching, 'contains' searching, and 'icontains' case-insensitive searching (e.g. name__contains=topic1
)
Search for topics by slug. Supports exact value matching
Filter results by creation date, in milliseconds since the epoch. Supports exact value matching and the following range filters: range, gt, gte, lt, lte
The maximum number of items to return. Defaults to 100.
The offset from the beginning of the result set from which to start returning results. Used for paging. Defaults to 0.
Use the casing=snake parameter to change the API's casing for all query parameters (including those above) and JSON fields (below) to snake_case, rather than camelCase, which is the default. This option is provided for backwards-compatibility and ease of migration from Content v2 APIs, which used snake_case.
Search for topics whose names or url slugs contain the given string.
Filter topics by whether or not they are associated with any published blog posts (true or false).
Filter topics by a blog they are used on (value is a blog ID).
Response
xxxxxxxxxx
Example GET request:
href="https://api.hubapi.com/blogs/v3/topics/search?created__gt=1435000911000" target="_blank">https://api.hubapi.com/blogs/v3/topics/search?created__gt=1435000911000
Example response:
<block>
{
"limit": 100,
"objects": [
{
"associatedBlogIds": [
],
"created": 1435001222059,
"deletedAt": 0,
"description": "tester9",
"id": 2986692016,
"livePosts": 0,
"name": "tester9",
"portalId": 62515,
"slug": "tester9",
"status": "inactive",
"totalPosts": 0,
"updated": 1435001222059
},
{
"associatedBlogIds": [
],
"created": 1435000911447,
"deletedAt": 0,
"description": "tester7",
"id": 3002998727,
"livePosts": 0,
"name": "tester7",
JSON Fields returned in the response
Field name | Type | Description |
---|---|---|
id | long | The unique id of the topic |
portalId | int | The hub id |
created | long | When the topic was first created, in milliseconds since the epoch |
updated | long | When the topic was last updated, in milliseconds since the epoch |
deletedAt | long | When the topic was deleted, in milliseconds since the epoch. Zero if the topic was never deleted. Use a DELETE request to properly soft delete a topic - do not set this value directly. |
name | string | The topic name |
slug | string | The URL-friendly version of the topic, used in blog urls |
description | string | The topic description |
totalPosts | int | The total count of posts (including drafts) associated with this topic. |
livePosts | int | The total count of published posts associated with this topic. |
lastUsed | long | The most recent publish date of a blog post associated with this topic, in milliseconds since the epoch. |
associatedBlogIds | array | A list of the blog IDs where this topic has been used. |
/blogs/v3/topics/:topic-id
Get the details for a specific topic by its ID.
Requirements
Parameters
Unique identifier for a particular topic
Use the casing=snake parameter to change the API's casing for returned JSON fields (below) to snake_case, rather than camelCase, which is the default. This option is provided for backwards-compatibility and ease of migration from Content v2 APIs, which used snake_case.
Response
xxxxxxxxxx
<h3>Example GET URL:</h3>
<a href="https://api.hubapi.com/blogs/v3/topics/349001328" target="_blank">https://api.hubapi.com/blogs/v3/topics/349001328</a>
Example GET response:
{
"id": 349001328,
"portalId": 62515,
"name": "api-docs",
"slug": "api-docs",
"description": "",
"created": 1381896200000,
"updated": 1381896200000,
"deletedAt": 0,
"totalPosts": null,
"livePosts": null,
"lastUsed": null,
"associatedBlogIds": [
],
"publicUrl": null,
"status": "inactive"
}
JSON Fields returned in the response
Field name | Type | Description |
---|---|---|
id | string | The unique id of the topic |
portalId | string | The hub id |
created | long | When the topic was first created, in milliseconds since the epoch |
updated | long | When the topic was last updated, in milliseconds since the epoch |
deletedAt | long | When the topic was deleted, in milliseconds since the epoch. Zero if the topic was never deleted. Use a DELETE request to properly soft delete a topic - do not set this value directly. |
name | string | The topic name |
slug | string | The URL-friendly version of the topic, used in blog urls |
description | string | The topic description |
/blogs/v3/topics
Create a new blog topic.
Requirements
Parameters
Use the casing=snake parameter to change the API's casing for allowed JSON fields (below) to snake_case, rather than camelCase, which is the default. This option is provided for backwards-compatibility and ease of migration from Content v2 APIs, which used snake_case.
The topic name
The topic description
Response
xxxxxxxxxx
<h3>Example POST URL:</h3>
<a href="https://api.hubapi.com/blogs/v3/topics" target="_blank">https://api.hubapi.com/blogs/v3/topics</a>
<p>Example POST body:</p>
{
"name": "Hey A New Topic",
"description": "This is a topic description"
}
<p>Example POST response:</p>
HTTP/1.1 201 Created
{
"id": 349001123123123,
"portalId": 62515,
"name": "Hey a new topic",
"slug": "hey-a-new-topic",
"description": "This is a topic description",
"created": 1381896200000,
"updated": 1381896200000,
"deletedAt": 0,
"totalPosts": null,
"livePosts": null,
"lastUsed": null,
"associatedBlogIds": [
],
"publicUrl": null,
"status": "inactive"
}
/blogs/v3/topics/group-topics
Merge multiple topics by ID into a single topic group.
Requirements
Parameters
Use the casing=snake parameter to change the API's casing for allowed JSON fields (below) to snake_case, rather than camelCase, which is the default. This option is provided for backwards-compatibility and ease of migration from Content v2 APIs, which used snake_case.
The new name of the combined topics
The List of topic ids to merge
Response
xxxxxxxxxx
<h3>Example POST URL:</h3>
<a href="https://api.hubapi.com/blogs/v3/topics/group-topics" target="_blank">https://api.hubapi.com/blogs/v3/topics/group-topics</a>
Example POST body:
{
"groupedTopicName": "Merged Topic",
"topicIds":[123456,789012,345678]
}
Example POST response:
HTTP/1.1 200 OK
{
"topicIds":[123456,789012,345678],
"groupedTopicName":"Merged Topic",
"portalId":62515
}
/blogs/v3/topics/:topic-id
Update an existing blog topic.
Requirements
Parameters
Unique identifier for a particular topic
Use the casing=snake parameter to change the API's casing for returned JSON fields (below) to snake_case, rather than camelCase, which is the default. This option is provided for backwards-compatibility and ease of migration from Content v2 APIs, which used snake_case.
The topic name
The topic description
Response
xxxxxxxxxx
<h3>Example Usage and Result</h3>
<p class="method-url">Hit this URL with a HTTP method of PUT
<a href="https://api.hubapi.com/blogs/v3/topics/349001123123123" target="_blank">https://api.hubapi.com/blogs/v3/topics/349001123123123</a></p>
<p>and including a request body of:</p>
<block>
{
"name": "Hey an updated Topic",
"description": "This is an updated topic description"
}
</block>
<p>This returns a response like:</p>
<block>
HTTP/1.1 200 OK
{
"id": 349001123123123,
"portalId": 62515,
"name": "Hey an updated topic",
"slug": "hey-an-updated-topic",
"description": "This is an updated topic description",
"created": 1381896200000,
"updated": 1381896200000,
"deletedAt": 0,
"totalPosts": null,
"livePosts": null,
"lastUsed": null,
"associatedBlogIds": [
],
"publicUrl": null,
"status": "inactive"
}
</block>
/blogs/v3/topics/:topic-iid
Marks a blog topic as deleted.
Requirements
Parameters
Unique identifier for the particular topic to delete
Response
xxxxxxxxxx
<h3>Example DELETE URL:</h3>
<a href="https://api.hubapi.com/blogs/v3/topics/2537672228?hapikey=demo" target="_blank">https://api.hubapi.com/blogs/v3/topicss/2537672228</a>
<p>Example DELETE response:</p>
HTTP/1.1 204 No Content