Run a bulk action on Knowledge Hub content

REST API Reference

Request

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, enqueues background work, and returns 202 with a placeholder envelope. Items whose type is not in the action's allowlist are silently dropped before processing. Articles imported from synced sources (Confluence, Notion, Zendesk, Salesforce Knowledge, etc.) are silently skipped on delete — they can only be removed by disconnecting the underlying import source.

Requires the write_content OAuth scope.

Security

bearerAuth

Headers

Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default:"2.16"

Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"

Example:2.16

Bodyapplication/jsonrequired

actionstringrequired

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"

Example:"publish"

content_idsArray of objects, <= 1000 itemsrequired

Up to 1,000 content items to apply the action to.

availabilityobject

Required when action is set_availability. Each field is optional — only the properties present in the request are toggled.

audienceobject

Required when action is set_audience. Manages segment membership.

tagsobject

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).

require 'json'
require 'uri'
require 'net/http'
require 'openssl'

url = URI('https://api.intercom.io/content/bulk_actions')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request['Content-Type'] = 'application/json'
request['Intercom-Version'] = '2.16'
request['Authorization'] = 'Bearer <YOUR_TOKEN_HERE>'
request.body = {
  action: 'publish',
  content_ids: [
    {
      type: 'article_content',
      id: '12345678'
    },
    {
      type: 'article_content',
      id: '12345679'
    }
  ]
}.to_json

response = http.request(request)
puts response.read_body

Responses

Accepted — work has been enqueued

Bodyapplication/json

typestring

Example:"content_bulk_action"

statusstring

Example:"queued"

Response

{
  "type": "content_bulk_action",
  "status": "queued"
}