# Run a bulk action on Knowledge Hub content (Preview)

Asynchronously run a bulk action over up to 1,000 Knowledge Hub content items.

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 and returns 202.

Important — 202 Accepted does not guarantee every item was processed. Two
classes of items are silently excluded:

  1. Unsupported content type for the action. Items whose type is not in the
     action's allowlist (see the action description) are not included in the bulk
     operation. No per-item error is returned.
  2. Synced content on delete. Articles imported from a synced source
     (Confluence, Notion, Zendesk, Salesforce Knowledge, etc.) are not deletable
     through this endpoint — they can only be removed by disconnecting the underlying
     import source.

For compliance-driven deletions (GDPR right-to-erasure, etc.), do not rely on the
202 Accepted response alone. Verify removal by fetching each item directly
(for example, GET /articles/{id} for article content) or disconnect the import
source for synced content. A future Preview release will expose a polling job
resource with per-item updated, unchanged, skipped, and failed buckets to
make these outcomes explicit.

Requires the write_content OAuth scope. Set Intercom-Version: preview.

Endpoint: POST /content/bulk_actions
Version: Preview
Security: bearerAuth

## Header parameters:

  - `Intercom-Version` (string)
    Preview Intercom API version. Used for closed beta endpoints or other features under managed availability.
    Enum: "preview"

## Request fields (application/json):

  - `action` (string, required)
    The bulk action to perform. Allowed content_ids[].type values vary per action:
  * 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"

  - `content_ids` (array, required)
    Up to 1,000 content items to apply the action to.

  - `content_ids.type` (string, required)
    Enum: "article", "article_content", "content_snippet", "external_content", "file_source_content", "internal_article"

  - `content_ids.id` (string, required)
    Example: "12345678"

  - `availability` (object)
    Required when action is set_availability. Each field is optional — only the
properties present in the request are toggled.

  - `availability.ai_agent` (boolean)
    Toggle Fin AI Agent availability.
    Example: true

  - `availability.copilot` (boolean)
    Toggle Copilot availability.

  - `availability.sales_agent` (boolean)
    Toggle Sales Agent availability.

  - `audience` (object)
    Required when action is set_audience. Manages segment membership.

  - `audience.add_segment_ids` (array)
    Segment IDs to assign to the selected content.
    Example: ["56203d253cba154d39010062"]

  - `audience.remove_segment_ids` (array)
    Segment IDs to remove from the selected content.
    Example: ["56203d253cba154d39010063"]

  - `audience.remove_all` (boolean)
    When true, removes all segments from the selected content.

  - `tags` (object)
    Required when action is update_tags. Applies and/or removes existing tags.
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).

  - `tags.add_tag_ids` (array)
    Tag IDs to apply to the selected content.
    Example: ["100"]

  - `tags.remove_tag_ids` (array)
    Tag IDs to remove from the selected content.
    Example: ["200"]

## Response 202 fields (application/json):

  - `type` (string, required)
    Example: "content_bulk_action"

  - `status` (string, required)
    Example: "queued"

## Response 401 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: "error.list"

  - `request_id` (string,null)
    Example: "f93ecfa8-d08a-4325-8694-89aeb89c8f85"

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (string, required)
    A string indicating the kind of error, used to further qualify the HTTP response code
    Example: "unauthorized"

  - `errors.message` (string,null)
    Optional. Human readable description of the error.
    Example: "Access Token Invalid"

  - `errors.field` (string,null)
    Optional. Used to identify a particular field or query parameter that was in error.
    Example: "email"