> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge base API (BETA)

> Create and manage articles, categories, and tags in your HubSpot knowledge base.

export const RequiredIndicator = () => {
  return <span className="required-indicator">
      required
    </span>;
};

export const BetaDisclaimerBanner = () => <Warning>
        This functionality is currently in beta. By participating in this beta, you agree to HubSpot's <a href="https://legal.hubspot.com/developer-terms">Developer Terms</a> and <a href="https://legal.hubspot.com/developerbetaterms">Developer Beta Terms</a>. Note that the functionality is still under active development and is subject to change based on testing and feedback.
    </Warning>;

export const ScopesList = ({scopes = [], description = "This API requires one of the following scopes:"}) => {
  if (!scopes || scopes.length === 0) {
    return null;
  }
  const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
  return <div>
      <div className="text-sm mb-2">{description}</div>
      <div>
        {sortedScopes.map((scope, index) => <div key={index}>
            <code>
              <span className="text-xs">{scope}</span>
            </code>
          </div>)}
      </div>
    </div>;
};

export const SupportedProducts = ({marketing, sales, service, cms, data, commerce, crm, marketingLevel, salesLevel, serviceLevel, cmsLevel, dataLevel, commerceLevel, crmLevel}) => {
  const translations = {
    description: "Requires one of the following products or higher.",
    productNames: {
      marketing: "Marketing Hub",
      sales: "Sales Hub",
      service: "Service Hub",
      cms: "Content Hub",
      data: "Data Hub",
      commerce: "Revenue Hub",
      crm: "Smart CRM"
    },
    tiers: {
      free: "Free",
      starter: "Starter",
      professional: "Professional",
      enterprise: "Enterprise"
    }
  };
  const translateTier = tier => {
    if (!tier) return '';
    const lowerTier = tier.toLowerCase();
    return translations.tiers[lowerTier] || tier;
  };
  const products = [{
    name: marketing ? translations.productNames.marketing : '',
    level: translateTier(marketingLevel),
    icon: "https://www.hubspot.com/hubfs/Knowledge_Base_2023-24-25/developer/icons/MarketingHub.svg",
    alt: "Marketing Hub"
  }, {
    name: sales ? translations.productNames.sales : '',
    level: translateTier(salesLevel),
    icon: "https://www.hubspot.com/hubfs/Knowledge_Base_2023-24-25/developer/icons/SalesHub.svg",
    alt: "Sales Hub"
  }, {
    name: service ? translations.productNames.service : '',
    level: translateTier(serviceLevel),
    icon: "https://www.hubspot.com/hubfs/Knowledge_Base_2023-24-25/developer/icons/ServiceHub.svg",
    alt: "Service Hub"
  }, {
    name: cms ? translations.productNames.cms : '',
    level: translateTier(cmsLevel),
    icon: "https://www.hubspot.com/hubfs/Knowledge_Base_2023-24-25/developer/icons/ContentHub.svg",
    alt: "Content Hub"
  }, {
    name: data ? translations.productNames.data : '',
    level: translateTier(dataLevel),
    icon: "https://www.hubspot.com/hubfs/Knowledge_Base_2023-24-25/developer/icons/DataHub.svg",
    alt: "Data Hub"
  }, {
    name: commerce ? translations.productNames.commerce : '',
    level: translateTier(commerceLevel),
    icon: "https://www.hubspot.com/hubfs/Knowledge_Base/subscription_key_icons/commerce_icon.svg",
    alt: "Revenue Hub"
  }, {
    name: crm ? translations.productNames.crm : '',
    level: translateTier(crmLevel),
    icon: "https://www.hubspot.com/hubfs/Knowledge_Base_2023-24-25/developer/icons/SmartCRM.svg",
    alt: "Smart CRM"
  }].filter(product => product.name && product.level);
  if (products.length === 0) return null;
  return <div>
      <div className="text-sm mb-2">{translations.description}</div>
      <div className={`grid ${products.length === 1 ? 'grid-cols-1' : 'grid-cols-2'} gap-1.5`}>
        {products.map((product, index) => <div key={index} style={{
    display: 'flex',
    alignItems: 'center'
  }}>
            <img src={product.icon} alt={product.alt} className="w-3.5 h-3.5 mr-1.5 mt-2.5 mb-2.5 flex-shrink-0 align-middle" />
            <span className="font-medium mr-1 text-sm">{product.name} -</span>
            <span className="text-sm">{product.level}</span>
          </div>)}
      </div>
    </div>;
};

<AccordionGroup>
  <Accordion title="Supported products" defaultOpen="true" icon="cubes">
    <SupportedProducts service={true} serviceLevel="PROFESSIONAL" />
  </Accordion>

  <Accordion title="Scope requirements" icon="key">
    <ScopesList
      scopes={[
  'cms.knowledge_base.articles.read',
  'cms.knowledge_base.articles.write',
  'cms.knowledge_base.articles.publish'
]}
    />
  </Accordion>
</AccordionGroup>

Use the knowledge base API to programmatically create and manage articles in your HubSpot [knowledge base](https://knowledge.hubspot.com/knowledge-base/set-up-a-knowledge-base). You can also retrieve knowledge base settings, categories, and tags.

<BetaDisclaimerBanner />

## 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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](#publish-a-draft).

In the request body, you'll need to include `knowledgeBaseId`, `title`, and `language`.

```json theme={null}
{
  "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` <RequiredIndicator /> | String | The ID of the knowledge base to create the article in. |
| `title` <RequiredIndicator /> | String | The article title. |
| `language` <RequiredIndicator /> | 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](#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](#update-an-article) but not removed entirely. This value will [sync across language variants](#synced-fields). |
| `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. |

<Note>
  `categoryId` stays in sync across all articles in a language group. See [Manage article translations](#manage-article-translations) for details.
</Note>

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

```json theme={null}
{
  "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](#filter-and-sort-articles).

The response will return a paginated list of articles and their details.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

<Note>
  `accessType` and `archivedInDashboard` can only be set on primary articles. Translations inherit these values automatically. See [Manage article translations](#manage-article-translations) for details.
</Note>

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

<Warning>
  **Please note:** the `translationOfId` and `archived` fields cannot be set via this endpoint. They can only be set using the [update article](#update-an-article) endpoint.
</Warning>

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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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.

<Info>
  Any of the article's [language variants](https://knowledge.hubspot.com/knowledge-base/create-knowledge-base-articles-in-multiple-languages) will also be updated automatically. You cannot set this field for language variants directly, as it's inherited from the primary article.
</Info>

```json theme={null}
{
  "archivedInDashboard": true
}
```

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

<Warning>
  **Please note:** setting `archived` to `true` cannot be undone. Setting `archived` to `false` in a subsequent update request will fail.
</Warning>

```json theme={null}
{
  "archived": true
}
```

## Retrieve categories

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

<Warning>
  **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.
</Warning>

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.

```json theme={null}
{
  "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.

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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](https://knowledge.hubspot.com/knowledge-base/create-knowledge-base-articles-in-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](#synced-fields) 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`.

```json highlight={7-8} theme={null}
{
  "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.

```json highlight={17-24} theme={null}
{
  "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](#archive-an-article).