Search knowledge base contents

REST API Reference

Request

Search the knowledge base contents — articles, snippets, external pages, uploaded files, and internal articles — using a keyword query.

Each result row has a type discriminator. Most types (content_snippet, external_content, file_source_content, internal_article) return a flat { type, id, title } shape. Help center articles return a nested shape with a contents[] array, one entry per locale.

Requires the read_content OAuth scope.

Security

bearerAuth

Query

querystring, <= 500 characters

A free-text search term matched against the title and body of each content item. When omitted, returns the most recent content items. Keep it to 500 characters or fewer. The API doesn't currently reject longer values.

Example:query=billing

pageinteger, >= 1

The page number to fetch. Defaults to 1. Values below 1 are clamped to 1. Values above 5001 return a 400 parameter_invalid error.

Default:1

Example:page=1

per_pageinteger, [ 1 .. 50 ]

Number of results per page. Defaults to 10. Maximum 50.

Default:10

Example:per_page=10

statesArray of strings

Filter by publication state. Accepts a comma-separated list or repeated params.

Items Enum:"published""draft"

Example:states=published,draft

localesArray of strings

Filter by locale codes (e.g. en, fr, de). Accepts a comma-separated list or repeated params.

Example:locales=en,fr

tag_idsArray of integers

Filter by tag IDs. Pairs with tag_operator to control match semantics. Accepts a comma-separated list or repeated params.

Example:tag_ids=1,2,3

tag_operatorstring

Match operator paired with tag_ids. IN returns content matching any of the given tags; NIN excludes content matching any of them.

Enum:"IN""NIN"

Example:tag_operator=IN

any_tag_idsArray of integers

Filter by tag IDs using OR semantics — returns content matching any of the given tags. Alternative to tag_ids + tag_operator. Accepts a comma-separated list or repeated params.

Example:any_tag_ids=1,2,3

folder_idsArray of integers

Filter by folder IDs. Must be sent together with folder_entity_type. Accepts a comma-separated list or repeated params.

Example:folder_ids=10,20

folder_entity_typestring

Required when folder_ids is provided. Identifies the entity type the folder IDs refer to.

Value:"folder"

Example:folder_entity_type=folder

content_typesArray of strings

Restrict the search to specific content types. When provided, this REPLACES the default content type set rather than filtering on top of it. Accepts a comma-separated list or repeated params.

Items Enum:"snippet""external_content""file_source_content""internal_article""article"

Example:content_types=article,snippet

copilot_statestring

Filter by whether the content is enabled for Copilot.

Enum:"on""off"

Example:copilot_state=on

fin_service_statestring

Filter by whether the content is enabled for Fin AI Agent (customer-facing service).

Enum:"on""off"

Example:fin_service_state=on

fin_sales_statestring

Filter by whether the content is enabled for Fin Sales Agent.

Enum:"on""off"

Example:fin_sales_state=on

created_by_idsArray of integers

Filter by the admin IDs that created the content. Accepts a comma-separated list or repeated params.

Example:created_by_ids=991267464,991267465

last_updated_by_idsArray of integers

Filter by the admin IDs that last updated the content. Accepts a comma-separated list or repeated params.

Example:last_updated_by_ids=991267464,991267465

created_at_afterinteger

Return content created at or after this time. Unix epoch seconds.

Example:created_at_after=1677253093

created_at_beforeinteger

Return content created at or before this time. Unix epoch seconds.

Example:created_at_before=1677861493

updated_at_afterinteger

Return content last updated at or after this time. Unix epoch seconds.

Example:updated_at_after=1677253093

updated_at_beforeinteger

Return content last updated at or before this time. Unix epoch seconds.

Example:updated_at_before=1677861493

Headers

Intercom-Versionstring(intercom_version)

Intercom API version.
If you omit the header, the API uses the version set in your app package, and 1.0 if none is set.

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

Example:2.17

curl -i -X GET \
  'https://api.intercom.io/content/search?query=billing&page=1&per_page=10&states=published%2Cdraft&locales=en%2Cfr&tag_ids=1%2C2%2C3&tag_operator=IN&any_tag_ids=1%2C2%2C3&folder_ids=10%2C20&folder_entity_type=folder&content_types=article%2Csnippet&copilot_state=on&fin_service_state=on&fin_sales_state=on&created_by_ids=991267464%2C991267465&last_updated_by_ids=991267464%2C991267465&created_at_after=1677253093&created_at_before=1677861493&updated_at_after=1677253093&updated_at_before=1677861493' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.17'

Responses

Search successful

Bodyapplication/json

typestring

Always list.

Value:"list"

Example:"list"

total_countinteger

Total number of results matching the query.

Example:5

pagesobject

Pagination metadata, including links to neighbouring pages.

dataArray of any(Content Search Result)

The list of matched content items. Each item's type field determines its shape.

Response

{
  "type": "list",
  "total_count": 5,
  "pages": {
    "type": "pages",
    "page": 1,
    "per_page": 10,
    "total_pages": 1
  },
  "data": [
    { … },
    { … },
    { … },
    { … },
    { … }
  ]
}