From 6b44930898c7dee3f5ef4581578cb0b2d71b3e1a Mon Sep 17 00:00:00 2001 From: Mark Dennis Date: Thu, 26 Feb 2026 11:18:04 +0000 Subject: [PATCH 1/3] Add article tags limitation callout to createArticle and updateArticle Tags cannot be managed via the Articles API, but this wasn't documented on the create/update endpoints. Adds the same callout format used by listArticles to prevent confusion when developers attempt to set tags. Co-Authored-By: Claude Opus 4.6 --- descriptions/2.14/api.intercom.io.yaml | 14 +++++++++++--- descriptions/2.15/api.intercom.io.yaml | 14 +++++++++++--- 2 files changed, 22 insertions(+), 6 deletions(-) diff --git a/descriptions/2.14/api.intercom.io.yaml b/descriptions/2.14/api.intercom.io.yaml index 13d7cd5..c1a677a 100644 --- a/descriptions/2.14/api.intercom.io.yaml +++ b/descriptions/2.14/api.intercom.io.yaml @@ -1041,7 +1041,11 @@ paths: tags: - Articles operationId: createArticle - description: You can create a new article by making a POST request to `https://api.intercom.io/articles`. + description: "You can create a new article by making a POST request to `https://api.intercom.io/articles`.\n\n> + \U0001F4D8 Tags cannot be managed via the Articles API\n>\n> While article tags are + returned in API responses, you cannot create, update, or delete tags through + the `/articles` endpoints. To manage article tags, use the Intercom UI or + the dedicated Tags API endpoints.\n" responses: '200': description: article created @@ -1236,8 +1240,12 @@ paths: tags: - Articles operationId: updateArticle - description: You can update the details of a single article by making a PUT - request to `https://api.intercom.io/articles/`. + description: "You can update the details of a single article by making a PUT + request to `https://api.intercom.io/articles/`.\n\n> \U0001F4D8 Tags cannot be + managed via the Articles API\n>\n> While article tags are returned in API + responses, you cannot create, update, or delete tags through the `/articles` + endpoints. To manage article tags, use the Intercom UI or the dedicated Tags + API endpoints.\n" responses: '200': description: successful diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index 967b0fb..070328e 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -1041,7 +1041,11 @@ paths: tags: - Articles operationId: createArticle - description: You can create a new article by making a POST request to `https://api.intercom.io/articles`. + description: "You can create a new article by making a POST request to `https://api.intercom.io/articles`.\n\n> + \U0001F4D8 Tags cannot be managed via the Articles API\n>\n> While article tags are + returned in API responses, you cannot create, update, or delete tags through + the `/articles` endpoints. To manage article tags, use the Intercom UI or + the dedicated Tags API endpoints.\n" responses: '200': description: article created @@ -1236,8 +1240,12 @@ paths: tags: - Articles operationId: updateArticle - description: You can update the details of a single article by making a PUT - request to `https://api.intercom.io/articles/`. + description: "You can update the details of a single article by making a PUT + request to `https://api.intercom.io/articles/`.\n\n> \U0001F4D8 Tags cannot be + managed via the Articles API\n>\n> While article tags are returned in API + responses, you cannot create, update, or delete tags through the `/articles` + endpoints. To manage article tags, use the Intercom UI or the dedicated Tags + API endpoints.\n" responses: '200': description: successful From 985cef59ae05fead16c3538406d8358df652dd20 Mon Sep 17 00:00:00 2001 From: Mark Dennis Date: Thu, 26 Feb 2026 11:54:14 +0000 Subject: [PATCH 2/3] Trim article tags callout body text Shorten the verbose callout to a single concise sentence while keeping the title and actionable guidance intact. Co-Authored-By: Claude Opus 4.6 --- descriptions/2.14/api.intercom.io.yaml | 14 ++++++-------- descriptions/2.15/api.intercom.io.yaml | 14 ++++++-------- 2 files changed, 12 insertions(+), 16 deletions(-) diff --git a/descriptions/2.14/api.intercom.io.yaml b/descriptions/2.14/api.intercom.io.yaml index c1a677a..f2b0fb8 100644 --- a/descriptions/2.14/api.intercom.io.yaml +++ b/descriptions/2.14/api.intercom.io.yaml @@ -1042,10 +1042,9 @@ paths: - Articles operationId: createArticle description: "You can create a new article by making a POST request to `https://api.intercom.io/articles`.\n\n> - \U0001F4D8 Tags cannot be managed via the Articles API\n>\n> While article tags are - returned in API responses, you cannot create, update, or delete tags through - the `/articles` endpoints. To manage article tags, use the Intercom UI or - the dedicated Tags API endpoints.\n" + \U0001F4D8 Tags cannot be managed via the Articles API\n>\n> Article tags are + read-only in responses. To create, update, or delete tags, use the Intercom + UI or the Tags API endpoints.\n" responses: '200': description: article created @@ -1242,10 +1241,9 @@ paths: operationId: updateArticle description: "You can update the details of a single article by making a PUT request to `https://api.intercom.io/articles/`.\n\n> \U0001F4D8 Tags cannot be - managed via the Articles API\n>\n> While article tags are returned in API - responses, you cannot create, update, or delete tags through the `/articles` - endpoints. To manage article tags, use the Intercom UI or the dedicated Tags - API endpoints.\n" + managed via the Articles API\n>\n> Article tags are read-only in responses. + To create, update, or delete tags, use the Intercom UI or the Tags API + endpoints.\n" responses: '200': description: successful diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index 070328e..98f220e 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -1042,10 +1042,9 @@ paths: - Articles operationId: createArticle description: "You can create a new article by making a POST request to `https://api.intercom.io/articles`.\n\n> - \U0001F4D8 Tags cannot be managed via the Articles API\n>\n> While article tags are - returned in API responses, you cannot create, update, or delete tags through - the `/articles` endpoints. To manage article tags, use the Intercom UI or - the dedicated Tags API endpoints.\n" + \U0001F4D8 Tags cannot be managed via the Articles API\n>\n> Article tags are + read-only in responses. To create, update, or delete tags, use the Intercom + UI or the Tags API endpoints.\n" responses: '200': description: article created @@ -1242,10 +1241,9 @@ paths: operationId: updateArticle description: "You can update the details of a single article by making a PUT request to `https://api.intercom.io/articles/`.\n\n> \U0001F4D8 Tags cannot be - managed via the Articles API\n>\n> While article tags are returned in API - responses, you cannot create, update, or delete tags through the `/articles` - endpoints. To manage article tags, use the Intercom UI or the dedicated Tags - API endpoints.\n" + managed via the Articles API\n>\n> Article tags are read-only in responses. + To create, update, or delete tags, use the Intercom UI or the Tags API + endpoints.\n" responses: '200': description: successful From 9d629cd766bd5be77c585d3b741dfa17c63617c9 Mon Sep 17 00:00:00 2001 From: Mark Dennis Date: Thu, 26 Feb 2026 13:38:42 +0000 Subject: [PATCH 3/3] Add article tags callout to Unstable (0) version MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Missed this version in the initial commit — aligns with the developer-docs @Unstable spec which already has the callout. Co-Authored-By: Claude Opus 4.6 --- descriptions/0/api.intercom.io.yaml | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 8d08f5b..130b8ed 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -1041,7 +1041,10 @@ paths: tags: - Articles operationId: createArticle - description: You can create a new article by making a POST request to `https://api.intercom.io/articles`. + description: "You can create a new article by making a POST request to `https://api.intercom.io/articles`.\n\n> + \U0001F4D8 Tags cannot be managed via the Articles API\n>\n> Article tags are + read-only in responses. To create, update, or delete tags, use the Intercom + UI or the Tags API endpoints.\n" responses: '200': description: article created @@ -1236,8 +1239,11 @@ paths: tags: - Articles operationId: updateArticle - description: You can update the details of a single article by making a PUT - request to `https://api.intercom.io/articles/`. + description: "You can update the details of a single article by making a PUT + request to `https://api.intercom.io/articles/`.\n\n> \U0001F4D8 Tags cannot be + managed via the Articles API\n>\n> Article tags are read-only in responses. + To create, update, or delete tags, use the Intercom UI or the Tags API + endpoints.\n" responses: '200': description: successful