Create an API template source

REST API Reference

Request

You can create a source that imports content from a knowledge base's REST API. Send a template that describes the vendor's API, a value for each of the template's variables, and an auth_token for the knowledge base.

Intercom checks the request, then checks the token by sending the template's tree request. If both pass, Intercom saves the source, starts its first sync and returns the source. The auth_token is never returned. If the first sync can't start, the source is still created, with a latest_sync that is null or has the status failed; use Sync an API template source to start one. Intercom also syncs each source automatically, about once a day, unless the vendor has rejected the token.

If the request isn't valid, the response is a 422 with one or more errors. Each error has a field that names the request field, such as auth_token, variables.space_id or template.base_url. A missing value has the code parameter_not_found; any other failure has the code parameter_invalid. When the template fails a check, the message names the check, such as base_url fails the not_https check. The template fields below list their checks. A tree response over 25 MB fails on template.tree with the message <name>'s tree response is too large: over the 25 MB cap.

If the vendor answers the tree request with 401 or 403, the error is parameter_invalid on auth_token with the message <name> rejected the token. Any other failed answer, such as a 404 for tree.path, a redirect, a 429, a 5xx or a timeout, gives parameter_invalid on auth_token with the message <name> could not be reached to check the token. In both messages, <name> is the template's name.

OAuth tokens must have the read_write_ai_content scope.

Security

bearerAuth

Headers

Intercom-Versionstring(intercom_version_preview)

Preview Intercom API version. Used for closed beta endpoints or other features under managed availability.

Default:"Preview"

Value:"Preview"

Example:Preview

Bodyapplication/jsonrequired

templateobject(API Template)required

Describes a knowledge base's REST API so that Intercom can import its content. On each sync, Intercom:

Sends a GET request to base_url and tree.path, and reads the list of nodes at tree.nodes in the JSON response, following tree.children into nested nodes.
Creates a folder for each node that matches tree.folder_if, or that has children when tree.folder_if_has_children is true.
For each node that matches tree.content_if, sends a GET request to base_url and item.path, and imports the page using the fields set in mapping.

Imported content goes into a Knowledge Hub folder named after name.

Placeholders. In base_url, tree.path and tree.query values, {name} is replaced with the value of the variable name. In item.path and item.query values, {name} can also be a node_values name. A query value of exactly {token} is replaced with the source's auth_token. A value filled into base_url or a path can only use letters, digits, ., _ and -, and can't be only dots. A node value that's blank, or that's filled into a path and doesn't meet this rule, fails the sync.

Checks. When the template fails a check, creating the source returns a 422 parameter_invalid error whose field names the template field and whose message names the check. For example, the field is template.base_url and the message is base_url fails the not_https check. Each field below lists its checks. A tree response over 25 MB isn't a check: it fails on template.tree with the message <name>'s tree response is too large: over the 25 MB cap.

Limits.

Intercom sends one tree request per sync, so the tree response must list every node. Paging isn't supported.
The tree response can be at most 25 MB. When you create the source, a larger response fails on template.tree with the message <name>'s tree response is too large: over the 25 MB cap.
A tree can have at most 50,000 nodes, or the sync fails. Nodes nested more than 12 levels deep are skipped.
An item response over 10 MB is skipped, as is an item the vendor returns 404 for.
A redirect isn't followed, and fails the sync.
During a sync, when the vendor answers 429, Intercom waits for the time in its Retry-After header and then retries. If the vendor keeps answering 429, the sync fails.

Example:

{
  "name": "Example Docs",
  "base_url": "https://api.example.com/v1",
  "variables": [
    "space_id"
  ],
  "auth": {
    "header": "Authorization",
    "value": "Bearer {token}"
  },
  "tree": {
    "path": "/spaces/{space_id}/pages",
    "query": { … },
    "nodes": [ … ],
    "children": "pages",
    "folder_if": [ … ],
    "folder_if_has_children": true,
    "content_if": [ … ]
  },
  "item": {
    "path": "/spaces/{space_id}/pages/{page_id}",
    "node_values": { … }
  },
  "mapping": {
    "id": [ … ],
    "title": [ … ],
    "body": [ … ],
    "updated_at": [ … ]
  },
  "body_format": "html"
}

