Sign in
Basic

Create article

Changed on

Creates a new article under the specified knowledge base and language in a draft state. Requires knowledgeBaseId, title, and language; optionally accepts subtitle, body, categoryId, path, metaDescription, tagIds, accessType, accessGroupIds, and translationOfId (to link this article as a translation of an existing one). Returns the created article, including its assigned ID and public URL.

post/cms/knowledge-base/2027-03-beta/articles

Request

  • Base URL: https://api.hubapi.com
  • URL: https://api.hubapi.com/cms/knowledge-base/2027-03-beta/articles
  • Auth: one of:
    • OAuth 2 (authorization code, authorization URL https://app.hubspot.com/oauth/authorize, token URL https://api.hubapi.com/oauth/v1/token, scopes: cms.knowledge_base.articles.publish)
    • OAuth 2 (authorization code, authorization URL https://app.hubspot.com/oauth/authorize, token URL https://api.hubapi.com/oauth/v1/token, scopes: cms.knowledge_base.articles.write)
    • OAuth 2 (authorization code, authorization URL https://app.hubspot.com/oauth/authorize, token URL https://api.hubapi.com/oauth/v1/token, scopes: cms.knowledge_base.settings.write)

Request body

accessGroupIdsstring[]

The IDs of the access groups permitted to view the article. Required and non-empty only when accessType is ACCESS_GROUP_MEMBERSHIP; must be empty otherwise.

accessType'ACCESS_GROUP_MEMBERSHIP' | 'PUBLIC' | 'SSO_LOGIN'

The access level for the article: PUBLIC, SSO_LOGIN, or ACCESS_GROUP_MEMBERSHIP.

bodystring

The article’s HTML content.

categoryIdstring

The unique identifier of the category this article belongs to.

knowledgeBaseIdstring required

The ID of the knowledge base where the article will be created. Required.

languagestring required

The article’s language. Must be either the knowledge base’s primary language or one of its existing translation-variant languages. Accepts an ISO 639 language code (e.g., en, es), optionally with a region subtag (e.g., en-US). Required.

metaDescriptionstring

A brief description of the article, used for SEO.

pathstring

The URL path segment for the article.

subtitlestring

The subtitle of the article.

tagIdsstring[]

The IDs of the tags associated with the article.

titlestring required

The title of the article. Required.

translationOfIdstring

The ID of the article this is a translation of.

Example request

{
  "accessType": "{ \"accessType\": \"ACCESS_GROUP_MEMBERSHIP\" }",
  "categoryId": "{ \"categoryId\": \"12345678\" }",
  "knowledgeBaseId": "{ \"knowledgeBaseId\": \"23456789\" }",
  "language": "{ \"language\": \"en\" }",
  "path": "{ \"path\": \"how-to-reset-your-password\" }",
  "subtitle": "{ \"subtitle\": \"Step-by-step instructions\" }",
  "title": "{ \"title\": \"How to reset your password\" }",
  "translationOfId": "{ \"translationOfId\": \"98765432\" }"
}

Response

successful operation

accessGroupIdsstring[] required

The IDs of the access groups that have access to the article. Used when accessType is ACCESS_GROUP_MEMBERSHIP.

accessType'ACCESS_GROUP_MEMBERSHIP' | 'PUBLIC' | 'SSO_LOGIN' required

The access level for the article: PUBLIC, SSO_LOGIN, or ACCESS_GROUP_MEMBERSHIP.

archivedInDashboardboolean required

A boolean indicating whether the article is archived in the dashboard.

bodystring

The article’s HTML content. Only included when the request’s includeBody query parameter is true (which is the default value for the query).

categoryIdstring

The ID of the category this article belongs to.

createdAtstring date-time required

The date and time when the article was created, in ISO 8601 format.

createdByUserIdstring

The unique identifier of the user who created the article.

idstring required

The unique identifier for the knowledge article.

initialPublishedAtstring date-time

The date and time the article was first published, in ISO 8601 format. Absent if the article has never been published.

knowledgeBaseIdstring required

The unique identifier of the knowledge base to which this article belongs.

languagestring required

The article’s language, as an ISO 639 code (e.g. en).

metaDescriptionstring

A brief description of the article, used for SEO.

pathstring required

The URL path segment for the article. Combined with the knowledge base’s domain, this forms the URL field.

positioninteger

The position of the article within its category.

publishedAtstring date-time

The date and time the article was last published, in ISO 8601 format. Absent if the article has never been published.

state'DRAFT' | 'PUBLISHED' required

The article’s state: either DRAFT or PUBLISHED.

subcategoryIdstring

The subcategory this article belongs to.

subtitlestring

The subtitle of the knowledge article.

tagIdsstring[] required

The IDs of the tags associated with the article.

titlestring required

The title of the knowledge article.

translationOfIdstring

The ID of the article this is a translation of.

translationsobject

A summary of the article’s translations, keyed by language code. Only included when the request’s includeTranslations query parameter is true (which is the default value for the query).

updatedAtstring date-time required

The date and time when the article was last updated, in ISO 8601 format.

updatedByUserIdstring

The unique identifier of the user who last updated the article.

urlstring required

The full URL of the article.

Changes

  • 2027-03-beta2eff3dd6fefaRevision changes
    • ○

      the security scope cms.knowledge_base.articles.publish was added to the endpoint's security scheme oauth2

    • ○

      the security scope cms.knowledge_base.settings.write was removed from the endpoint's security scheme oauth2

    • ○

      the request property became optional

    • ○

      the request property became optional

  • 2027-03-betaf542018e1a93Revision changes
    • ○

      the security scope cms.knowledge_base.articles.publish was added to the endpoint's security scheme oauth2

    • ○

      the security scope cms.knowledge_base.settings.write was removed from the endpoint's security scheme oauth2