From 327c405863f9599ed1ccacd9fb4bf67944d74a91 Mon Sep 17 00:00:00 2001 From: kilian-tennyson Date: Tue, 16 Jun 2026 15:00:09 +0100 Subject: [PATCH 1/3] Document public content-tagging endpoints in Preview OpenAPI spec Add the four public v3 content-tagging endpoints to the Preview spec (descriptions/0/api.intercom.io.yaml): POST /articles/{article_id}/tags DELETE /articles/{article_id}/tags/{id} POST /content_snippets/{content_snippet_id}/tags DELETE /content_snippets/{content_snippet_id}/tags/{id} These document the implementation shipped in intercom/intercom#523830 (apply/remove an existing tag on articles + KB content snippets). The endpoints are Preview-gated via the intercom_version_preview header, reuse the existing tag/error schemas and the Unauthorized response, and document the read_write_articles_scope / read_write_content_snippets OAuth scopes plus the 403 (forbidden) and 404 (article/snippet/tag not found) responses. Companion to intercom/intercom#523830. --- descriptions/0/api.intercom.io.yaml | 382 ++++++++++++++++++++++++++++ 1 file changed, 382 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 84dd93e..39b414d 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -2128,6 +2128,197 @@ paths: "$ref": "#/components/responses/ObjectNotFound" '401': "$ref": "#/components/responses/Unauthorized" + "/articles/{article_id}/tags": + post: + summary: Add a tag to an article + tags: + - Articles + - Tags + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version_preview" + - name: article_id + in: path + required: true + description: The unique identifier for the article which is given by Intercom. + example: 123 + schema: + type: integer + operationId: attachTagToArticle + description: | + Apply an existing tag to an article. Returns the tag that was applied. + + The tag must already exist in the workspace (create tags with the Tags API), + and the authenticating teammate must have the `manage_knowledge_base_content` + permission. + + Requires the `read_write_articles_scope` OAuth scope. Set `Intercom-Version: Preview`. + requestBody: + content: + application/json: + schema: + type: object + required: + - id + properties: + id: + type: string + description: The unique identifier of the tag to apply, as given by + Intercom. + example: '7522907' + admin_id: + type: string + nullable: true + description: Optional id of the teammate to attribute the tagging to. + Defaults to the authenticating teammate. Does not affect authorization. + example: '1234' + examples: + successful: + summary: Apply a tag + value: + id: '7522907' + responses: + '200': + description: Tag applied + content: + application/json: + examples: + Tag applied: + value: + type: tag + id: '7522907' + name: Independent + applied_at: 1663597223 + applied_by: + type: admin + id: '1234' + schema: + "$ref": "#/components/schemas/tag" + '403': + description: Forbidden + content: + application/json: + examples: + Forbidden: + value: + type: error.list + request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f + errors: + - code: forbidden + message: Not authorized to manage knowledge base content + schema: + "$ref": "#/components/schemas/error" + '404': + description: Article or tag not found + content: + application/json: + examples: + Article not found: + value: + type: error.list + request_id: 302049fb-b8c1-4dc8-a327-a8f6e1923484 + errors: + - code: article_not_found + message: Article not found + Tag not found: + value: + type: error.list + request_id: 8a3e4f88-ae65-433a-b4eb-46780ffc5402 + errors: + - code: tag_not_found + message: Tag not found + schema: + "$ref": "#/components/schemas/error" + '401': + "$ref": "#/components/responses/Unauthorized" + "/articles/{article_id}/tags/{id}": + delete: + summary: Remove a tag from an article + tags: + - Articles + - Tags + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version_preview" + - name: article_id + in: path + required: true + description: The unique identifier for the article which is given by Intercom. + example: 123 + schema: + type: integer + - name: id + in: path + required: true + description: The unique identifier of the tag to remove, as given by Intercom. + example: '7522907' + schema: + type: string + operationId: detachTagFromArticle + description: | + Remove a tag from an article. Returns the tag that was removed, with null + `applied_at` and `applied_by`. + + The authenticating teammate must have the `manage_knowledge_base_content` + permission. + + Requires the `read_write_articles_scope` OAuth scope. Set `Intercom-Version: Preview`. + responses: + '200': + description: Tag removed + content: + application/json: + examples: + Tag removed: + value: + type: tag + id: '7522907' + name: Independent + applied_at: null + applied_by: null + schema: + "$ref": "#/components/schemas/tag" + '403': + description: Forbidden + content: + application/json: + examples: + Forbidden: + value: + type: error.list + request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f + errors: + - code: forbidden + message: Not authorized to manage knowledge base content + schema: + "$ref": "#/components/schemas/error" + '404': + description: Article or tag not found + content: + application/json: + examples: + Article not found: + value: + type: error.list + request_id: 302049fb-b8c1-4dc8-a327-a8f6e1923484 + errors: + - code: article_not_found + message: Article not found + Tag not found: + value: + type: error.list + request_id: 8a3e4f88-ae65-433a-b4eb-46780ffc5402 + errors: + - code: tag_not_found + message: Tag not found + schema: + "$ref": "#/components/schemas/error" + '401': + "$ref": "#/components/responses/Unauthorized" "/articles/search": get: summary: Search for articles @@ -9757,6 +9948,197 @@ paths: be deleted schema: "$ref": "#/components/schemas/error" + "/content_snippets/{content_snippet_id}/tags": + post: + summary: Add a tag to a content snippet + tags: + - Content Snippets + - Tags + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version_preview" + - name: content_snippet_id + in: path + required: true + description: The unique identifier for the content snippet. + example: '123' + schema: + type: string + operationId: attachTagToContentSnippet + description: | + Apply an existing tag to a content snippet. Returns the tag that was applied. + + The tag must already exist in the workspace (create tags with the Tags API), + and the authenticating teammate must have the `manage_knowledge_base_content` + permission. + + Requires the `read_write_content_snippets` OAuth scope. Set `Intercom-Version: Preview`. + requestBody: + content: + application/json: + schema: + type: object + required: + - id + properties: + id: + type: string + description: The unique identifier of the tag to apply, as given by + Intercom. + example: '7522907' + admin_id: + type: string + nullable: true + description: Optional id of the teammate to attribute the tagging to. + Defaults to the authenticating teammate. Does not affect authorization. + example: '1234' + examples: + successful: + summary: Apply a tag + value: + id: '7522907' + responses: + '200': + description: Tag applied + content: + application/json: + examples: + Tag applied: + value: + type: tag + id: '7522907' + name: Independent + applied_at: 1663597223 + applied_by: + type: admin + id: '1234' + schema: + "$ref": "#/components/schemas/tag" + '403': + description: Forbidden + content: + application/json: + examples: + Forbidden: + value: + type: error.list + request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f + errors: + - code: forbidden + message: Not authorized to manage knowledge base content + schema: + "$ref": "#/components/schemas/error" + '404': + description: Content snippet or tag not found + content: + application/json: + examples: + Content snippet not found: + value: + type: error.list + request_id: 302049fb-b8c1-4dc8-a327-a8f6e1923484 + errors: + - code: content_snippet_not_found + message: Content snippet not found + Tag not found: + value: + type: error.list + request_id: 8a3e4f88-ae65-433a-b4eb-46780ffc5402 + errors: + - code: tag_not_found + message: Tag not found + schema: + "$ref": "#/components/schemas/error" + '401': + "$ref": "#/components/responses/Unauthorized" + "/content_snippets/{content_snippet_id}/tags/{id}": + delete: + summary: Remove a tag from a content snippet + tags: + - Content Snippets + - Tags + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version_preview" + - name: content_snippet_id + in: path + required: true + description: The unique identifier for the content snippet. + example: '123' + schema: + type: string + - name: id + in: path + required: true + description: The unique identifier of the tag to remove, as given by Intercom. + example: '7522907' + schema: + type: string + operationId: detachTagFromContentSnippet + description: | + Remove a tag from a content snippet. Returns the tag that was removed, with + null `applied_at` and `applied_by`. + + The authenticating teammate must have the `manage_knowledge_base_content` + permission. + + Requires the `read_write_content_snippets` OAuth scope. Set `Intercom-Version: Preview`. + responses: + '200': + description: Tag removed + content: + application/json: + examples: + Tag removed: + value: + type: tag + id: '7522907' + name: Independent + applied_at: null + applied_by: null + schema: + "$ref": "#/components/schemas/tag" + '403': + description: Forbidden + content: + application/json: + examples: + Forbidden: + value: + type: error.list + request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f + errors: + - code: forbidden + message: Not authorized to manage knowledge base content + schema: + "$ref": "#/components/schemas/error" + '404': + description: Content snippet or tag not found + content: + application/json: + examples: + Content snippet not found: + value: + type: error.list + request_id: 302049fb-b8c1-4dc8-a327-a8f6e1923484 + errors: + - code: content_snippet_not_found + message: Content snippet not found + Tag not found: + value: + type: error.list + request_id: 8a3e4f88-ae65-433a-b4eb-46780ffc5402 + errors: + - code: tag_not_found + message: Tag not found + schema: + "$ref": "#/components/schemas/error" + '401': + "$ref": "#/components/responses/Unauthorized" "/conversations/{conversation_id}/tags": post: summary: Add tag to a conversation From 158c88d09e19056d5ecf73d1e312ba609a07a4e3 Mon Sep 17 00:00:00 2001 From: kilian-tennyson Date: Thu, 18 Jun 2026 11:57:40 +0100 Subject: [PATCH 2/3] Document internal-article tagging in Preview OpenAPI spec Fold the internal-article tag support shipped in intercom/intercom#524047 into the content-tagging docs: POST /internal_articles/{internal_article_id}/tags DELETE /internal_articles/{internal_article_id}/tags/{id} Plus a version-gated 'tags' field added to the internal-article read responses (GET /internal_articles and GET /internal_articles/{id}) via a $ref to the shared 'tags' schema on internal_article_list_item, mirroring public articles. Write endpoints mirror the articles/content-snippets shape exactly: same {id} body + optional admin_id, same AddContentTaggingApi Preview gate, same VersionedTaggingPresenter response, same 403/404 errors (with an internal_article_not_found case). Internal-article tags ride the read_write_articles_scope OAuth scope (same as public articles), not a separate scope. Companion to intercom/intercom#524047 (and #523830 for articles + KB snippets). --- descriptions/0/api.intercom.io.yaml | 195 ++++++++++++++++++++++++++++ 1 file changed, 195 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 39b414d..524444b 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -5008,6 +5008,199 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + "/internal_articles/{internal_article_id}/tags": + post: + summary: Add a tag to an internal article + tags: + - Internal Articles + - Tags + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version_preview" + - name: internal_article_id + in: path + required: true + description: The unique identifier for the internal article which is given by + Intercom. + example: 123 + schema: + type: integer + operationId: attachTagToInternalArticle + description: | + Apply an existing tag to an internal article. Returns the tag that was applied. + + The tag must already exist in the workspace (create tags with the Tags API), + and the authenticating teammate must have the `manage_knowledge_base_content` + permission. + + Requires the `read_write_articles_scope` OAuth scope. Set `Intercom-Version: Preview`. + requestBody: + content: + application/json: + schema: + type: object + required: + - id + properties: + id: + type: string + description: The unique identifier of the tag to apply, as given by + Intercom. + example: '7522907' + admin_id: + type: string + nullable: true + description: Optional id of the teammate to attribute the tagging to. + Defaults to the authenticating teammate. Does not affect authorization. + example: '1234' + examples: + successful: + summary: Apply a tag + value: + id: '7522907' + responses: + '200': + description: Tag applied + content: + application/json: + examples: + Tag applied: + value: + type: tag + id: '7522907' + name: Independent + applied_at: 1663597223 + applied_by: + type: admin + id: '1234' + schema: + "$ref": "#/components/schemas/tag" + '403': + description: Forbidden + content: + application/json: + examples: + Forbidden: + value: + type: error.list + request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f + errors: + - code: forbidden + message: Not authorized to manage knowledge base content + schema: + "$ref": "#/components/schemas/error" + '404': + description: Internal article or tag not found + content: + application/json: + examples: + Internal article not found: + value: + type: error.list + request_id: 302049fb-b8c1-4dc8-a327-a8f6e1923484 + errors: + - code: internal_article_not_found + message: Internal article not found + Tag not found: + value: + type: error.list + request_id: 8a3e4f88-ae65-433a-b4eb-46780ffc5402 + errors: + - code: tag_not_found + message: Tag not found + schema: + "$ref": "#/components/schemas/error" + '401': + "$ref": "#/components/responses/Unauthorized" + "/internal_articles/{internal_article_id}/tags/{id}": + delete: + summary: Remove a tag from an internal article + tags: + - Internal Articles + - Tags + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version_preview" + - name: internal_article_id + in: path + required: true + description: The unique identifier for the internal article which is given by + Intercom. + example: 123 + schema: + type: integer + - name: id + in: path + required: true + description: The unique identifier of the tag to remove, as given by Intercom. + example: '7522907' + schema: + type: string + operationId: detachTagFromInternalArticle + description: | + Remove a tag from an internal article. Returns the tag that was removed, with + null `applied_at` and `applied_by`. + + The authenticating teammate must have the `manage_knowledge_base_content` + permission. + + Requires the `read_write_articles_scope` OAuth scope. Set `Intercom-Version: Preview`. + responses: + '200': + description: Tag removed + content: + application/json: + examples: + Tag removed: + value: + type: tag + id: '7522907' + name: Independent + applied_at: null + applied_by: null + schema: + "$ref": "#/components/schemas/tag" + '403': + description: Forbidden + content: + application/json: + examples: + Forbidden: + value: + type: error.list + request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f + errors: + - code: forbidden + message: Not authorized to manage knowledge base content + schema: + "$ref": "#/components/schemas/error" + '404': + description: Internal article or tag not found + content: + application/json: + examples: + Internal article not found: + value: + type: error.list + request_id: 302049fb-b8c1-4dc8-a327-a8f6e1923484 + errors: + - code: internal_article_not_found + message: Internal article not found + Tag not found: + value: + type: error.list + request_id: 8a3e4f88-ae65-433a-b4eb-46780ffc5402 + errors: + - code: tag_not_found + message: Tag not found + schema: + "$ref": "#/components/schemas/error" + '401': + "$ref": "#/components/responses/Unauthorized" "/internal_articles/search": get: summary: Search for internal articles @@ -25363,6 +25556,8 @@ components: type: boolean description: Whether the internal article is available for AI Sales Agent. example: true + tags: + "$ref": "#/components/schemas/tags" article_search_highlights: title: Article Search Highlights type: object From 06aed5278b811999cda1d1a7ca8cb358228e4b61 Mon Sep 17 00:00:00 2001 From: kilian-tennyson Date: Fri, 19 Jun 2026 09:29:23 +0100 Subject: [PATCH 3/3] Note Knowledge Hub content in tag applied_at/applied_by descriptions Keep byte-identical with the developer-docs companion: extend the tag schema's applied_at/applied_by descriptions to include articles, internal articles, and content snippets returned by the content-tagging endpoints. --- descriptions/0/api.intercom.io.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 524444b..ab5889f 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -35598,12 +35598,12 @@ components: type: integer format: date-time nullable: true - description: The time when the tag was applied to the object. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket. + description: The time when the tag was applied to the object. Only present when the tag is returned as part of a tagging operation on a contact, conversation, ticket, article, internal article, or content snippet. example: 1663597223 applied_by: type: object nullable: true - description: The admin who applied the tag. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket. + description: The admin who applied the tag. Only present when the tag is returned as part of a tagging operation on a contact, conversation, ticket, article, internal article, or content snippet. allOf: - "$ref": "#/components/schemas/reference" tag_basic: