Knowledge base API (BETA)

Supported products

Scope requirements

Use the knowledge base API to programmatically create and manage articles in your HubSpot knowledge base. You can also retrieve knowledge base settings, categories, and tags.

Retrieve knowledge bases

To retrieve all knowledge bases in your account, make a GET request to /cms/knowledge-base/2027-03-beta/knowledge-bases. The response will return a paginated list of knowledge bases, including each knowledge base’s id, name, domain, language, and URL.

{
  "results": [
    {
      "id": "179976093461",
      "name": "My KB",
      "language": "en",
      "domain": "www.website.com",
      "path": "knowledge",
      "url": "http://www.website.com/knowledge",
      "translations": {},
      "metaDescription": "Learn all about the platform on our knowledge base.",
      "accessType": "PUBLIC",
      "relatedArticlesEnabled": false,
      "createdAt": "2024-10-01T20:04:11.710Z",
      "updatedAt": "2024-10-01T20:04:13.105Z",
      "createdByUserId": "2931299",
      "updatedByUserId": "2931299"
    }
  ]
}

To retrieve a specific knowledge base, append the knowledge base ID to the request URL: /cms/knowledge-base/2027-03-beta/knowledge-bases/{knowledgeBaseId}. The response will return the knowledge base details, including its name, language, domain, URL, and access settings.

{
  "id": "179976093461",
  "name": "My KB",
  "language": "en",
  "domain": "www.website.com",
  "path": "knowledge",
  "url": "http://www.website.com/knowledge",
  "translations": {},
  "metaDescription": "Learn all about the platform on our knowledge base.",
  "accessType": "PUBLIC",
  "relatedArticlesEnabled": false,
  "createdAt": "2024-10-01T20:04:11.710Z",
  "updatedAt": "2024-10-01T20:04:13.105Z",
  "createdByUserId": "2931299",
  "updatedByUserId": "2931299"
}

The knowledgeBaseId returned in these responses is required when creating and filtering articles.

Create an article

To create a new article, make a POST request to /cms/knowledge-base/2027-03-beta/articles. New articles are created in a DRAFT state and are not publicly visible until published. In the request body, you’ll need to include knowledgeBaseId, title, and language.

{
  "knowledgeBaseId": "179976093461",
  "title": "Reset your password",
  "language": "en",
  "categoryId": "4409856",
  "metaDescription": "Learn how to reset your password to log in to your account.",
  "tagIds": [
    "50819883",
    "50820459",
    "50819228"
  ],
  "subtitle": "Having trouble logging in? Learn how to reset your password",
  "body": "<p>Here's some good content -- stuff that will no doubt help you troubleshoot the issue you're running into. In this article, you will learn many things.</p>\n<h2>First section</h2>\n<p>The first section is critical. It starts the user off on the right foot and helps them to feel confident as they proceed through the rest of the article.\n<h2>Second section</h3>\n<p>You'll likely want to provide <a href=\"https://en.wikipedia.org/wiki/Cat\" rel=\"noopener\">links</a> throughout the <a href=\"https://en.wikipedia.org/wiki/Domestication_of_the_cat\" rel=\"noopener\">article</a> so that the user has somewhere to go for more information or next steps.</p>"
}

Parameter	Type	Description
`knowledgeBaseId`	String	The ID of the knowledge base to create the article in.
`title`	String	The article title.
`language`	String	The article language. Accepts an ISO 639 language code (e.g., `en`, `es`), optionally with a region subtag (e.g., `en-US`).
`tagIds`	Array	Tag IDs to associate with the article. Learn how to retrieve tags.
`subtitle`	String	An optional subtitle for the article.
`body`	String	The article’s HTML content.
`categoryId`	String	The ID of the category to assign the article to. Once set, this value can be updated but not removed entirely. This value will sync across language variants.
`path`	String	A custom URL path for the article. If not provided, defaults to the title (lowercase hyphenated). For example, a `title` of `"Reset your password"` would have a default `path` of `"reset-your-password"`.
`metaDescription`	String	A meta description for SEO purposes. Required for publishing a draft.
`accessType`	String	The access level for the article. Accepted values: `PUBLIC`, `SSO_LOGIN`, or `ACCESS_GROUP_MEMBERSHIP`.
`translationOfId`	String	The ID of the article this is a translation of. Links translated articles to the primary article.
`accessGroupIds`	Array	Access group IDs that can view the article.

