Update an article

Request

You can update the details of a single article by making a PUT request to https://api.intercom.io/articles/<id>.

📘 Tags cannot be managed via the Articles API
Article tags are read-only in responses. To create, update, or delete tags, use the Intercom UI or the Tags API endpoints.

Security

bearerAuth

Path

article_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:"2.16"

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

Example:2.16

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"

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.

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

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

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

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

Responses

successful

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

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
]

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

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

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": [],
  "statistics": {
    "type": "article_statistics",
    "views": 0,
    "conversations": 0,
    "reactions": 0,
    "happy_reaction_percentage": 0,
    "neutral_reaction_percentage": 0,
    "sad_reaction_percentage": 0
  },
  "tags": {
    "type": "tag.list",
    "tags": []
  },
  "title": "Christmas is here!",
  "description": "",
  "body": "<p class=\"no-margin\">New gifts in store for the jolly season</p>",
  "author_id": 991267508,
  "state": "published",
  "created_at": 1734537297,
  "updated_at": 1734537298,
  "url": "http://help-center.test/myapp-80/en/articles/48-christmas-is-here"
}