diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 3f4ebff..7f9c031 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -1640,6 +1640,254 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + "/articles/{id}/draft": + get: + summary: Retrieve an article draft + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: id + in: path + required: true + description: The unique identifier for the article which is given by Intercom. + example: 123 + schema: + type: integer + tags: + - Articles + operationId: retrieveArticleDraft + description: | + 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`. + responses: + '200': + description: Article draft found + content: + application/json: + examples: + Article draft found: + value: + id: '45' + type: article + workspace_id: this_is_an_id74_that_should_be_at_least_4 + parent_ids: [] + title: This is the draft title + description: '' + body:

Unpublished changes staged as a draft

+ body_markdown: "Unpublished changes staged as a draft\n" + author_id: 991267502 + state: published + created_at: 1734537292 + updated_at: 1734537292 + has_unpublished_changes: true + draft_updated_at: 1734537292 + url: http://help-center.test/myapp-74/en/articles/45-this-is-the-article-title + ai_chatbot_availability: true + ai_copilot_availability: true + ai_sales_agent_availability: true + schema: + "$ref": "#/components/schemas/article" + '404': + "$ref": "#/components/responses/ObjectNotFound" + '401': + "$ref": "#/components/responses/Unauthorized" + put: + summary: Stage an article draft + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: id + in: path + required: true + description: The unique identifier for the article which is given by Intercom. + example: 123 + schema: + type: integer + tags: + - Articles + operationId: stageArticleDraft + description: | + 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`. + responses: + '200': + description: Draft staged + content: + application/json: + examples: + Draft staged: + value: + id: '48' + type: article + workspace_id: this_is_an_id80_that_should_be_at_least_4 + parent_ids: [] + title: Christmas is here! + description: '' + body:

New gifts in store for the jolly season

+ 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 + schema: + "$ref": "#/components/schemas/article" + '404': + "$ref": "#/components/responses/ObjectNotFound" + '422': + description: Article must be published before a draft can be staged + content: + application/json: + examples: + Article not published: + value: + type: error.list + request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f + errors: + - code: parameter_invalid + message: Article must be published before a draft can be staged + schema: + "$ref": "#/components/schemas/error" + '401': + "$ref": "#/components/responses/Unauthorized" + requestBody: + content: + application/json: + schema: + "$ref": "#/components/schemas/update_article_request" + examples: + Draft staged: + summary: Stage a draft + value: + title: Christmas is here! + body: "

New gifts in store for the jolly season

" + "/articles/{id}/draft/publish": + post: + summary: Publish an article draft + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: id + in: path + required: true + description: The unique identifier for the article which is given by Intercom. + example: 123 + schema: + type: integer + tags: + - Articles + operationId: publishArticleDraft + description: | + 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`. + responses: + '200': + description: Draft published + content: + application/json: + examples: + Draft published: + value: + id: '48' + type: article + workspace_id: this_is_an_id80_that_should_be_at_least_4 + parent_ids: [] + title: Christmas is here! + description: '' + body:

New gifts in store for the jolly season

+ body_markdown: "New gifts in store for the jolly season\n" + author_id: 991267508 + state: published + created_at: 1734537297 + updated_at: 1734537299 + has_unpublished_changes: false + draft_updated_at: null + 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 + schema: + "$ref": "#/components/schemas/article" + '404': + "$ref": "#/components/responses/ObjectNotFound" + '422': + description: No draft to publish, locales not specified on a multilingual workspace, or a requested locale has no pending changes + content: + application/json: + examples: + No draft to publish: + value: + type: error.list + request_id: 8a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d + errors: + - code: parameter_invalid + message: Article has no draft to publish + Locales required on a multilingual workspace: + value: + type: error.list + request_id: 9b2c3d4e-5f6a-7b8c-9d0e-1f2a3b4c5d6e + errors: + - code: parameter_not_found + message: locales must be specified to publish a draft on a multilingual workspace + Locale has no pending changes: + value: + type: error.list + request_id: 0c3d4e5f-6a7b-8c9d-0e1f-2a3b4c5d6e7f + errors: + - code: parameter_invalid + message: 'Cannot publish a draft for locale(s) without pending changes: fr' + schema: + "$ref": "#/components/schemas/error" + '401': + "$ref": "#/components/responses/Unauthorized" + requestBody: + required: false + content: + application/json: + schema: + "$ref": "#/components/schemas/publish_article_draft_request" + examples: + Publish specific locales: + summary: Publish specific locales on a multilingual workspace + value: + locales: + - en + - fr "/articles/search": get: summary: Search for articles @@ -22756,6 +23004,20 @@ components: format: date-time description: The time when the article was last updated (seconds). example: 1663597260 + has_unpublished_changes: + type: boolean + description: Whether this locale's published content has unpublished + changes staged as a draft on top of its live content. Only returned on + the `Preview` API version. + example: false + draft_updated_at: + type: integer + format: date-time + nullable: true + description: The time, in seconds, when this locale's staged draft was + last edited, or `null` when there is no staged draft. Only returned on + the `Preview` API version. + example: 1663597260 url: type: string description: The URL of the article. @@ -22978,6 +23240,21 @@ components: articles, this will be the timestamp of last update of the default language's content in seconds. example: 1672928610 + has_unpublished_changes: + type: boolean + description: 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_at: + type: integer + format: date-time + nullable: true + description: 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 url: type: string nullable: true @@ -33575,6 +33852,25 @@ components: type: role comparison: eq value: user + publish_article_draft_request: + description: | + Optional body for publishing a staged article draft. On a single-language + workspace the body can be omitted. On a multilingual workspace, `locales` + is required and lists which locales' drafts to publish. + type: object + title: Publish Article Draft Request Payload + nullable: true + properties: + locales: + type: array + description: | + The locales whose staged drafts should be published. Required on + multilingual workspaces; each locale must have a pending draft. + items: + type: string + example: + - en + - fr update_article_request: description: You can Update an Article type: object