categoryId stays in sync across all articles in a language group. See Manage article translations for details.

The response will return the created article, including its assigned id and url.

{
  "id": "222377418866",
  "knowledgeBaseId": "179976093461",
  "title": "Reset your password",
  "subtitle": "Having trouble logging in? Learn how to reset your password",
  "language": "en",
  "categoryId": "4409856",
  "tagIds": [
    "50819883",
    "50820459",
    "50819228"
  ],
  "state": "DRAFT",
  "accessType": "PUBLIC",
  "accessGroupIds": [],
  "position": 0,
  "path": "reset-your-password",
  "url": "http://www.website.com/knowledge/reset-your-password",
  "body": "<p>Here's some good content -- stuff that will no doubt help you troubleshoot the issue you're running into. In this article, you will learn many things.</p>\n<h2>First section</h2>\n<p>The first section is critical. It starts the user off on the right foot and helps them to feel confident as they proceed through the rest of the article.\n<h2>Second section</h3>\n<p>You'll likely want to provide <a href=\"https://en.wikipedia.org/wiki/Cat\" rel=\"noopener\">links</a> throughout the <a href=\"https://en.wikipedia.org/wiki/Domestication_of_the_cat\" rel=\"noopener\">article</a> so that the user has somewhere to go for more information or next steps.</p>",
  "translations": {},
  "createdAt": "2026-09-21T14:11:08.667Z",
  "updatedAt": "2026-09-21T14:33:39.807Z",
  "createdByUserId": "2931299",
  "updatedByUserId": "2931299",
  "archivedInDashboard": false
}

Retrieve articles

To retrieve a list of articles, make a GET request to /cms/knowledge-base/2027-03-beta/articles. Results are paginated (default 25, maximum 100 per page). When retrieving articles, you can include includeBody=false or includeTranslations=false query parameters to reduce the response size. Learn more about the available filtering and sorting parameters. The response will return a paginated list of articles and their details.

{
  "results": [
    {
      "id": "213257111675",
      "knowledgeBaseId": "179976093461",
      "title": "What question is your article answering?",
      "language": "en",
      "tagIds": [],
      "state": "DRAFT",
      "accessType": "PUBLIC",
      "accessGroupIds": [],
      "position": 0,
      "path": "-temporary-slug-82e1fd73-0a92-46f3-a390-55e25bcafed6",
      "url": "http://www.website.com/knowledge/-temporary-slug-82e1fd73-0a92-46f3-a390-55e25bcafed6",
      "body": "",
      "translations": {},
      "createdAt": "2026-05-20T13:53:57.376Z",
      "updatedAt": "2026-05-20T13:53:57.376Z",
      "createdByUserId": "2931299",
      "updatedByUserId": "2931299",
      "archivedInDashboard": false
    },
    {
      "id": "179889003802",
      "knowledgeBaseId": "179976093461",
      "title": "What is a cat?",
      "subtitle": "Finally, a straight forward answer to the age old question",
      "language": "en",
      "categoryId": "4409856",
      "metaDescription": "Learn more about cats.",
      "tagIds": [],
      "state": "PUBLISHED",
      "accessType": "PUBLIC",
      "accessGroupIds": [],
      "position": 0,
      "path": "what-is-a-cat",
      "url": "http://www.website.com/knowledge/what-is-a-cat",
      "body": "<p>Ah, cats. Through history, mankind has catered to these otherworldly creatures.</p>\n<h3>Heading 1</h3>\n<p>This is the first subsection of the article.</p>",
      "translations": {},
      "createdAt": "2024-10-01T20:04:22.531Z",
      "updatedAt": "2024-10-01T20:06:15.735Z",
      "publishedAt": "2024-10-01T20:06:30.911Z",
      "initialPublishedAt": "2024-10-01T20:06:11.842Z",
      "createdByUserId": "2931299",
      "updatedByUserId": "2931299",
      "archivedInDashboard": false
    }
  ],
  "paging": {
    "next": {
      "after": "MjU%3D",
      "link": "https://api.hubspot.com/cms/knowledge-base/2027-03-beta/articles?after=MjU%3D"
    }
  }
}

