Intercom API (unofficial showcase)
POST/articles

Create an article

Creates a new article in the help center. Supply title and author_id; state defaults to draft, and you can provide article content in HTML or Markdown. Article tags are read-only through the Articles API and must be managed through the Tags API or the Intercom UI.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 16 body fields
Intercom-Versionstringoptional
The Intercom API version to use. Defaults to 2.17 when omitted.
Allowed:1.01.11.21.31.42.02.12.22.32.42.52.6Default:2.17

Article content and settings. title and author_id are required; the other fields are optional.

titlestringrequired
The title of the article.For multilingual articles, this will be the title of the default language's content.
descriptionstringoptional
The description of the article. For multilingual articles, this will be the description of the default language's content.
bodystringoptional
The content of the article in HTML. For multilingual articles, this will be the body of the default language's content. Mutually exclusive with `body_markdown`.
body_markdownstringoptional
The content of the article in markdown. For multilingual articles, this will be the body of the default language's content. An alternative to `body` — you can provide content as markdown instead of HTML. Mutually exclusive with `body`.
author_idintegerrequired
The id of the author of the article. For multilingual articles, this will be the id of the author of the default language's content. Must be a teammate on the help center's workspace.
statestringoptional
Whether the article will be `published` or will be a `draft`. Defaults to draft. For multilingual articles, this will be the state of the default language's content.
Allowed:publisheddraft
parent_idintegeroptional
The id of the article's parent collection or section. An article without this field stands alone.
parent_typestringoptional
The type of parent, which can either be a `collection` or `section`.
translated_contentobjectoptional
The Translated Content of an Article. The keys are the locale codes and the values are the translated content of the article.
folder_idintegeroptional
The ID of the folder to place this article in, or null to leave it without a folder.
audience_idsarray<integer>optional
The list of audience IDs to assign to this article for Fin AI Agent targeting. Sending a top-level `audience_ids` broadcasts the same set to every locale. For per-locale targeting, use `translated_content.<locale>.audience_ids` instead. Sending both top-level and per-locale in the same request causes top-level to win. Unknown audience IDs return a 404 error. No partial commit occurs.
ai_chatbot_availabilitybooleanoptional
Whether the article should be available for AI Chatbot (Fin). For multilingual articles, this sets the default language's availability.
ai_copilot_availabilitybooleanoptional
Whether the article should be available for AI Copilot. For multilingual articles, this sets the default language's availability.
ai_sales_agent_availabilitybooleanoptional
Whether the article should be available for AI Sales Agent. For multilingual articles, this sets the default language's availability.
scheduled_publish_atstringoptional
ISO 8601 timestamp at which to schedule a future publish of the article. When set together with `state: "published"`, the article is scheduled instead of published immediately. Setting `null` cancels a pending publish schedule. Timestamps in the past or equal to the current time are rejected with 400 `parameter_invalid` — the value must be strictly in the future. Combining with `state: "draft"` returns 400 `parameter_invalid`. Sending in the same request as `scheduled_unpublish_at` returns 400 — only one pending schedule per article. Empty string returns 400 `parameter_invalid`.
scheduled_unpublish_atstringoptional
ISO 8601 timestamp at which to schedule a future unpublish of the article. Setting `null` cancels a pending unpublish schedule. Timestamps in the past or equal to the current time are rejected with 400 `parameter_invalid` — the value must be strictly in the future. Rejected with 400 `parameter_invalid` if the article has never been published. Sending in the same request as `scheduled_publish_at` returns 400 — only one pending schedule per article. Empty string returns 400 `parameter_invalid`.

3 status codes
200Returns the created article object, including its article content, publication state, and article metadata.
statisticsobjectoptional
The statistics of an article.
typestringoptional
The type of object - `article`.
Allowed:articleDefault:article
idstringoptional
The unique identifier for the article which is given by Intercom.
workspace_idstringoptional
The id of the workspace which the article belongs to.
titlestringoptional
The title of the article. For multilingual articles, this will be the title of the default language's content.
descriptionstringoptional
The description of the article. For multilingual articles, this will be the description of the default language's content.
bodystringoptional
The body of the article in HTML. For multilingual articles, this will be the body of the default language's content.
body_markdownstringoptional
The body of the article in markdown. For multilingual articles, this will be the body of the default language's content.
author_idintegeroptional
The id of the author of the article. For multilingual articles, this will be the id of the author of the default language's content. Must be a teammate on the help center's workspace.
statestringoptional
Whether the article is `published` or is a `draft`. For multilingual articles, this will be the state of the default language's content.
Allowed:publisheddraftDefault:draft
created_atintegeroptional
The time when the article was created. For multilingual articles, this will be the timestamp of creation of the default language's content in seconds.
updated_atintegeroptional
The time when the article was last updated. For multilingual articles, this will be the timestamp of last update of the default language's content in seconds.
has_unpublished_changesbooleanoptional
Whether the published article has unpublished changes staged as a draft on top of its live content. For multilingual articles this reflects the default language's content; a pure draft (never published) reports `false`.
draft_updated_atintegeroptional
The time, in seconds, when the staged draft was last edited, or `null` when there is no staged draft.
urlstringoptional
The URL of the article. For multilingual articles, this will be the URL of the default language's content.
parent_idsarray<integer>optional
The ids of the article's parent collections or sections. An article without this field stands alone.
ai_chatbot_availabilitybooleanoptional
Whether the article is available for AI Chatbot. For multilingual articles, this will be the value of the default language's content.
ai_copilot_availabilitybooleanoptional
Whether the article is available for AI Copilot. For multilingual articles, this will be the value of the default language's content.
ai_sales_agent_availabilitybooleanoptional
Whether the article is available for AI Sales Agent. For multilingual articles, this will be the value of the default language's content.
created_by_idintegeroptional
The ID of the teammate who created the article. For multilingual articles, this will be the creator of the default language's content.
updated_by_idintegeroptional
The ID of the teammate who last updated the article. For multilingual articles, this will be the last editor of the default language's content.
exclude_from_article_suggestionsbooleanoptional
Whether the article is excluded from Fin AI Agent article suggestions.
help_center_audiencestringoptional
The audience that can view this article in the Help Center. `everyone` means all users and visitors can view it; `restricted` indicates a custom audience ruleset. For multilingual articles, this is the article-level audience.
Allowed:everyoneall_usersall_visitorsall_leadsall_visitors_and_leadsrestricted
scheduled_publish_atintegeroptional
The Unix timestamp (in seconds) at which the article is scheduled to be published. `null` when no publish is scheduled. Mutually exclusive with `scheduled_unpublish_at` — at most one pending schedule exists per article.
scheduled_unpublish_atintegeroptional
The Unix timestamp (in seconds) at which the article is scheduled to be unpublished. `null` when no unpublish is scheduled. Mutually exclusive with `scheduled_publish_at` — at most one pending schedule exists per article.
default_localestringoptional
The default locale of the help center. This field is only returned for multilingual help centers.
translated_contentobjectoptional
The Translated Content of an Article. The keys are the locale codes and the values are the translated content of the article.
tagsobjectoptional
A list of tags objects associated with a conversation
folder_idintegeroptional
The ID of the folder this article belongs to, or null if not in a folder.
400Returned when the request fails validation, such as when a required field is missing or mutually exclusive content fields are both supplied.

One documented failure

  • parameter_not_found

    author_id must be in the main body or default locale translated_content object

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects
401Returned when the request is unauthorized.

One documented failure

  • unauthorized

    Access Token Invalid

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects

Error handling

title and author_id are required, and body and body_markdown are mutually exclusive. state must be published or draft; a 400 is returned when the request fails validation. A 401 is returned when the request is not authorized.