From ca84f9058a87b88d419fe8db682f2bc57a170258 Mon Sep 17 00:00:00 2001 From: Georgio Sunil Date: Tue, 18 Aug 2026 15:16:49 +0100 Subject: [PATCH 1/2] Correct the update_article state description The update endpoint has no nil-state default: it only unpublishes when the request explicitly asks for "draft". "Defaults to draft" was copy-pasted from create_article_request, where it is accurate. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 5 +++-- descriptions/2.10/api.intercom.io.yaml | 5 +++-- descriptions/2.11/api.intercom.io.yaml | 5 +++-- descriptions/2.12/api.intercom.io.yaml | 5 +++-- descriptions/2.13/api.intercom.io.yaml | 5 +++-- descriptions/2.14/api.intercom.io.yaml | 5 +++-- descriptions/2.15/api.intercom.io.yaml | 5 +++-- descriptions/2.16/api.intercom.io.yaml | 5 +++-- descriptions/2.7/api.intercom.io.yaml | 5 +++-- descriptions/2.8/api.intercom.io.yaml | 5 +++-- descriptions/2.9/api.intercom.io.yaml | 5 +++-- 11 files changed, 33 insertions(+), 22 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 56bb766..ee7867f 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -40087,8 +40087,9 @@ components: state: type: string description: 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. + Omitting this field leaves the current publish state unchanged. For + multilingual articles, this will be the state of the default language's + content. enum: - published - draft diff --git a/descriptions/2.10/api.intercom.io.yaml b/descriptions/2.10/api.intercom.io.yaml index 9899675..b2b2514 100644 --- a/descriptions/2.10/api.intercom.io.yaml +++ b/descriptions/2.10/api.intercom.io.yaml @@ -16812,8 +16812,9 @@ components: state: type: string description: 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. + Omitting this field leaves the current publish state unchanged. For + multilingual articles, this will be the state of the default language's + content. enum: - published - draft diff --git a/descriptions/2.11/api.intercom.io.yaml b/descriptions/2.11/api.intercom.io.yaml index 7fe9f8c..8a3a798 100644 --- a/descriptions/2.11/api.intercom.io.yaml +++ b/descriptions/2.11/api.intercom.io.yaml @@ -18661,8 +18661,9 @@ components: state: type: string description: 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. + Omitting this field leaves the current publish state unchanged. For + multilingual articles, this will be the state of the default language's + content. enum: - published - draft diff --git a/descriptions/2.12/api.intercom.io.yaml b/descriptions/2.12/api.intercom.io.yaml index 70aac5a..05571b4 100644 --- a/descriptions/2.12/api.intercom.io.yaml +++ b/descriptions/2.12/api.intercom.io.yaml @@ -18323,8 +18323,9 @@ components: state: type: string description: 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. + Omitting this field leaves the current publish state unchanged. For + multilingual articles, this will be the state of the default language's + content. enum: - published - draft diff --git a/descriptions/2.13/api.intercom.io.yaml b/descriptions/2.13/api.intercom.io.yaml index d225578..101a6eb 100644 --- a/descriptions/2.13/api.intercom.io.yaml +++ b/descriptions/2.13/api.intercom.io.yaml @@ -20011,8 +20011,9 @@ components: state: type: string description: 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. + Omitting this field leaves the current publish state unchanged. For + multilingual articles, this will be the state of the default language's + content. enum: - published - draft diff --git a/descriptions/2.14/api.intercom.io.yaml b/descriptions/2.14/api.intercom.io.yaml index 2b224f0..8d0f372 100644 --- a/descriptions/2.14/api.intercom.io.yaml +++ b/descriptions/2.14/api.intercom.io.yaml @@ -22738,8 +22738,9 @@ components: state: type: string description: 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. + Omitting this field leaves the current publish state unchanged. For + multilingual articles, this will be the state of the default language's + content. enum: - published - draft diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index 49ae729..7710b25 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -23746,8 +23746,9 @@ components: state: type: string description: 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. + Omitting this field leaves the current publish state unchanged. For + multilingual articles, this will be the state of the default language's + content. enum: - published - draft diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index 5b27176..10e9a73 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -34590,8 +34590,9 @@ components: state: type: string description: 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. + Omitting this field leaves the current publish state unchanged. For + multilingual articles, this will be the state of the default language's + content. enum: - published - draft diff --git a/descriptions/2.7/api.intercom.io.yaml b/descriptions/2.7/api.intercom.io.yaml index 19ea31b..5623ff5 100644 --- a/descriptions/2.7/api.intercom.io.yaml +++ b/descriptions/2.7/api.intercom.io.yaml @@ -14273,8 +14273,9 @@ components: state: type: string description: 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. + Omitting this field leaves the current publish state unchanged. For + multilingual articles, this will be the state of the default language's + content. enum: - published - draft diff --git a/descriptions/2.8/api.intercom.io.yaml b/descriptions/2.8/api.intercom.io.yaml index d8f84ed..53905b3 100644 --- a/descriptions/2.8/api.intercom.io.yaml +++ b/descriptions/2.8/api.intercom.io.yaml @@ -14320,8 +14320,9 @@ components: state: type: string description: 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. + Omitting this field leaves the current publish state unchanged. For + multilingual articles, this will be the state of the default language's + content. enum: - published - draft diff --git a/descriptions/2.9/api.intercom.io.yaml b/descriptions/2.9/api.intercom.io.yaml index c8e7366..c7c43de 100644 --- a/descriptions/2.9/api.intercom.io.yaml +++ b/descriptions/2.9/api.intercom.io.yaml @@ -16131,8 +16131,9 @@ components: state: type: string description: 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. + Omitting this field leaves the current publish state unchanged. For + multilingual articles, this will be the state of the default language's + content. enum: - published - draft From 0e688332f324f190103c43fc7d928ec02c364e39 Mon Sep 17 00:00:00 2001 From: Georgio Sunil Date: Thu, 20 Aug 2026 16:41:20 +0100 Subject: [PATCH 2/2] Reword the state description to cover immediate publishing Also note, on the versions that have them, how scheduled publishing and the draft endpoint interact with an omitted state. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 9 ++++++--- descriptions/2.10/api.intercom.io.yaml | 7 ++++--- descriptions/2.11/api.intercom.io.yaml | 7 ++++--- descriptions/2.12/api.intercom.io.yaml | 7 ++++--- descriptions/2.13/api.intercom.io.yaml | 7 ++++--- descriptions/2.14/api.intercom.io.yaml | 7 ++++--- descriptions/2.15/api.intercom.io.yaml | 7 ++++--- descriptions/2.16/api.intercom.io.yaml | 9 ++++++--- descriptions/2.7/api.intercom.io.yaml | 7 ++++--- descriptions/2.8/api.intercom.io.yaml | 7 ++++--- descriptions/2.9/api.intercom.io.yaml | 7 ++++--- 11 files changed, 48 insertions(+), 33 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index ee7867f..0f3d961 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -40087,9 +40087,12 @@ components: state: type: string description: Whether the article will be `published` or will be a `draft`. - Omitting this field leaves the current publish state unchanged. For - multilingual articles, this will be the state of the default language's - content. + Omitting this field leaves the publish state unchanged, so a draft stays + a draft and an edit to a published article goes live immediately unless + that article already has a pending draft or a scheduled publish time is + set in the same request. The `PUT /articles/{id}/draft` endpoint ignores + this field and always stages a draft. For multilingual articles, this + will be the state of the default language's content. enum: - published - draft diff --git a/descriptions/2.10/api.intercom.io.yaml b/descriptions/2.10/api.intercom.io.yaml index b2b2514..a7992a7 100644 --- a/descriptions/2.10/api.intercom.io.yaml +++ b/descriptions/2.10/api.intercom.io.yaml @@ -16812,9 +16812,10 @@ components: state: type: string description: Whether the article will be `published` or will be a `draft`. - Omitting this field leaves the current publish state unchanged. For - multilingual articles, this will be the state of the default language's - content. + Omitting this field leaves the publish state unchanged, so a draft stays + a draft and an edit to a published article goes live immediately unless + that article already has a pending draft. For multilingual articles, this + will be the state of the default language's content. enum: - published - draft diff --git a/descriptions/2.11/api.intercom.io.yaml b/descriptions/2.11/api.intercom.io.yaml index 8a3a798..bd186a4 100644 --- a/descriptions/2.11/api.intercom.io.yaml +++ b/descriptions/2.11/api.intercom.io.yaml @@ -18661,9 +18661,10 @@ components: state: type: string description: Whether the article will be `published` or will be a `draft`. - Omitting this field leaves the current publish state unchanged. For - multilingual articles, this will be the state of the default language's - content. + Omitting this field leaves the publish state unchanged, so a draft stays + a draft and an edit to a published article goes live immediately unless + that article already has a pending draft. For multilingual articles, this + will be the state of the default language's content. enum: - published - draft diff --git a/descriptions/2.12/api.intercom.io.yaml b/descriptions/2.12/api.intercom.io.yaml index 05571b4..4d5d89c 100644 --- a/descriptions/2.12/api.intercom.io.yaml +++ b/descriptions/2.12/api.intercom.io.yaml @@ -18323,9 +18323,10 @@ components: state: type: string description: Whether the article will be `published` or will be a `draft`. - Omitting this field leaves the current publish state unchanged. For - multilingual articles, this will be the state of the default language's - content. + Omitting this field leaves the publish state unchanged, so a draft stays + a draft and an edit to a published article goes live immediately unless + that article already has a pending draft. For multilingual articles, this + will be the state of the default language's content. enum: - published - draft diff --git a/descriptions/2.13/api.intercom.io.yaml b/descriptions/2.13/api.intercom.io.yaml index 101a6eb..d9813bb 100644 --- a/descriptions/2.13/api.intercom.io.yaml +++ b/descriptions/2.13/api.intercom.io.yaml @@ -20011,9 +20011,10 @@ components: state: type: string description: Whether the article will be `published` or will be a `draft`. - Omitting this field leaves the current publish state unchanged. For - multilingual articles, this will be the state of the default language's - content. + Omitting this field leaves the publish state unchanged, so a draft stays + a draft and an edit to a published article goes live immediately unless + that article already has a pending draft. For multilingual articles, this + will be the state of the default language's content. enum: - published - draft diff --git a/descriptions/2.14/api.intercom.io.yaml b/descriptions/2.14/api.intercom.io.yaml index 8d0f372..c829dd8 100644 --- a/descriptions/2.14/api.intercom.io.yaml +++ b/descriptions/2.14/api.intercom.io.yaml @@ -22738,9 +22738,10 @@ components: state: type: string description: Whether the article will be `published` or will be a `draft`. - Omitting this field leaves the current publish state unchanged. For - multilingual articles, this will be the state of the default language's - content. + Omitting this field leaves the publish state unchanged, so a draft stays + a draft and an edit to a published article goes live immediately unless + that article already has a pending draft. For multilingual articles, this + will be the state of the default language's content. enum: - published - draft diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index 7710b25..6a95759 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -23746,9 +23746,10 @@ components: state: type: string description: Whether the article will be `published` or will be a `draft`. - Omitting this field leaves the current publish state unchanged. For - multilingual articles, this will be the state of the default language's - content. + Omitting this field leaves the publish state unchanged, so a draft stays + a draft and an edit to a published article goes live immediately unless + that article already has a pending draft. For multilingual articles, this + will be the state of the default language's content. enum: - published - draft diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index 10e9a73..afd781b 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -34590,9 +34590,12 @@ components: state: type: string description: Whether the article will be `published` or will be a `draft`. - Omitting this field leaves the current publish state unchanged. For - multilingual articles, this will be the state of the default language's - content. + Omitting this field leaves the publish state unchanged, so a draft stays + a draft and an edit to a published article goes live immediately unless + that article already has a pending draft or a scheduled publish time is + set in the same request. The `PUT /articles/{id}/draft` endpoint ignores + this field and always stages a draft. For multilingual articles, this + will be the state of the default language's content. enum: - published - draft diff --git a/descriptions/2.7/api.intercom.io.yaml b/descriptions/2.7/api.intercom.io.yaml index 5623ff5..8d76a57 100644 --- a/descriptions/2.7/api.intercom.io.yaml +++ b/descriptions/2.7/api.intercom.io.yaml @@ -14273,9 +14273,10 @@ components: state: type: string description: Whether the article will be `published` or will be a `draft`. - Omitting this field leaves the current publish state unchanged. For - multilingual articles, this will be the state of the default language's - content. + Omitting this field leaves the publish state unchanged, so a draft stays + a draft and an edit to a published article goes live immediately unless + that article already has a pending draft. For multilingual articles, this + will be the state of the default language's content. enum: - published - draft diff --git a/descriptions/2.8/api.intercom.io.yaml b/descriptions/2.8/api.intercom.io.yaml index 53905b3..2934e9d 100644 --- a/descriptions/2.8/api.intercom.io.yaml +++ b/descriptions/2.8/api.intercom.io.yaml @@ -14320,9 +14320,10 @@ components: state: type: string description: Whether the article will be `published` or will be a `draft`. - Omitting this field leaves the current publish state unchanged. For - multilingual articles, this will be the state of the default language's - content. + Omitting this field leaves the publish state unchanged, so a draft stays + a draft and an edit to a published article goes live immediately unless + that article already has a pending draft. For multilingual articles, this + will be the state of the default language's content. enum: - published - draft diff --git a/descriptions/2.9/api.intercom.io.yaml b/descriptions/2.9/api.intercom.io.yaml index c7c43de..26c49ea 100644 --- a/descriptions/2.9/api.intercom.io.yaml +++ b/descriptions/2.9/api.intercom.io.yaml @@ -16131,9 +16131,10 @@ components: state: type: string description: Whether the article will be `published` or will be a `draft`. - Omitting this field leaves the current publish state unchanged. For - multilingual articles, this will be the state of the default language's - content. + Omitting this field leaves the publish state unchanged, so a draft stays + a draft and an edit to a published article goes live immediately unless + that article already has a pending draft. For multilingual articles, this + will be the state of the default language's content. enum: - published - draft