To retrieve a specific article, make a GET request to /cms/knowledge-base/2027-03-beta/articles/{articleId}. The response will return the article and its details.

{
  "id": "213257111675",
  "knowledgeBaseId": "179976093461",
  "title": "What question is your article answering?",
  "language": "en",
  "tagIds": [],
  "state": "DRAFT",
  "accessType": "PUBLIC",
  "accessGroupIds": [],
  "position": 0,
  "path": "-temporary-slug-82e1fd73-0a92-46f3-a390-55e25bcafed6",
  "url": "http://www.website.com/knowledge/-temporary-slug-82e1fd73-0a92-46f3-a390-55e25bcafed6",
  "body": "",
  "translations": {},
  "createdAt": "2026-05-20T13:53:57.376Z",
  "updatedAt": "2026-05-20T13:53:57.376Z",
  "createdByUserId": "2931299",
  "updatedByUserId": "2931299",
  "archivedInDashboard": false
}

Filter and sort articles

The list endpoint supports several query parameters for filtering and sorting:

Parameter	Type	Description
`state`	String	Filter to articles in a specific state. Accepted values: `DRAFT` or `PUBLISHED`.
`archivedInDashboard`	Boolean	Filter articles based on whether they are archived in the dashboard. Accepted values: `true` or `false`.
`categoryId`	Array	Filter to articles in specific categories. Accepts multiple values.
`knowledgeBaseId`	Array	Filter to articles in specific knowledge bases. Accepts multiple values.
`language`	Array	Filter to articles in specific languages. Accepts multiple values.
`includeTranslations`	Boolean	Whether to include language variants in results. Defaults to `true`.
`includeBody`	Boolean	Whether to include the article body in results. Defaults to `true`.
`createdAfter` / `createdBefore`	String	Filter by creation date range. Accepts ISO-8601 timestamps.
`updatedAfter` / `updatedBefore`	String	Filter by update date range. Accepts ISO-8601 timestamps.
`sort`	Array	Sort by `name`, `createdAt`, or `updatedAt`. Prefix with `-` for descending order (e.g., `-createdAt`). Defaults to `createdAt` descending.
`after`	String	Pagination cursor from the previous response’s `paging.next.after` value.

Update an article

To update a live article, make a PATCH request to /cms/knowledge-base/2027-03-beta/articles/{articleId}. Only the fields included in the request body are updated. Omitted fields are left unchanged. In the request body, include the article fields you want to update.

accessType and archivedInDashboard can only be set on primary articles. Translations inherit these values automatically. See Manage article translations for details.

{
  "title": "Reset your password",
  "categoryId": "4409856",
  "tagIds": [
    "50819883",
    "50820459",
    "50819228"
  ],
  "subtitle": "Having trouble logging in? Learn how to reset your password",
  "body": "<p>Here's some good content -- stuff that will no doubt help you troubleshoot the issue you're running into. In this article, you will learn many things.</p>\n<h2>First section</h2>\n<p>The first section is critical. It starts the user off on the right foot and helps them to feel confident as they proceed through the rest of the article.\n<h2>Second section</h3>\n<p>You'll likely want to provide <a href=\"https://en.wikipedia.org/wiki/Cat\" rel=\"noopener\">links</a> throughout the <a href=\"https://en.wikipedia.org/wiki/Domestication_of_the_cat\" rel=\"noopener\">article</a> so that the user has somewhere to go for more information or next steps.</p>"
}

The response will return the updated article.

{
  "id": "222377418866",
  "knowledgeBaseId": "179976093461",
  "title": "Reset your password",
  "subtitle": "Having trouble logging in? Learn how to reset your password",
  "language": "en",
  "categoryId": "4409856",
  "tagIds": [
    "50819883",
    "50820459",
    "50819228"
  ],
  "state": "DRAFT",
  "accessType": "PUBLIC",
  "accessGroupIds": [],
  "position": 0,
  "path": "reset-your-password",
  "url": "http://www.website.com/knowledge/reset-your-password",
  "body": "<p>Here's some good content -- stuff that will no doubt help you troubleshoot the issue you're running into. In this article, you will learn many things.</p>\n<h2>First section</h2>\n<p>The first section is critical. It starts the user off on the right foot and helps them to feel confident as they proceed through the rest of the article.\n<h2>Second section</h3>\n<p>You'll likely want to provide <a href=\"https://en.wikipedia.org/wiki/Cat\" rel=\"noopener\">links</a> throughout the <a href=\"https://en.wikipedia.org/wiki/Domestication_of_the_cat\" rel=\"noopener\">article</a> so that the user has somewhere to go for more information or next steps.</p>",
  "translations": {},
  "createdAt": "2026-09-21T14:11:08.667Z",
  "updatedAt": "2026-09-21T14:33:39.807Z",
  "createdByUserId": "2931299",
  "updatedByUserId": "2931299",
  "archivedInDashboard": false
}

Manage article drafts

Published articles in HubSpot maintain a separate draft version that lets you stage changes before pushing them live. Use the draft endpoints to retrieve, edit, and publish draft content.

Retrieve a draft

To retrieve the draft version of an article, make a GET request to /cms/knowledge-base/2027-03-beta/articles/{articleId}/draft. The response will return the draft article, including its current content, state, and metadata. You can include includeBody=false or includeTranslations=false query parameters to reduce the response size.

{
  "id": "222377418866",
  "knowledgeBaseId": "179976093461",
  "title": "Reset your password",
  "subtitle": "Having trouble logging in? Learn how to reset your password",
  "language": "en",
  "categoryId": "4409856",
  "metaDescription": "Learn how to reset your password to log in to your account.",
  "tagIds": [
    "50819883",
    "50820459",
    "50819228"
  ],
  "state": "PUBLISHED",
  "accessType": "PUBLIC",
  "accessGroupIds": [],
  "position": 0,
  "path": "reset-your-password",
  "url": "http://www.website.com/knowledge/reset-your-password",
  "body": "<p>Here's some good content -- stuff that will no doubt help you troubleshoot the issue you're running into. In this article, you will learn many things.</p>\n<h2>First section</h2>\n<p>The first section is critical. It starts the user off on the right foot and helps them to feel confident as they proceed through the rest of the article.\n<h2>Second section</h3>\n<p>You'll likely want to provide <a href=\"https://en.wikipedia.org/wiki/Cat\" rel=\"noopener\">links</a> throughout the <a href=\"https://en.wikipedia.org/wiki/Domestication_of_the_cat\" rel=\"noopener\">article</a> so that the user has somewhere to go for more information or next steps.</p>",
  "translations": {},
  "createdAt": "2026-09-21T14:11:08.667Z",
  "updatedAt": "2026-09-21T14:40:28.875Z",
  "publishedAt": "2026-09-21T14:40:36.575Z",
  "initialPublishedAt": "2026-09-21T14:40:36.575Z",
  "createdByUserId": "2931299",
  "updatedByUserId": "2931299",
  "archivedInDashboard": false
}

Update a draft

To update draft content, make a PATCH request to /cms/knowledge-base/2027-03-beta/articles/{articleId}/draft. Include only the fields you want to update.