variablesobject

A value for each name in the template's variables, required when the template declares variables. Values can only use letters, digits, ., _ and -, and can't be only dots. Values for names the template doesn't declare are ignored.

Example:

{
  "space_id": "help-center"
}

auth_tokenstringrequired

The API token for the knowledge base, sent as set in template.auth. It can only use printable ASCII characters. Intercom checks it by sending the template's tree request before saving the source. It's never returned.

Example:"vendor-api-token"

curl -i -X POST \
  https://api.intercom.io/ai/api_template_sources \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: Preview' \
  -d '{
    "template": {
      "name": "Example Docs",
      "base_url": "https://api.example.com/v1",
      "variables": [
        "space_id"
      ],
      "auth": {
        "header": "Authorization",
        "value": "Bearer {token}"
      },
      "tree": {
        "path": "/spaces/{space_id}/pages",
        "query": {
          "status": "published"
        },
        "nodes": [
          "pages"
        ],
        "children": "pages",
        "folder_if": [
          {
            "type": "group"
          }
        ],
        "folder_if_has_children": true,
        "content_if": [
          {
            "type": "document"
          }
        ]
      },
      "item": {
        "path": "/spaces/{space_id}/pages/{page_id}",
        "node_values": {
          "page_id": [
            "id"
          ]
        }
      },
      "mapping": {
        "id": [
          "node",
          "id"
        ],
        "title": [
          "node",
          "title"
        ],
        "body": [
          "item",
          "body"
        ],
        "updated_at": [
          "item",
          "updatedAt"
        ]
      },
      "body_format": "html"
    },
    "variables": {
      "space_id": "help-center"
    },
    "auth_token": "vendor-api-token"
  }'

Responses

API template source created

Bodyapplication/json

typestringrequired

Always api_template_source.

Value:"api_template_source"

Example:"api_template_source"

idstringrequired

The unique identifier for the source, given by Intercom.

Example:"4182"

templateobject(API Template)required

The source's template, as saved. Top-level keys that aren't template fields are removed.

Example:

{
  "name": "Example Docs",
  "base_url": "https://api.example.com/v1",
  "variables": [
    "space_id"
  ],
  "auth": {
    "header": "Authorization",
    "value": "Bearer {token}"
  },
  "tree": {
    "path": "/spaces/{space_id}/pages",
    "query": { … },
    "nodes": [ … ],
    "children": "pages",
    "folder_if": [ … ],
    "folder_if_has_children": true,
    "content_if": [ … ]
  },
  "item": {
    "path": "/spaces/{space_id}/pages/{page_id}",
    "node_values": { … }
  },
  "mapping": {
    "id": [ … ],
    "title": [ … ],
    "body": [ … ],
    "updated_at": [ … ]
  },
  "body_format": "html"
}

variablesobjectrequired

The values of the template's variables, as strings. Values for names the template doesn't declare are removed.

Example:

{
  "space_id": "help-center"
}

created_atinteger, (date-time)required

The time the source was created.

Example:1792713600

latest_syncobject or nullrequired

The source's most recent sync, or null if no sync has started.

Example:

{
  "id": "90817",
  "status": "in_progress",
  "created_at": 1792713601,
  "updated_at": 1792713601
}

Response

{
  "type": "api_template_source",
  "id": "4182",
  "template": {
    "name": "Example Docs",
    "base_url": "https://api.example.com/v1",
    "variables": [ … ],
    "auth": { … },
    "tree": { … },
    "item": { … },
    "mapping": { … },
    "body_format": "html"
  },
  "variables": {
    "space_id": "help-center"
  },
  "created_at": 1792713600,
  "latest_sync": {
    "id": "90817",
    "status": "in_progress",
    "created_at": 1792713601,
    "updated_at": 1792713601
  }
}