CMS API | Blog Settings

Scope requirements

You can use the blog settings API to retrieve and manage blogs in your HubSpot account. This API allows you to list all blogs, retrieve individual blog details, access revision history, and manage multi-language blog variations.

Retrieve blogs

You can retrieve blogs either individually by ID or by retrieving all blogs:

To retrieve an individual blog, make a GET request to /cms/v3/blog-settings/settings/{blogId}.
To retrieve all blogs, make a GET request to /cms/v3/blog-settings/settings.

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

curl https://api.hubapi.com/cms/v3/blog-settings/settings?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	Cursor token to get the next set of results. Available from `paging.next.after` in paginated responses.
`archived`	Boolean	Filter by whether the blog is archived.
`createdAfter`	String	Filter to blogs created after this timestamp (ISO8601 format).
`createdAt`	String	Filter to blogs created at this exact timestamp (ISO8601 format).
`createdBefore`	String	Filter to blogs created before this timestamp (ISO8601 format).
`limit`	Integer	Maximum number of blogs to return.
`sort`	Array	List of fields to sort by. Each sort specifies a property name and direction (`ASCENDING`, `DESCENDING`).
`updatedAfter`	String	Filter to blogs updated after this timestamp (ISO8601 format).
`updatedAt`	String	Filter to blogs updated at this exact timestamp (ISO8601 format).
`updatedBefore`	String	Filter to blogs updated before this timestamp (ISO8601 format).

By default, results will be sorted by creation date in ascending order.

{
  "total": 2,
  "results": [
    {
      "id": "184993428780",
      "name": "Company Blog",
      "publicTitle": "Our Blog",
      "description": "The official company blog",
      "slug": "blog",
      "absoluteUrl": "https://www.example.com/blog",
      "language": "en",
      "allowComments": true,
      "created": "2024-01-15T10:30:00Z",
      "updated": "2024-06-20T14:45:00Z"
    }
  ]
}

Retrieve a single blog

To retrieve details for a specific blog, make a GET request to /cms/v3/blog-settings/settings/{blogId}. For example, the request below would retrieve the details for the blog with ID 184993428780:

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

Retrieve blog revisions

You can access the revision history of a blog to view previous versions and track changes over time.

List all revisions

To retrieve all revisions for a blog, make a GET request to /cms/v3/blog-settings/settings/{blogId}/revisions. The following query parameters are available:

Parameter	Type	Description
`after`	String	Cursor token to get the next set of results.
`before`	String	Cursor token to get the previous set of results.
`limit`	Integer	Maximum number of results to return. Default is 100.

Retrieve a specific revision

To retrieve a specific revision, make a GET request to /cms/v3/blog-settings/settings/{blogId}/revisions/{revisionId}. For example, the request below would retrieve the revision with ID 12345 for the blog with ID 184993428780:

curl https://api.hubapi.com/cms/v3/blog-settings/settings/184993428780/revisions/12345 \
  --request GET \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"

The following response body is returned:

{
  "id": "12345",
  "updatedAt": "2024-06-20T14:45:00Z",
  "user": {
    "id": "123456",
    "email": "user@example.com",
    "fullName": "John Doe"
  },
  "object": {
    "id": "184993428780",
    "name": "Company Blog",
    "slug": "blog"
  }
}

Multi-language management

HubSpot’s CMS allows you to group together language variants of the same blog. You can learn more about working with multi-language content in HubSpot’s Knowledge Base.

Create a new language variation

To create a new language variation from an existing blog, make a POST request to /cms/v3/blog-settings/settings/multi-language/create-language-variation. For example, the request below would create a Spanish language variation for the blog with ID 184993428780:

curl https://api.hubapi.com/cms/v3/blog-settings/settings/multi-language/create-language-variation \
  --request POST \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "id": "184993428780",
    "language": "es",
    "slug": "blog-es"
  }'

The following request body parameters are available:

Parameter	Type	Description
`id` Required	String	ID of the blog to clone.
`language`	String	Target language of the new variant.
`primaryLanguage`	String	Language of the primary blog to clone.
`slug`	String	Path to the new blog.

Attach a blog to a multi-language group

To add a blog to an existing multi-language group, make a POST request to /cms/v3/blog-settings/settings/multi-language/attach-to-lang-group. For example, the request below would add the blog with ID 184993428781 to the multi-language group with the primary blog ID 184993428780:

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

The following request body parameters are available:

Parameter	Type	Description
`id` Required	String	ID of the blog to add to the multi-language group.
`language` Required	String	Designated language of the blog being added.
`primaryId` Required	String	ID of the primary language blog in the multi-language group.
`primaryLanguage`	String	Primary language of the multi-language group.

Detach a blog from a multi-language group

To remove a blog from a multi-language group, make a POST request to /cms/v3/blog-settings/settings/multi-language/detach-from-lang-group. For example, the request below would remove the blog with ID 184993428781 from the multi-language group:

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

The following request body parameters are available:

Parameter	Type	Description
`id` Required	String	ID of the blog to remove from the multi-language group.

​Retrieve blogs

​Retrieve a single blog

​Retrieve blog revisions

​List all revisions

​Retrieve a specific revision

​Multi-language management

​Create a new language variation

​Attach a blog to a multi-language group

​Detach a blog from a multi-language group

Retrieve blogs

Retrieve a single blog

Retrieve blog revisions

List all revisions

Retrieve a specific revision

Multi-language management

Create a new language variation

Attach a blog to a multi-language group

Detach a blog from a multi-language group