Please note: the translationOfId and archived fields cannot be set via this endpoint. They can only be set using the update article endpoint.

In the request body, include the draft fields you want to update.

{
  "title": "Log in",
  "subtitle": "Log in, get going.",
  "body": "<p>You can log in either via <a href=\"https://en.wikipedia.org/wiki/Cat\" rel=\"noopener\">the website</a> or the mobile app.</p>\n<h2>Website login</h2>\n<p>Here's how you log in via the website.\n<h2>Mobile app login</h3>\n<p>Here's how you log in via the mobile app.</p>",
  "tagIds": [
    "50819883",
    "50820459"
  ]
}

The response will return the updated draft article.

{
  "id": "222380235353",
  "knowledgeBaseId": "179976093461",
  "title": "Log in",
  "subtitle": "Log in, get going.",
  "language": "en",
  "categoryId": "4409856",
  "metaDescription": "Read all about it!",
  "tagIds": [
    "50819883",
    "50820459"
  ],
  "state": "DRAFT",
  "accessType": "PUBLIC",
  "accessGroupIds": [],
  "position": 1,
  "path": "log-in",
  "url": "http://www.website.com/knowledge/log-in",
  "body": "<p>You can log in either via <a href=\"https://en.wikipedia.org/wiki/Cat\" rel=\"noopener\">the website</a> or the mobile app.</p>\n<h2>Website login</h2>\n<p>Here's how you log in via the website.\n<h2>Mobile app login</h3>\n<p>Here's how you log in via the mobile app.</p>",
  "translations": {},
  "createdAt": "2026-09-21T14:53:42.580Z",
  "updatedAt": "2026-09-21T15:02:17.256Z",
  "createdByUserId": "2931299",
  "updatedByUserId": "2931299",
  "archivedInDashboard": false
}

Publish a draft

To push a draft live, make a POST request to /cms/knowledge-base/2027-03-beta/articles/{articleId}/draft/push-live. The response will return the updated article in its published state.

{
  "id": "222377418866",
  "knowledgeBaseId": "179976093461",
  "title": "Reset your password",
  "subtitle": "Having trouble logging in? Learn how to reset your password",
  "language": "en",
  "categoryId": "4409856",
  "metaDescription": "Learn how to reset your password to log in to your account.",
  "tagIds": [
    "50819883",
    "50820459",
    "50819228"
  ],
  "state": "PUBLISHED",
  "accessType": "PUBLIC",
  "accessGroupIds": [],
  "position": 0,
  "path": "reset-your-password",
  "url": "http://www.website.com/knowledge/reset-your-password",
  "body": "<p>Here's some good content -- stuff that will no doubt help you troubleshoot the issue you're running into. In this article, you will learn many things.</p>\n<h2>First section</h2>\n<p>The first section is critical. It starts the user off on the right foot and helps them to feel confident as they proceed through the rest of the article.\n<h2>Second section</h3>\n<p>You'll likely want to provide <a href=\"https://en.wikipedia.org/wiki/Cat\" rel=\"noopener\">links</a> throughout the <a href=\"https://en.wikipedia.org/wiki/Domestication_of_the_cat\" rel=\"noopener\">article</a> so that the user has somewhere to go for more information or next steps.</p>",
  "translations": {},
  "createdAt": "2026-09-21T14:11:08.667Z",
  "updatedAt": "2026-09-21T14:40:28.875Z",
  "publishedAt": "2026-09-21T14:40:36.575Z",
  "initialPublishedAt": "2026-09-21T14:40:36.575Z",
  "createdByUserId": "2931299",
  "updatedByUserId": "2931299",
  "archivedInDashboard": false
}

Unpublish articles

To unpublish a published article and revert it to a draft state, make a POST request to /cms/knowledge-base/2027-03-beta/articles/{articleId}/unpublish. The response will return the article with its state set to DRAFT.

