There's a new version of the HubSpot API
We're also working on a new documentation website, you're invited to check it out and give us your feedback.
HTTP Methods:
GET
Response Format:
json
Requires Authentication?
Yes
Rate Limited?
Headers
Products:
Marketing
Required Scope:
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.
| Required Parameters | How to use | Description |
|---|---|---|
| OAuth access token or private app access token | Authorization: Bearer {token} header | Used to authenticate the request. Please see this page for more details about authentication. |
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
| Parameter name | Description |
|---|---|
| id | Search for topics by id. Supports exact value matching and the 'in' range filter (e.g. id__in=348109009,348109019) |
| name | Search for topics by name. Supports exact value matching, 'contains' searching, and 'icontains' case-insensitive searching (e.g. name__contains=topic1) |
| slug | Search for topics by slug. Supports exact value matching |
| created | Filter results by creation date, in milliseconds since the epoch. Supports exact value matching and the following range filters: range, gt, gte, lt, lte |
| limit | The maximum number of items to return. Defaults to 100. |
| offset | The offset from the beginning of the result set from which to start returning results. Used for paging. Defaults to 0. |
| casing | 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. |
| q | Search for topics whose names or url slugs contain the given string. |
| active | Filter topics by whether or not they are associated with any published blog posts (true or false). |
| blog | Filter topics by a blog they are used on (value is a blog ID). |
| 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. |
