Skip to content

Commit 7be2e63

Browse files
alexpetrash-codeclaude
alexpetrash-code
and
claude
authored
Add Articles draft lifecycle endpoints to Preview spec (#542)
* Add Articles draft lifecycle endpoints to Preview spec Document the three Articles draft endpoints (Preview): - GET /articles/{id}/draft — retrieve a staged draft - PUT /articles/{id}/draft — stage a draft - POST /articles/{id}/draft/publish — publish a staged draft Responses reuse the existing article schema; the PUT body reuses update_article_request. Adds a publish_article_draft_request schema for the publish endpoint. _sent by alexbot_ Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * Note required OAuth scope in draft endpoint descriptions Add the required OAuth scope to each draft operation description, matching the convention used by other documented endpoints: - retrieve draft → read_articles_scope - stage / publish draft → read_write_articles_scope _sent by alexbot_ Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * Document draft detection fields and correct draft endpoint examples - Add has_unpublished_changes + draft_updated_at to article_list_item and article_content schemas (Preview-only); show them in the retrieve/stage/publish 200 examples - Fix stage/publish 422 examples to the real {message, status} shape and add the multilingual-locales and locale-without-pending-changes examples - Clarify the GET /draft 404 (empty body when no draft), note that only versioned text content is staged, and state the Intercom-Version: Preview requirement Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * Address review: shared error $refs and schema-conformant 422 examples - Use Pattern B shared responses ($ref) for 401 (Unauthorized) and 404 (ObjectNotFound) per openapi-conventions.md - Resolve the GET /draft 404 empty-body/schema contradiction by referencing ObjectNotFound (the no-draft trigger is already in the operation description) - Revert the stage/publish 422 examples to the schema-conformant {code, message} shape (the error schema requires code; status was non-conformant) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent ebefd5f commit 7be2e63

1 file changed

Lines changed: 296 additions & 0 deletions

File tree

‎descriptions/0/api.intercom.io.yaml‎

Lines changed: 296 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1690,6 +1690,254 @@ paths:
16901690
message: Access Token Invalid
16911691
schema:
16921692
"$ref": "#/components/schemas/error"
1693+
"/articles/{id}/draft":
1694+
get:
1695+
summary: Retrieve an article draft
1696+
parameters:
1697+
- name: Intercom-Version
1698+
in: header
1699+
schema:
1700+
"$ref": "#/components/schemas/intercom_version"
1701+
- name: id
1702+
in: path
1703+
required: true
1704+
description: The unique identifier for the article which is given by Intercom.
1705+
example: 123
1706+
schema:
1707+
type: integer
1708+
tags:
1709+
- Articles
1710+
operationId: retrieveArticleDraft
1711+
description: |
1712+
Fetch the staged draft of a published article by making a GET request to
1713+
`https://api.intercom.io/articles/<id>/draft`. The response is the article
1714+
rendered with its draft content, leaving the live article untouched.
1715+
1716+
A draft exists only when a published article has unpublished changes staged
1717+
on top of it. Returns `404` when the article has no staged draft.
1718+
1719+
Requires the `read_articles_scope` OAuth scope. Set `Intercom-Version: Preview`.
1720+
responses:
1721+
'200':
1722+
description: Article draft found
1723+
content:
1724+
application/json:
1725+
examples:
1726+
Article draft found:
1727+
value:
1728+
id: '45'
1729+
type: article
1730+
workspace_id: this_is_an_id74_that_should_be_at_least_4
1731+
parent_ids: []
1732+
title: This is the draft title
1733+
description: ''
1734+
body: <p class="no-margin">Unpublished changes staged as a draft</p>
1735+
body_markdown: "Unpublished changes staged as a draft\n"
1736+
author_id: 991267502
1737+
state: published
1738+
created_at: 1734537292
1739+
updated_at: 1734537292
1740+
has_unpublished_changes: true
1741+
draft_updated_at: 1734537292
1742+
url: http://help-center.test/myapp-74/en/articles/45-this-is-the-article-title
1743+
ai_chatbot_availability: true
1744+
ai_copilot_availability: true
1745+
ai_sales_agent_availability: true
1746+
schema:
1747+
"$ref": "#/components/schemas/article"
1748+
'404':
1749+
"$ref": "#/components/responses/ObjectNotFound"
1750+
'401':
1751+
"$ref": "#/components/responses/Unauthorized"
1752+
put:
1753+
summary: Stage an article draft
1754+
parameters:
1755+
- name: Intercom-Version
1756+
in: header
1757+
schema:
1758+
"$ref": "#/components/schemas/intercom_version"
1759+
- name: id
1760+
in: path
1761+
required: true
1762+
description: The unique identifier for the article which is given by Intercom.
1763+
example: 123
1764+
schema:
1765+
type: integer
1766+
tags:
1767+
- Articles
1768+
operationId: stageArticleDraft
1769+
description: |
1770+
Stage changes to a published article as a draft by making a PUT request to
1771+
`https://api.intercom.io/articles/<id>/draft`. The live article remains
1772+
unchanged until the draft is published.
1773+
1774+
The article must already be published; staging a draft on an article that
1775+
has never been published returns `422`.
1776+
1777+
Only versioned text content (such as `title` and `body`) is staged.
1778+
Non-versioned fields like AI availability are ignored, leaving the live
1779+
values untouched.
1780+
1781+
Requires the `read_write_articles_scope` OAuth scope. Set `Intercom-Version: Preview`.
1782+
responses:
1783+
'200':
1784+
description: Draft staged
1785+
content:
1786+
application/json:
1787+
examples:
1788+
Draft staged:
1789+
value:
1790+
id: '48'
1791+
type: article
1792+
workspace_id: this_is_an_id80_that_should_be_at_least_4
1793+
parent_ids: []
1794+
title: Christmas is here!
1795+
description: ''
1796+
body: <p class="no-margin">New gifts in store for the jolly season</p>
1797+
body_markdown: "New gifts in store for the jolly season\n"
1798+
author_id: 991267508
1799+
state: published
1800+
created_at: 1734537297
1801+
updated_at: 1734537298
1802+
has_unpublished_changes: true
1803+
draft_updated_at: 1734537298
1804+
url: http://help-center.test/myapp-80/en/articles/48-christmas-is-here
1805+
ai_chatbot_availability: true
1806+
ai_copilot_availability: true
1807+
ai_sales_agent_availability: true
1808+
schema:
1809+
"$ref": "#/components/schemas/article"
1810+
'404':
1811+
"$ref": "#/components/responses/ObjectNotFound"
1812+
'422':
1813+
description: Article must be published before a draft can be staged
1814+
content:
1815+
application/json:
1816+
examples:
1817+
Article not published:
1818+
value:
1819+
type: error.list
1820+
request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f
1821+
errors:
1822+
- code: parameter_invalid
1823+
message: Article must be published before a draft can be staged
1824+
schema:
1825+
"$ref": "#/components/schemas/error"
1826+
'401':
1827+
"$ref": "#/components/responses/Unauthorized"
1828+
requestBody:
1829+
content:
1830+
application/json:
1831+
schema:
1832+
"$ref": "#/components/schemas/update_article_request"
1833+
examples:
1834+
Draft staged:
1835+
summary: Stage a draft
1836+
value:
1837+
title: Christmas is here!
1838+
body: "<p>New gifts in store for the jolly season</p>"
1839+
"/articles/{id}/draft/publish":
1840+
post:
1841+
summary: Publish an article draft
1842+
parameters:
1843+
- name: Intercom-Version
1844+
in: header
1845+
schema:
1846+
"$ref": "#/components/schemas/intercom_version"
1847+
- name: id
1848+
in: path
1849+
required: true
1850+
description: The unique identifier for the article which is given by Intercom.
1851+
example: 123
1852+
schema:
1853+
type: integer
1854+
tags:
1855+
- Articles
1856+
operationId: publishArticleDraft
1857+
description: |
1858+
Publish a staged draft by making a POST request to
1859+
`https://api.intercom.io/articles/<id>/draft/publish`, promoting the draft
1860+
content to live.
1861+
1862+
On a single-language workspace no body is required. On a multilingual
1863+
workspace you must list which locales to publish via the `locales` array;
1864+
omitting it returns `422`. Returns `422` when there is no staged draft to
1865+
publish, or when a requested locale has no pending changes.
1866+
1867+
Requires the `read_write_articles_scope` OAuth scope. Set `Intercom-Version: Preview`.
1868+
responses:
1869+
'200':
1870+
description: Draft published
1871+
content:
1872+
application/json:
1873+
examples:
1874+
Draft published:
1875+
value:
1876+
id: '48'
1877+
type: article
1878+
workspace_id: this_is_an_id80_that_should_be_at_least_4
1879+
parent_ids: []
1880+
title: Christmas is here!
1881+
description: ''
1882+
body: <p class="no-margin">New gifts in store for the jolly season</p>
1883+
body_markdown: "New gifts in store for the jolly season\n"
1884+
author_id: 991267508
1885+
state: published
1886+
created_at: 1734537297
1887+
updated_at: 1734537299
1888+
has_unpublished_changes: false
1889+
draft_updated_at: null
1890+
url: http://help-center.test/myapp-80/en/articles/48-christmas-is-here
1891+
ai_chatbot_availability: true
1892+
ai_copilot_availability: true
1893+
ai_sales_agent_availability: true
1894+
schema:
1895+
"$ref": "#/components/schemas/article"
1896+
'404':
1897+
"$ref": "#/components/responses/ObjectNotFound"
1898+
'422':
1899+
description: No draft to publish, locales not specified on a multilingual workspace, or a requested locale has no pending changes
1900+
content:
1901+
application/json:
1902+
examples:
1903+
No draft to publish:
1904+
value:
1905+
type: error.list
1906+
request_id: 8a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d
1907+
errors:
1908+
- code: parameter_invalid
1909+
message: Article has no draft to publish
1910+
Locales required on a multilingual workspace:
1911+
value:
1912+
type: error.list
1913+
request_id: 9b2c3d4e-5f6a-7b8c-9d0e-1f2a3b4c5d6e
1914+
errors:
1915+
- code: parameter_not_found
1916+
message: locales must be specified to publish a draft on a multilingual workspace
1917+
Locale has no pending changes:
1918+
value:
1919+
type: error.list
1920+
request_id: 0c3d4e5f-6a7b-8c9d-0e1f-2a3b4c5d6e7f
1921+
errors:
1922+
- code: parameter_invalid
1923+
message: 'Cannot publish a draft for locale(s) without pending changes: fr'
1924+
schema:
1925+
"$ref": "#/components/schemas/error"
1926+
'401':
1927+
"$ref": "#/components/responses/Unauthorized"
1928+
requestBody:
1929+
required: false
1930+
content:
1931+
application/json:
1932+
schema:
1933+
"$ref": "#/components/schemas/publish_article_draft_request"
1934+
examples:
1935+
Publish specific locales:
1936+
summary: Publish specific locales on a multilingual workspace
1937+
value:
1938+
locales:
1939+
- en
1940+
- fr
16931941
"/articles/search":
16941942
get:
16951943
summary: Search for articles
@@ -23577,6 +23825,20 @@ components:
2357723825
format: date-time
2357823826
description: The time when the article was last updated (seconds).
2357923827
example: 1663597260
23828+
has_unpublished_changes:
23829+
type: boolean
23830+
description: Whether this locale's published content has unpublished
23831+
changes staged as a draft on top of its live content. Only returned on
23832+
the `Preview` API version.
23833+
example: false
23834+
draft_updated_at:
23835+
type: integer
23836+
format: date-time
23837+
nullable: true
23838+
description: The time, in seconds, when this locale's staged draft was
23839+
last edited, or `null` when there is no staged draft. Only returned on
23840+
the `Preview` API version.
23841+
example: 1663597260
2358023842
url:
2358123843
type: string
2358223844
description: The URL of the article.
@@ -23799,6 +24061,21 @@ components:
2379924061
articles, this will be the timestamp of last update of the default language's
2380024062
content in seconds.
2380124063
example: 1672928610
24064+
has_unpublished_changes:
24065+
type: boolean
24066+
description: Whether the published article has unpublished changes staged
24067+
as a draft on top of its live content. Only returned on the `Preview`
24068+
API version. For multilingual articles this reflects the default
24069+
language's content; a pure draft (never published) reports `false`.
24070+
example: false
24071+
draft_updated_at:
24072+
type: integer
24073+
format: date-time
24074+
nullable: true
24075+
description: The time, in seconds, when the staged draft was last edited,
24076+
or `null` when there is no staged draft. Only returned on the `Preview`
24077+
API version.
24078+
example: 1672928610
2380224079
url:
2380324080
type: string
2380424081
nullable: true
@@ -34585,6 +34862,25 @@ components:
3458534862
type: role
3458634863
comparison: eq
3458734864
value: user
34865+
publish_article_draft_request:
34866+
description: |
34867+
Optional body for publishing a staged article draft. On a single-language
34868+
workspace the body can be omitted. On a multilingual workspace, `locales`
34869+
is required and lists which locales' drafts to publish.
34870+
type: object
34871+
title: Publish Article Draft Request Payload
34872+
nullable: true
34873+
properties:
34874+
locales:
34875+
type: array
34876+
description: |
34877+
The locales whose staged drafts should be published. Required on
34878+
multilingual workspaces; each locale must have a pending draft.
34879+
items:
34880+
type: string
34881+
example:
34882+
- en
34883+
- fr
3458834884
update_article_request:
3458934885
description: You can Update an Article
3459034886
type: object

0 commit comments

Comments
 (0)