{
  "id": "222377418866",
  "knowledgeBaseId": "179976093461",
  "title": "Reset your password",
  "subtitle": "Having trouble logging in? Learn how to reset your password",
  "language": "en",
  "categoryId": "4409856",
  "metaDescription": "Learn how to reset your password to log in to your account.",
  "tagIds": [
    "50819883",
    "50820459",
    "50819228"
  ],
  "state": "DRAFT",
  "accessType": "PUBLIC",
  "accessGroupIds": [],
  "position": 0,
  "path": "reset-your-password",
  "url": "http://www.website.com/knowledge/reset-your-password",
  "body": "<p>Here's some good content -- stuff that will no doubt help you troubleshoot the issue you're running into. In this article, you will learn many things.</p>\n<h2>First section</h2>\n<p>The first section is critical. It starts the user off on the right foot and helps them to feel confident as they proceed through the rest of the article.\n<h2>Second section</h3>\n<p>You'll likely want to provide <a href=\"https://en.wikipedia.org/wiki/Cat\" rel=\"noopener\">links</a> throughout the <a href=\"https://en.wikipedia.org/wiki/Domestication_of_the_cat\" rel=\"noopener\">article</a> so that the user has somewhere to go for more information or next steps.</p>",
  "translations": {},
  "createdAt": "2026-09-21T14:11:08.667Z",
  "updatedAt": "2026-09-21T14:40:28.875Z",
  "createdByUserId": "2931299",
  "updatedByUserId": "2931299",
  "archivedInDashboard": false
}

Archive an article

To archive an article, make a PATCH request to /cms/knowledge-base/2027-03-beta/articles/{articleId}. In the request body, set one of archivedInDashboard or archived to true, depending on the type of archiving you want to perform.

Set archivedInDashboard to true to hide the article from the HubSpot dashboard. The article retains its current publish state (DRAFT or PUBLISHED) and can still be found via the Archived filter on the articles dashboard.

Any of the article’s language variants will also be updated automatically. You cannot set this field for language variants directly, as it’s inherited from the primary article.

{
  "archivedInDashboard": true
}

Set archived to true to permanently delete the article. Any language variants will need to be deleted separately.

Please note: setting archived to true cannot be undone. Setting archived to false in a subsequent update request will fail.

{
  "archived": true
}

Retrieve categories

Categories are organizational groups for knowledge base articles. The API supports read-only access to categories.

Please note: if a category translation is missing a name, that translation is considered incomplete. Publishing an article assigned to that category in that language will be blocked until the category translation has a name.

To retrieve all categories, make a GET request to /cms/knowledge-base/2027-03-beta/categories. You can filter by knowledgeBaseIds, parentCategoryIds, and language, and sort results by name, createdAt, or updatedAt. The response will return a paginated list of categories and their details.

{
  "results": [
    {
      "id": "79534382",
      "name": "Cats",
      "description": "",
      "translations": {},
      "knowledgeBaseId": "179976093461",
      "parentCategoryId": "4409856",
      "position": 0,
      "language": "en",
      "url": "http://www.website.com/knowledge/general/cats",
      "visibleOnHomepage": false,
      "createdAt": "2026-09-21T14:31:10.912Z",
      "updatedAt": "2026-09-21T14:31:10.912Z",
      "createdByUserId": "2931299",
      "updatedByUserId": "2931299"
    },
    {
      "id": "4409856",
      "name": "General",
      "description": null,
      "translations": {},
      "knowledgeBaseId": "179976093461",
      "parentCategoryId": null,
      "position": 3,
      "language": "en",
      "url": "http://www.website.com/knowledge/general",
      "visibleOnHomepage": true,
      "createdAt": "2024-10-01T20:04:14.691Z",
      "updatedAt": "2024-10-01T20:04:14.691Z",
      "createdByUserId": "2931299",
      "updatedByUserId": "2931299"
    },
    {
      "id": "4409773",
      "name": "FAQs",
      "description": null,
      "translations": {},
      "knowledgeBaseId": "179976093461",
      "parentCategoryId": null,
      "position": 0,
      "language": "en",
      "url": "http://www.website.com/knowledge/faqs",
      "visibleOnHomepage": true,
      "createdAt": "2024-10-01T20:04:13.396Z",
      "updatedAt": "2024-10-01T20:04:13.396Z",
      "createdByUserId": "2931299",
      "updatedByUserId": "2931299"
    }
  ],
  "paging": {
    "next": {
      "after": "MjU%3D",
      "link": "https://api.hubspot.com/cms/knowledge-base/2027-03-beta/categories?after=MjU%3D"
    }
  }
}

