# Retrieve an API template source

You can retrieve an API template source, including its template and the status of its latest sync. The `auth_token` is never returned.
OAuth tokens must have the `read_write_ai_content` scope.

Endpoint: GET /ai/api_template_sources/{id}
Version: Preview
Security: bearerAuth

## Path parameters:

  - `id` (string, required)
    The unique identifier for the API template source, given by Intercom.

## Header parameters:

  - `Intercom-Version` (string)

## Response 200 fields (application/json):

  - `type` (string, required)
    Always `api_template_source`.
    Enum: "api_template_source"

  - `id` (string, required)
    The unique identifier for the source, given by Intercom.
    Example: 4182

  - `template` (object, required)
    The source's template, as saved. Top-level keys that aren't template fields are removed, and fields that were left out are returned without their defaults.
    Example: {"name":"Example Docs","base_url":"https://api.example.com/v1","auth":{"header":"Authorization","value":"Bearer {token}"},"tree":{"path":"/spaces/help-center/pages","query":{"status":"published"},"nod…

  - `template.name` (string, required)
    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

  - `template.base_url` (string, required)
    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, can't point to an Intercom domain, and can't include placeholders. Intercom only sends the token to this URL's host. A URL that can't be parsed fails `not_https`, and a host whose percent-encoding doesn't decode to valid UTF-8 text, such as `%ff`, fails `invalid`. Checks: `not_https`, `query_or_fragment`, `userinfo`, `intercom_host`, `invalid`, `undeclared_placeholder`.
    Example: https://api.example.com/v1

  - `template.auth` (object)
    How to send the source's `auth_token`. Intercom sends this header on every request. If it's left out, the header is `Authorization` with the value `Bearer {token}`, unless a `query` value in the tree request, a child call or the item is exactly `{token}`. Then no header is sent, and each of those requests must have a `query` value of `{token}`; one without it fails `missing_token` on its `query`, such as `template.item.query`. Intercom only sends the token over `https` to the `base_url` host. Checks: `invalid`.
    Example: {"header":"Authorization","value":"Bearer {token}"}

  - `template.auth.header` (string, required)
    The name of the header that carries the token, such as `Authorization` or `X-API-Key`. It can only use letters, digits and hyphens, must contain `auth`, `key`, `token` or `secret` in any case, and can't be a reserved header such as `Host`, `Cookie`, `Content-Length`, `Connection`, `X-Forwarded-For`, or a `Proxy-` or `Sec-` header. Checks: `invalid`, `not_credential`, `reserved`.
    Example: Authorization

  - `template.auth.value` (string, required)
    The header's value. It must be `{token}`, optionally preceded by one word of up to 24 letters and hyphens, starting with a letter, and a space, such as `Bearer {token}`. Intercom replaces `{token}` with the source's `auth_token`. Checks: `literal_text`.
    Example: Bearer {token}

  - `template.tree` (object, required)
    The request that lists the knowledge base's pages, and how to read its response. Checks: `invalid`, and `missing_keys` when `path` or `nodes` is missing.
    Example: {"path":"/spaces/help-center/pages","query":{"status":"published"},"nodes":["pages"],"children":"pages","folder_if":[{"type":"group"}],"folder_if_has_children":true,"content_if":[{"type":"document"}]}

  - `template.tree.path` (string, required)
    The request path, relative to `base_url`. It can't include placeholders. It can't be an absolute URL, contain `//`, or include `?` or `#`; send query parameters in `query` instead. The first path segment can't contain `:`, because it would read as a URL scheme (`not_relative`). Checks: `not_relative`, `query_or_fragment`, `invalid`, `undeclared_placeholder`.
    Example: /spaces/help-center/pages

  - `template.tree.nodes` (array, required)
    The path to the list of nodes in the response, as a list of keys and array indexes. For example, `["pages"]` reads the `pages` array from `{"pages": [...]}`. Use `[]` if the response body is the list itself.
    Example: ["pages"]

  - `template.tree.paging` (object)
    Optional. Requests the list page by page, sending each page's position in the query parameter named by `param`, which replaces any parameter of the same name in `query`. `style` sets what the position is and which page is the last. Intercom stops after a page that lists no nodes, or after the last page. With the `page_number` or `offset` style, a page that lists nodes but has no integer at `page_count` or `total` fails the sync. Each child call can have its own `paging`.
Without `paging`, the request is sent once, and a response that says it has more fails the sync without another try. A response says it has more if, at its top level or under `meta`, `total` or `total_count` is an integer larger than the number of entries at `nodes`, `total_pages` or `page_count` is an integer larger than 1, `has_more`, `hasMore`, `has_next_page` or `hasNextPage` is `true`, or `next_cursor`, `nextCursor`, `next_page_token` or `nextPageToken` has a value that isn't blank.
When you create the source, Intercom checks the token with one tree request sent without `param`. If `tree` has no `paging` and that response says it has more, the source isn't created and the request fails on `template.tree.paging`; see the create endpoint. Checks: `invalid` if it isn't an object with a `style` listed below, a `param` and the key its `style` needs.
    Example: {"style":"page_number","param":"page","page_count":["meta","total_pages"]}

  - `template.tree.paging.style` (string, required)
    How the list is paged. With `page_number`, `param` carries the page number, from 1, and the last page is the one whose number reaches the count at `page_count`. With `offset`, `param` carries the number of entries already listed, from 0, and the last page is the one that brings that number to the total at `total`. With `cursor`, the first request is sent without `param`, each later request sends the value at `next_cursor` in the response before it, and the last page is the one whose `next_cursor` is missing or blank.
    Enum: "page_number", "offset", "cursor"

  - `template.tree.paging.param` (string, required)
    The name of the query parameter that carries the page number, offset or cursor. It can only use letters, digits, `_`, `.`, `-`, `[` and `]`, such as `page`, `offset` or `page[number]`.
    Example: page

  - `template.tree.paging.page_count` (array)
    Required with the `page_number` style. The path to the total number of pages in each page's response, as a list of keys and array indexes. For example, `["meta", "total_pages"]`.
    Example: ["meta","total_pages"]

  - `template.tree.paging.total` (array)
    Required with the `offset` style. The path to the total number of entries in each page's response, as a list of keys and array indexes. For example, `["meta", "total"]`.
    Example: ["meta","total"]

  - `template.tree.paging.next_cursor` (array)
    Required with the `cursor` style. The path to the next page's cursor in each page's response, as a list of keys and array indexes. For example, `["meta", "next_cursor"]`.
    Example: ["meta","next_cursor"]

  - `template.tree.children` (string)
    The key on each node that holds its child nodes, for a nested tree. Omit it if the list is flat.
    Example: pages

  - `template.tree.child_calls` (array)
    Optional. Up to 11 more requests that list the tree one level at a time, for APIs that return a node's children from a separate request. Intercom sends the first child call once for each node the tree request lists, the second once for each node the first child call lists, and so on. Nodes nested under `children` don't get child calls. The nodes a child call returns become children of the node it was sent for, alongside any nodes under `tree.children`, and are matched against `tree.content_if` and `tree.folder_if` like other nodes. Child calls aren't sent when you create the source. An error inside a child call names it by its position from 0, such as `template.tree.child_calls.0.path`. Checks: `invalid` for a value that isn't a list or that has more than 11 child calls.
    Example: [{"path":"/collections/{collection_id}/articles","nodes":["articles"],"node_values":{"collection_id":["id"]},"paging":{"style":"page_number","param":"page","page_count":["meta","total_pages"]}}]

  - `template.tree.child_calls.path` (string, required)
    The request path, relative to `base_url`. It can include placeholders from the child call's `node_values`, and follows the same rules as `tree.path`, so its first path segment can't contain `:` (`not_relative`). Checks: `not_relative`, `query_or_fragment`, `invalid`, `undeclared_placeholder`.
    Example: /collections/{collection_id}/articles

  - `template.tree.child_calls.nodes` (array, required)
    The path to the list of nodes in the response, read the same way as `tree.nodes`.
    Example: ["articles"]

  - `template.tree.child_calls.paging` (object)
    Optional. Pages the child call's list, with the same fields and checks as `tree.paging`. Without it, a response that says it has more, as described under `tree.paging`, fails the sync without another try. Checks: `invalid`.
    Example: {"style":"page_number","param":"page","page_count":["meta","total_pages"]}

  - `template.tree.child_calls.paging.style` (string, required)
    How the list is paged, as in `tree.paging`.
    Enum: "page_number", "offset", "cursor"

  - `template.tree.child_calls.paging.param` (string, required)
    The name of the query parameter that carries the page number, offset or cursor.
    Example: page

  - `template.tree.child_calls.paging.page_count` (array)
    Required with the `page_number` style. The path to the total number of pages in each page's response.
    Example: ["meta","total_pages"]

  - `template.tree.child_calls.paging.total` (array)
    Required with the `offset` style. The path to the total number of entries in each page's response.
    Example: ["meta","total"]

  - `template.tree.child_calls.paging.next_cursor` (array)
    Required with the `cursor` style. The path to the next page's cursor in each page's response.
    Example: ["meta","next_cursor"]

  - `template.tree.content_if` (array)
    Optional. Conditions that pick the nodes to import as content. A node matches a condition when each key in the condition has the same value on the node, and it's imported when it matches any condition. If it's left out, every node is imported as content. If it's set, it needs at least one condition. Checks: `invalid`.
    Example: [{"type":"document"}]

  - `template.tree.folder_if` (array)
    Conditions that pick the nodes to create as folders, matched the same way as `content_if`. A node can be both a folder and content. A folder needs an `id` and a `title` read from the node; the children of a node that isn't a folder go into its parent's folder. Checks: `invalid`.
    Example: [{"type":"group"}]

  - `template.tree.folder_if_has_children` (boolean)
    When `true`, every node that has children is created as a folder.
    Example: true

  - `template.item` (object)
    Optional. The request that fetches one page, sent for each node that matches `tree.content_if`. Leave it out if the tree's nodes hold everything `mapping` reads: no item is then requested, and every `mapping` value must read from `node`. Checks: `invalid`, and `missing_keys` when `path` is missing.
    Example: {"path":"/spaces/help-center/pages/{page_id}","node_values":{"page_id":["id"]}}

  - `template.item.path` (string, required)
    The request path, relative to `base_url`. It can include placeholders from `node_values`, and follows the same rules as `tree.path`, so its first path segment can't contain `:` (`not_relative`). Checks: `not_relative`, `query_or_fragment`, `invalid`, `undeclared_placeholder`.
    Example: /spaces/help-center/pages/{page_id}

  - `template.mapping` (object, required)
    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. A value can only start with `item` if the template has an `item`. Checks: `invalid`, `missing_keys` when `id`, `title` or `body` is missing, and `invalid` or `missing_item` on a single field, such as `mapping.body`.
    Example: {"id":["node","id"],"title":["node","title"],"body":["item","body"],"updated_at":["item","updatedAt"]}

  - `template.mapping.id` (array, required)
    A unique ID for each node. Must read from `node`. A node whose id is blank isn't imported, though its child nodes are.
    Example: ["node","id"]

  - `template.mapping.title` (array, required)
    The page's title. Folders always take their title from the node, so read `title` from `node` if the template creates folders. Content without a title isn't imported.
    Example: ["node","title"]

  - `template.mapping.body` (array, required)
    The page's content, in the format set by `body_format`.
    Example: ["item","body"]

  - `template.mapping.updated_at` (array, required)
    When the page was last updated, as a date string such as an ISO 8601 timestamp. A value that can't be read as a date is ignored. Required when you create a source: a template without it, or with `null`, fails on `template.mapping.updated_at` with the message `mapping.updated_at is required`.
    Example: ["item","updatedAt"]

  - `template.mapping.item_id` (array)
    Optional. An ID for the page a node points to, for knowledge bases where one page can appear in more than one place. Nodes that share an `item_id` are imported once, into the folder of the first one. Must read from `node`.
    Example: ["node","page_id"]

  - `template.body_format` (string)
    Optional; defaults to `html`. 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"

  - `created_at` (integer, required)
    The time the source was created.
    Example: 1792713600

  - `latest_sync` (object, required)
    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}

  - `latest_sync.id` (string)
    The unique identifier for the sync.
    Example: 90817

  - `latest_sync.status` (string)
    `in_progress` while the sync runs. Once it ends, `success`, `failed`, `cancelled` or `skipped`.
    Enum: "in_progress", "success", "failed", "cancelled", "skipped"

  - `latest_sync.created_at` (integer)
    The time the sync started.
    Example: 1792713601

  - `latest_sync.updated_at` (integer)
    The time the sync was last updated.
    Example: 1792713601

## Response 401 fields (application/json):

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

  - `request_id` (string)
    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)
    Optional. Human readable description of the error.
    Example: Access Token Invalid

## Response 404 fields (application/json):

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

  - `request_id` (string)
    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)
    Optional. Human readable description of the error.
    Example: Access Token Invalid

