From 45b2868b0523262076771e671104b9837ee2f7da Mon Sep 17 00:00:00 2001 From: kilian-tennyson Date: Thu, 18 Jun 2026 09:30:40 +0100 Subject: [PATCH 1/2] Document update_tags bulk action on /content/bulk_actions (Preview) Add the sixth action, update_tags, to the content_bulk_action_request schema and the endpoint docs: action enum value, the tags request block (add_tag_ids/remove_tag_ids), and the new article content type. Documents the key asymmetry: update_tags addresses articles by the parent article id (not article_content), unlike the other five actions. Tags must already exist and be non-archived (else parameter_invalid, HTTP 422). Verified against intercom/intercom#524459. Other five actions unchanged. --- descriptions/0/api.intercom.io.yaml | 43 ++++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 78f40b0..1a27112 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -9003,11 +9003,15 @@ paths: description: | Asynchronously run a bulk action over up to 1,000 Knowledge Hub content items. - Five actions are supported: + Six actions are supported: * `publish` and `unpublish` — apply to `article_content` only. * `delete` — permanently delete content (excludes synced sources and `external_content`). * `set_availability` — toggle Fin AI Agent, Copilot, and Sales Agent availability flags. * `set_audience` — manage segment membership on content. + * `update_tags` — apply and/or remove existing tags on content. Unlike the other + actions, `update_tags` addresses articles by the parent `article` id, not + `article_content`. Tags must already exist and not be archived; supply at least one of + `add_tag_ids` / `remove_tag_ids`. The endpoint validates the request, enqueues background work, and returns 202 with a placeholder envelope. Items whose `type` is not in the action's allowlist are silently @@ -9111,6 +9115,18 @@ paths: - 100 remove_segment_ids: - 200 + update_tags: + summary: Apply and remove tags on an article + value: + action: update_tags + content_ids: + - type: article + id: '12345678' + tags: + add_tag_ids: + - 100 + remove_tag_ids: + - 200 "/content/search": get: summary: Search knowledge base contents @@ -27142,12 +27158,14 @@ components: * `publish`, `unpublish`: `article_content` * `delete`: `article_content`, `content_snippet`, `file_source_content`, `internal_article` * `set_availability`, `set_audience`: `article_content`, `content_snippet`, `external_content`, `file_source_content`, `internal_article` + * `update_tags`: `article` (the parent Article id, not `article_content`), `content_snippet`, `external_content`, `file_source_content`, `internal_article` enum: - publish - unpublish - delete - set_availability - set_audience + - update_tags example: publish content_ids: type: array @@ -27162,6 +27180,7 @@ components: type: type: string enum: + - article - article_content - content_snippet - external_content @@ -27208,6 +27227,28 @@ components: type: boolean description: When `true`, removes all segments from the selected content. example: false + tags: + type: object + description: | + Required when `action` is `update_tags`. Applies and/or removes existing tags. + Supply at least one of `add_tag_ids` / `remove_tag_ids`. Tag IDs must reference + existing, non-archived tags; unknown or archived IDs are rejected with + `parameter_invalid` (HTTP 422). + properties: + add_tag_ids: + type: array + description: Tag IDs to apply to the selected content. + items: + type: integer + example: + - 100 + remove_tag_ids: + type: array + description: Tag IDs to remove from the selected content. + items: + type: integer + example: + - 200 content_bulk_action_response: title: Content Bulk Action Response Envelope type: object From 7563e7db1a15e742f6f2bf51b2c11e4a69eeff81 Mon Sep 17 00:00:00 2001 From: kilian-tennyson Date: Thu, 18 Jun 2026 09:42:41 +0100 Subject: [PATCH 2/2] Document 100 distinct-tag-id cap on update_tags (review fix) The controller caps the combined unique count of add_tag_ids + remove_tag_ids at MAX_TAG_IDS=100 (validate_tags_live!), rejecting excess with parameter_invalid/HTTP 422. Note the cap in the tags description prose (combined unique count, so not expressible as per-array maxItems). --- descriptions/0/api.intercom.io.yaml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 1a27112..5dc8074 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -27231,9 +27231,10 @@ components: type: object description: | Required when `action` is `update_tags`. Applies and/or removes existing tags. - Supply at least one of `add_tag_ids` / `remove_tag_ids`. Tag IDs must reference - existing, non-archived tags; unknown or archived IDs are rejected with - `parameter_invalid` (HTTP 422). + Supply at least one of `add_tag_ids` / `remove_tag_ids`. At most 100 distinct tag IDs + may be supplied across `add_tag_ids` and `remove_tag_ids` combined. Tag IDs must + reference existing, non-archived tags; exceeding the limit or referencing unknown or + archived IDs is rejected with `parameter_invalid` (HTTP 422). properties: add_tag_ids: type: array