To retrieve a specific category, make a GET request to /cms/knowledge-base/2027-03-beta/categories/{categoryId}. The response will return the category details, including its name, language, parent category (if applicable), and any translated variants.

If a category translation variant is missing a name, the translation is considered incomplete and articles cannot be published using that category.

{
  "id": "79534382",
  "name": "Cats",
  "description": "",
  "translations": {},
  "knowledgeBaseId": "179976093461",
  "parentCategoryId": "4409856",
  "position": 0,
  "language": "en",
  "url": "http://www.website.com/knowledge/general/cats",
  "visibleOnHomepage": false,
  "createdAt": "2026-09-21T14:31:10.912Z",
  "updatedAt": "2026-09-21T14:31:10.912Z",
  "createdByUserId": "2931299",
  "updatedByUserId": "2931299"
}

Retrieve featured articles for a category

Featured articles are displayed on the knowledge base homepage. To retrieve the featured articles for a category, make a GET request to /cms/knowledge-base/2027-03-beta/categories/{categoryId}/featured-articles. The response will return an array of featured article entries in their configured display order. Each entry includes the article ID, its position in the list, the category it’s featured in, and the subcategory ID if applicable.

{
  "results": [
    {
      "articleId": "222380235353",
      "position": 0,
      "featuredInCategoryId": "4409774",
      "subcategoryId": null
    }
  ]
}

Retrieve tags

Tags provide another way to organize and filter articles within a knowledge base. The API supports read-only access to tags. To retrieve all tags, make a GET request to /cms/knowledge-base/2027-03-beta/tags. You can filter by knowledgeBaseIds and language, and sort by name, createdAt, or updatedAt. The response will return a paginated list of tags and the knowledge bases they belong to.

{
  "results": [
    {
      "id": "50819228",
      "name": "Troubleshooting",
      "knowledgeBases": [
        {
          "knowledgeBaseId": "179976093461",
          "languages": [
            "EN"
          ]
        }
      ],
      "createdAt": "2026-09-21T14:31:32.706Z",
      "updatedAt": "2026-09-21T14:31:32.706Z"
    },
    {
      "id": "50820459",
      "name": "User",
      "knowledgeBases": [
        {
          "knowledgeBaseId": "179976093461",
          "languages": [
            "EN"
          ]
        }
      ],
      "createdAt": "2026-09-21T14:31:26.721Z",
      "updatedAt": "2026-09-21T14:31:26.721Z"
    },
    {
      "id": "50819883",
      "name": "Account",
      "knowledgeBases": [
        {
          "knowledgeBaseId": "179976093461",
          "languages": [
            "EN"
          ]
        }
      ],
      "createdAt": "2026-09-21T14:31:20.163Z",
      "updatedAt": "2026-09-21T14:31:20.163Z"
    }
  ],
  "paging": {
    "next": {
      "after": "MjU%3D",
      "link": "https://api.hubspot.com/cms/knowledge-base/2027-03-beta/tags?after=MjU%3D"
    }
  }
}

To retrieve a specific tag, make a GET request to /cms/knowledge-base/2027-03-beta/tags/{tagId}. The response will return the tag details, including its name and the knowledge bases it belongs to.

