Stage an article draft

Request

Stage changes to a published article as a draft by making a PUT request to https://api.intercom.io/articles/<id>/draft. The live article remains unchanged until the draft is published.

The article must already be published; staging a draft on an article that has never been published returns 422.

Only versioned text content (such as title and body) is staged. Non-versioned fields like AI availability are ignored, leaving the live values untouched.

Requires the read_write_articles_scope OAuth scope. Set Intercom-Version: Preview.

Security

bearerAuth

Path

idintegerrequired

The unique identifier for the article which is given by Intercom.

Example:123

Headers

Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default:"Preview"

Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"

Example:Preview

Bodyapplication/json

titlestring

The title of the article.For multilingual articles, this will be the title of the default language's content.

Example:"Thanks for everything"

descriptionstring

The description of the article. For multilingual articles, this will be the description of the default language's content.

Example:"Description of the Article"

bodystring

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.

Example:"<p>This is the body in html</p>"

body_markdownstring

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.

Example:"## Updated heading\n\nNew content.\n"

author_idinteger

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.

Example:1295

statestring

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.

Enum:"published""draft"

Example:"draft"

parent_idstring

The id of the article's parent collection or section. An article without this field stands alone.

Example:"18"

parent_typestring

The type of parent, which can either be a collection or section.

Example:"collection"

parent_idsArray of integers

The ids of the parent collections to place this article in. Send an empty array to remove the article from all collections. When provided, this takes precedence over parent_id and parent_type.

Example:

[
  18,
  19
]

translated_contentobject or null(Article Translated Content)

The Translated Content of an Article. The keys are the locale codes and the values are the translated content of the article.

folder_idinteger or null

The ID of the folder to place this article in, or null to remove it from its folder.

Example:6

audience_idsArray of integers or null

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. Sending audience_ids: [] clears all audience memberships from 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.

Example:

[
  1,
  2
]

ai_chatbot_availabilityboolean

Whether the article should be available for AI Chatbot (Fin). For multilingual articles, this sets the default language's availability.

Example:true

ai_copilot_availabilityboolean

Whether the article should be available for AI Copilot. For multilingual articles, this sets the default language's availability.

Example:true

ai_sales_agent_availabilityboolean

Whether the article should be available for AI Sales Agent. For multilingual articles, this sets the default language's availability.

Example:true

scheduled_publish_atstring or null, (date-time)

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. The value must be strictly in the future — timestamps in the past or equal to the current time are rejected with 400 parameter_invalid. Setting null cancels a pending publish schedule. 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.

Example:"2026-12-31T09:00:00Z"

scheduled_unpublish_atstring or null, (date-time)

ISO 8601 timestamp at which to schedule a future unpublish of the article. The value must be strictly in the future — timestamps in the past or equal to the current time are rejected with 400 parameter_invalid. Setting null cancels a pending unpublish schedule. 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.

Example:"2026-12-31T17:00:00Z"

curl -i -X PUT \
  https://api.intercom.io/articles/123/draft \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: Preview' \
  -d '{
    "title": "Christmas is here!",
    "body": "<p>New gifts in store for the jolly season</p>"
  }'

Responses

Draft staged

Bodyapplication/json

typestring

The type of object - article.

Default:"article"

Value:"article"

Example:"article"

idstring

The unique identifier for the article which is given by Intercom.

Example:"6871119"

workspace_idstring

The id of the workspace which the article belongs to.

Example:"hfi1bx4l"

titlestring

The title of the article. For multilingual articles, this will be the title of the default language's content.

Example:"Default language title"

descriptionstring or null

The description of the article. For multilingual articles, this will be the description of the default language's content.

Example:"Default language description"

bodystring or null

The body of the article in HTML. For multilingual articles, this will be the body of the default language's content.

Example:"Default language body in html"

body_markdownstring or null

The body of the article in markdown. For multilingual articles, this will be the body of the default language's content.

Example:"# Default language title\n\nDefault language body in markdown\n"

author_idinteger

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.

Example:"5017691"

statestring

Whether the article is published or is a draft. For multilingual articles, this will be the state of the default language's content.

Default:"draft"

Enum:"published""draft"

Example:"published"

created_atinteger, (date-time)

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.

Example:1672928359

updated_atinteger, (date-time)

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.

Example:1672928610

has_unpublished_changesboolean

Whether the published article has unpublished changes staged as a draft on top of its live content. Only returned on the Preview API version. For multilingual articles this reflects the default language's content; a pure draft (never published) reports false.

Example:false

draft_updated_atinteger or null, (date-time)

The time, in seconds, when the staged draft was last edited, or null when there is no staged draft. Only returned on the Preview API version.

Example:1672928610

urlstring or null

The URL of the article. For multilingual articles, this will be the URL of the default language's content.

Example:"http://intercom.test/help/en/articles/3-default-language"

parent_idsArray of integers

The ids of the article's parent collections or sections. An article without this field stands alone.

Example:

[
  18,
  19
]

default_localestring

The default locale of the help center. This field is only returned for multilingual help centers.

Example:"en"

translated_contentobject or null(Article Translated Content)

The Translated Content of an Article. The keys are the locale codes and the values are the translated content of the article.

tagsobject(Tags)

A list of tags objects associated with a conversation

folder_idinteger or null

The ID of the folder this article belongs to, or null if not in a folder.

Example:6

ai_chatbot_availabilityboolean

Whether the article is available for AI Chatbot. For multilingual articles, this will be the value of the default language's content.

Example:true

ai_copilot_availabilityboolean

Whether the article is available for AI Copilot. For multilingual articles, this will be the value of the default language's content.

Example:true

ai_sales_agent_availabilityboolean

Whether the article is available for AI Sales Agent. For multilingual articles, this will be the value of the default language's content.

Example:true

created_by_idinteger or nullread-only

The ID of the teammate who created the article. For multilingual articles, this will be the creator of the default language's content.

Example:5017691

updated_by_idinteger or nullread-only

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.

Example:5017691

exclude_from_article_suggestionsbooleanread-only

Whether the article is excluded from Fin AI Agent article suggestions.

Example:false

help_center_audiencestring or nullread-only

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.

Enum:"everyone""all_users""all_visitors""all_leads""all_visitors_and_leads""restricted"

Example:"everyone"

scheduled_publish_atinteger or null, (date-time)read-only

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.

Example:1769443200

scheduled_unpublish_atinteger or null, (date-time)read-only

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.

Example:1769443200

statisticsobject or null(Article Statistics)

The statistics of an article.

Response

{
  "id": "48",
  "type": "article",
  "workspace_id": "this_is_an_id80_that_should_be_at_least_4",
  "parent_ids": [],
  "title": "Christmas is here!",
  "description": "",
  "body": "<p class=\"no-margin\">New gifts in store for the jolly season</p>",
  "body_markdown": "New gifts in store for the jolly season\n",
  "author_id": 991267508,
  "state": "published",
  "created_at": 1734537297,
  "updated_at": 1734537298,
  "has_unpublished_changes": true,
  "draft_updated_at": 1734537298,
  "url": "http://help-center.test/myapp-80/en/articles/48-christmas-is-here",
  "ai_chatbot_availability": true,
  "ai_copilot_availability": true,
  "ai_sales_agent_availability": true
}