# Articles

Everything about your Articles

## List all articles

 - [GET /articles](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/articles/listarticles.md): You can fetch a list of all articles by making a GET request to https://api.intercom.io/articles.

> 📘 How are the articles sorted and ordered?
>
> Articles will be returned in descending order on the updated_at attribute. This means if you need to iterate through results then we'll show the most recently updated articles first.

## Create an article

 - [POST /articles](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/articles/createarticle.md): You can create a new article by making a POST request to https://api.intercom.io/articles.

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

## Retrieve an article

 - [GET /articles/{id}](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/articles/retrievearticle.md): You can fetch the details of a single article by making a GET request to https://api.intercom.io/articles/.

## Update an article

 - [PUT /articles/{id}](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/articles/updatearticle.md): You can update the details of a single article by making a PUT request to https://api.intercom.io/articles/.

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

## Delete an article

 - [DELETE /articles/{id}](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/articles/deletearticle.md): You can delete a single article by making a DELETE request to https://api.intercom.io/articles/.

## Retrieve an article draft

 - [GET /articles/{id}/draft](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/articles/retrievearticledraft.md): Fetch the staged draft of a published article by making a GET request to
https://api.intercom.io/articles//draft. The response is the article
rendered with its draft content, leaving the live article untouched.

A draft exists only when a published article has unpublished changes staged
on top of it. Returns 404 when the article has no staged draft.

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

## Stage an article draft

 - [PUT /articles/{id}/draft](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/articles/stagearticledraft.md): Stage changes to a published article as a draft by making a PUT request to
https://api.intercom.io/articles//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.

## Publish an article draft

 - [POST /articles/{id}/draft/publish](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/articles/publisharticledraft.md): Publish a staged draft by making a POST request to
https://api.intercom.io/articles//draft/publish, promoting the draft
content to live.

On a single-language workspace no body is required. On a multilingual
workspace you must list which locales to publish via the locales array;
omitting it returns 422. Returns 422 when there is no staged draft to
publish, or when a requested locale has no pending changes.

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

## List article versions

 - [GET /articles/{article_id}/versions](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/articles/listarticleversions.md): Fetch the version history of an article by making a GET request to
https://api.intercom.io/articles//versions. Versions are
returned newest-first as a paginated list of metadata. Use
GET /articles/{article_id}/versions/{id} to retrieve a single version
with its full content.

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

## Retrieve an article version

 - [GET /articles/{article_id}/versions/{id}](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/articles/retrievearticleversion.md): Fetch a single prior version of an article, including its body content,
by making a GET request to
https://api.intercom.io/articles//versions/. Returns
the version's full content; the live article remains untouched.

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

## Search for articles

 - [GET /articles/search](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/articles/searcharticles.md): You can search for articles by making a GET request to https://api.intercom.io/articles/search.