Correct the state description on the update article request - #628
Conversation
Sorry, something went wrong.
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) <noreply@anthropic.com>
joshuacorcoran-blip
left a comment
There was a problem hiding this comment.
Some minor nits but overall looks good.
MEDIUM — descriptions/0/api.intercom.io.yaml:40090
Customer-facing copy not updated. intercom/developer-docs still says "Defaults to draft" (verified @2.16, lines 27813 and 34562), and there's no companion PR. If this merges alone, the misleading sentence stays live on developers.intercom.com and the reader this PR is trying to protect still gets it wrong.
LOW — descriptions/2.16/api.intercom.io.yaml:34593
The new sentence stops short of the real surprise: omitting state on an already-published article publishes the edit immediately. Only an article with a pending draft holds it back. One clause would cover it.
LOW — descriptions/2.16/api.intercom.io.yaml:34593
In 2.16 and Preview, this same schema is also the request body for PUT /articles/{id}/draft, where state is ignored outright (update.rb:216). Pre-existing, but this is the natural place to say so.
Sorry, something went wrong.
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) <noreply@anthropic.com>
joshuacorcoran-blip
left a comment
There was a problem hiding this comment.
LGTM
Sorry, something went wrong.
Why?
The state field on the update article request says it defaults to draft. It doesn't. Leaving it out keeps the article's current publish state, and an edit to a published article goes live immediately unless that article already has a pending draft, so anyone following the docs could expect their edit to be staged when it isn't.
How?
Reworded that description across all API versions, and on the versions that have scheduled publishing or a draft endpoint, said how those interact with an omitted state. The create request still says it defaults to draft, which is accurate there.