Skip to content
Home/
REST API Reference
/
/
API Template

API Template

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

  1. 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.
  2. Creates a folder for each node that matches tree.folder_if, or that has children when tree.folder_if_has_children is true.
  3. 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.
namestringrequired

The knowledge base's name. Imported content goes into a Knowledge Hub folder with this name, and error messages use it. Checks: blank.

Example:"Example Docs"
base_urlstringrequired

The base URL of the vendor's API. It must use https, can't include a query string, a fragment or a user name and password, and can't point to an Intercom domain. It can include variable placeholders, such as https://{subdomain}.example.com/api. Intercom only sends the token to this URL's host. A URL that can't be parsed fails not_https; invalid applies only to malformed percent-encoding in a host that contains a placeholder. Checks: not_https, query_or_fragment, userinfo, intercom_host, invalid, undeclared_placeholder.

Example:"https://api.example.com/v1"
variablesArray of stringsrequired

The names of the values you send in variables when you create the source, for use as {name} placeholders. Names can only use letters, digits and underscores. Because responses return variables, a name can't look like a credential, such as token, secret, password, api_key or access_token. Use [] if the template has no variables. Checks: invalid, credential_name.

Example:
[
  "space_id"
]
authobjectrequired

How to send the source's auth_token. Intercom sends this header on every request, and only over https to the base_url host. Checks: invalid.

Example:
{
  "header": "Authorization",
  "value": "Bearer {token}"
}
treeobjectrequired

The request that lists the knowledge base's pages, and how to read its response. Checks: invalid, missing_keys, and undeclared_placeholder for a placeholder in path or a query value that isn't in variables.

Example:
{
  "path": "/spaces/{space_id}/pages",
  "query": {
    "status": "published"
  },
  "nodes": [
    "pages"
  ],
  "children": "pages",
  "folder_if": [
    { … }
  ],
  "folder_if_has_children": true,
  "content_if": [
    { … }
  ]
}
itemobjectrequired

The request that fetches one page, sent for each node that matches tree.content_if. Checks: invalid, missing_keys, and undeclared_placeholder for a placeholder in path or a query value that isn't in variables or node_values.

Example:
{
  "path": "/spaces/{space_id}/pages/{page_id}",
  "node_values": {
    "page_id": [ … ]
  }
}
mappingobjectrequired

Where to read each page's fields. Each value is a list that starts with node, to read from the tree node, or item, to read from the item response, followed by at least one key or array index. For example, ["item", "body"] reads body from the item response. Checks: invalid, missing_keys, and invalid on a single field, such as mapping.title.

Example:
{
  "id": [
    "node",
    "id"
  ],
  "title": [
    "node",
    "title"
  ],
  "body": [
    "item",
    "body"
  ],
  "updated_at": [
    "item",
    "updatedAt"
  ]
}
body_formatstringrequired

The format of the page content that mapping.body reads. Markdown is converted to HTML, without a leading YAML front matter block. Unsafe HTML is removed. Checks: unknown.

Enum:"html""markdown""plain_text"
Example:"html"
{
  "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"
}