{
  "id": "50819228",
  "name": "Troubleshooting",
  "knowledgeBases": [
    {
      "knowledgeBaseId": "179976093461",
      "languages": [
        "EN"
      ]
    }
  ],
  "createdAt": "2026-09-21T14:31:32.706Z",
  "updatedAt": "2026-09-21T14:31:32.706Z"
}

Manage article translations

HubSpot knowledge base articles support multiple languages. You can create translated versions of an article by linking them to a primary article using the translationOfId field. Articles linked to the same primary article form a language group, and some fields are synced across the group automatically.

Create a translation

To create a translated version of an existing article, make a POST request to /cms/knowledge-base/2027-03-beta/articles and include translationOfId set to the id of the primary article. For example, the following request body would create a Spanish language variant of an article with the ID 222380235353.

{
  "title": "Iniciar sesión en HubSpot",
  "knowledgeBaseId": "179976093461",
  "categoryId": "4409774",
  "metaDescription": "Descubre cómo iniciar sesión en HubSpot y cómo solucionar problemas de inicio de sesión.",
  "subtitle": "Aprende a iniciar sesión en tu cuenta.",
  "language": "es",
  "translationOfId": "222380235353"
}

The response will return the created translation article, including its id and a translationOfId field reflecting the linked primary article.

{
  "id": "222624565129",
  "knowledgeBaseId": "179976093461",
  "title": "Iniciar sesión en HubSpot",
  "subtitle": "Aprende a iniciar sesión en tu cuenta.",
  "language": "es",
  "categoryId": "4409774",
  "metaDescription": "Descubre cómo iniciar sesión en HubSpot y cómo solucionar problemas de inicio de sesión.",
  "tagIds": [],
  "state": "DRAFT",
  "accessType": "PUBLIC",
  "accessGroupIds": [],
  "position": 0,
  "path": "iniciar-sesión-en-hubspot",
  "url": "http://2272014.hs-sites.com/es/knowledge/iniciar-sesión-en-hubspot",
  "body": "",
  "translationOfId": "222380235353",
  "translations": {
    "en": {
      "id": "222380235353",
      "title": "Log in",
      "state": "PUBLISHED"
    }
  },
  "createdAt": "2026-09-23T16:54:41.873Z",
  "updatedAt": "2026-09-23T16:54:41.873Z",
  "createdByUserId": "2931299",
  "updatedByUserId": "2931299",
  "archivedInDashboard": false
}

Synced fields

categoryId stays in sync across all articles in a language group:

On create: if a language variant omits categoryId, it inherits the value from the primary article.
On update: changing categoryId on any article in the group (primary or variant) propagates the change to all other articles in that group.
When changing translationOfId: the article’s categoryId is automatically re-synced to match the category of the newly linked primary article.
- If that primary article has no category, the variant falls back to the category of another published translation of that primary instead.
- If no published translations have an assigned category, the article’s existing categoryId is left unchanged.
- If you want to set the category explicitly at the same time, include categoryId in the same request that changes the translationOfId.

The following fields can only be set on the primary article, and are synced across language variants:

accessType: the access level for the article (PUBLIC, SSO_LOGIN, or ACCESS_GROUP_MEMBERSHIP).
archivedInDashboard: whether the article is hidden in the HubSpot dashboard. See Archive an article.

​Retrieve knowledge bases

​Create an article

​Retrieve articles

​Filter and sort articles

​Update an article

​Manage article drafts

​Retrieve a draft

​Update a draft

​Publish a draft

​Unpublish articles

​Archive an article

​Retrieve categories

​Retrieve featured articles for a category

​Retrieve tags

​Manage article translations

​Create a translation

​Synced fields

Retrieve knowledge bases

Create an article

Retrieve articles

Filter and sort articles

Update an article

Manage article drafts

Retrieve a draft

Update a draft

Publish a draft

Unpublish articles

Archive an article

Retrieve categories

Retrieve featured articles for a category

Retrieve tags

Manage article translations

Create a translation

Synced fields