From 6b54b327627f17ce3a31ad1da26a254f1f41cd0f Mon Sep 17 00:00:00 2001 From: kilian-tennyson Date: Fri, 23 Oct 2026 10:27:01 +0100 Subject: [PATCH 1/3] Document the API template source endpoints in Preview Add the API template source endpoints to the Preview spec: - POST /ai/api_template_sources creates a source from an API template, variable values and a vendor token, and starts its first sync (201). - GET /ai/api_template_sources/{id} returns the source with its template, variables and latest sync status. - POST /ai/api_template_sources/{id}/sync starts a sync (202). New schemas: api_template (the template format, with each field's checks and the sync limits), api_template_source and create_api_template_source_request. Error responses cover the 401 scope errors, the 403 for workspaces that can't fetch external URLs, 404, the 409 sync conflicts, the 422 source_unauthorized on sync, and the 422 validation errors on create, whose examples show the field that failed. --- descriptions/0/api.intercom.io.yaml | 879 ++++++++++++++++++++++++++++ 1 file changed, 879 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 987e5099..2e6f0e34 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -784,6 +784,528 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + "/ai/api_template_sources": + post: + summary: Create an API template source + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - AI Content + operationId: createApiTemplateSource + description: | + You can create an API template source to import a knowledge base through its vendor's REST API. Send a template that describes the vendor's API, values for the template's variables, and a token for the vendor's API. + + Intercom checks the template and the variables, then checks the token by requesting the template's tree from the vendor. If any check fails, the source isn't created and the API returns a `422` error that names each failing field. Otherwise, the source is created and its first sync starts. The imported content is filed in a folder named after the template. + + If the first sync can't start, the source is still created. Its `latest_sync` is then `null` or has the status `failed`, and you can start a sync with `POST /ai/api_template_sources/{id}/sync`. + + The token is stored with the source and is never returned. + + OAuth tokens must have the `read_write_ai_content` scope. + responses: + '201': + description: successful + content: + application/json: + examples: + successful: + value: + type: api_template_source + id: '494' + 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: {} + 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}" + query: {} + 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 + created_at: 1734537259 + latest_sync: + id: '1287' + status: in_progress + created_at: 1734537259 + updated_at: 1734537259 + schema: + "$ref": "#/components/schemas/api_template_source" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 187fc629-1bf4-419a-8995-ad0f81010c58 + errors: + - code: unauthorized + message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: a3e5b8e2-1234-5678-9abc-def012345678 + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '403': + description: The workspace isn't allowed to fetch external URLs. + content: + application/json: + examples: + Forbidden: + value: + type: error.list + request_id: 1aa556d8-7b3b-4386-b8de-bf562107c874 + errors: + - code: action_forbidden + message: "This workspace can't fetch external URLs yet. Contact + support to enable it." + schema: + "$ref": "#/components/schemas/error" + '422': + description: | + The template, the variables or the token failed a check, and the source wasn't created. The response can list several errors. + + Each error's `field` names the request field that failed, such as `template.base_url`, `variables.space_id` or `auth_token`. A missing value has the code `parameter_not_found`, and any other failure has the code `parameter_invalid`. + + When a template check fails, the message names the check: ` fails the check`. The checks are listed in the API Template schema. A tree response over 25 MB fails on `template.tree`. + content: + application/json: + examples: + Invalid base URL: + value: + type: error.list + request_id: c78bca98-61fb-4dea-853f-d179a2ed7fda + errors: + - code: parameter_invalid + field: template.base_url + message: base_url fails the not_https check + Literal credential in a query: + value: + type: error.list + request_id: e1e5735e-9fb5-445c-b607-6dec2df9aedf + errors: + - code: parameter_invalid + field: template.tree.query + message: tree.query fails the literal_credential check + Missing template: + value: + type: error.list + request_id: db830aaf-f8c5-4298-9288-6533c3f02713 + errors: + - code: parameter_not_found + field: template + message: An API template object is required + Missing variable: + value: + type: error.list + request_id: 8ae61f5d-5d4a-4469-8a63-5f945047d176 + errors: + - code: parameter_not_found + field: variables.space_id + message: space_id is required + Missing token: + value: + type: error.list + request_id: 52c3ca26-c94f-4ebb-9e69-b3422a16434d + errors: + - code: parameter_not_found + field: auth_token + message: A token is required + Token rejected: + value: + type: error.list + request_id: 8a27c782-f6d6-42bf-b6c5-2b630120dc8b + errors: + - code: parameter_invalid + field: auth_token + message: Example Docs rejected the token + Vendor unreachable: + value: + type: error.list + request_id: 2276a961-ad8f-4cf0-81ac-9ff892ed64ea + errors: + - code: parameter_invalid + field: auth_token + message: Example Docs could not be reached to check the token + schema: + "$ref": "#/components/schemas/error" + requestBody: + content: + application/json: + schema: + "$ref": "#/components/schemas/create_api_template_source_request" + examples: + successful: + summary: successful + value: + 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: {} + 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}" + query: {} + 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 + "/ai/api_template_sources/{id}": + parameters: + - name: id + in: path + description: The unique identifier for the API template source, which is given + by Intercom. + required: true + schema: + type: string + get: + summary: Retrieve an API template source + operationId: getApiTemplateSource + description: | + You can retrieve an API template source, with its template, its variables and the status of its latest sync. The source's token is never returned. + + OAuth tokens must have the `read_write_ai_content` scope. + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - AI Content + responses: + '200': + description: successful + content: + application/json: + examples: + successful: + value: + type: api_template_source + id: '494' + 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: {} + 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}" + query: {} + 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 + created_at: 1734537259 + latest_sync: + id: '1287' + status: success + created_at: 1734537259 + updated_at: 1734537265 + schema: + "$ref": "#/components/schemas/api_template_source" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 963aaf87-3f2b-4fae-9f83-69eac49ce2c1 + errors: + - code: unauthorized + message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: a3e5b8e2-1234-5678-9abc-def012345678 + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '404': + description: API template source not found + content: + application/json: + examples: + API template source not found: + value: + type: error.list + request_id: bdba03ae-ed4d-43d8-a0df-8b6947c467bc + errors: + - code: not_found + message: Resource Not Found + schema: + "$ref": "#/components/schemas/error" + "/ai/api_template_sources/{id}/sync": + parameters: + - name: id + in: path + description: The unique identifier for the API template source, which is given + by Intercom. + required: true + schema: + type: string + post: + summary: Sync an API template source + operationId: syncApiTemplateSource + description: | + You can start a sync of an API template source, which imports its content from the vendor again. The sync runs in the background: the response is the source, with the new sync as its `latest_sync`. Retrieve the source to follow the sync's status. + + A source runs one sync at a time. + + OAuth tokens must have the `read_write_ai_content` scope. + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - AI Content + responses: + '202': + description: Accepted + content: + application/json: + examples: + successful: + value: + type: api_template_source + id: '494' + 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: {} + 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}" + query: {} + 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 + created_at: 1734537259 + latest_sync: + id: '1311' + status: in_progress + created_at: 1734623659 + updated_at: 1734623659 + schema: + "$ref": "#/components/schemas/api_template_source" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 3909bb15-20b6-4593-b849-b572f44a317d + errors: + - code: unauthorized + message: Access Token Invalid + Token lacks required scope: + value: + type: error.list + request_id: a3e5b8e2-1234-5678-9abc-def012345678 + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '403': + description: The workspace isn't allowed to fetch external URLs. + content: + application/json: + examples: + Forbidden: + value: + type: error.list + request_id: 7ff7b139-7b45-4121-b59f-93956207ee8d + errors: + - code: action_forbidden + message: "This workspace can't fetch external URLs yet. Contact + support to enable it." + schema: + "$ref": "#/components/schemas/error" + '404': + description: API template source not found + content: + application/json: + examples: + API template source not found: + value: + type: error.list + request_id: d2860453-7f71-4c2b-9c15-ce0f59872f73 + errors: + - code: not_found + message: Resource Not Found + schema: + "$ref": "#/components/schemas/error" + '409': + description: A sync is already running for the source, or the source is + being deleted. + content: + application/json: + examples: + Sync already running: + value: + type: error.list + request_id: 39d83fa9-2362-4bdf-8264-83bd175ef3ef + errors: + - code: conflict + message: A sync is already running for this source + Source being deleted: + value: + type: error.list + request_id: d7d75f78-fb59-43db-841c-1c88b4f08709 + errors: + - code: conflict + message: This source is being deleted + schema: + "$ref": "#/components/schemas/error" + '422': + description: The vendor no longer accepts the source's token. + content: + application/json: + examples: + Token no longer accepted: + value: + type: error.list + request_id: 9b1f4c2e-6a83-4d57-b0e9-2c7a5f8d1e36 + errors: + - code: source_unauthorized + message: The vendor no longer accepts this source's token + schema: + "$ref": "#/components/schemas/error" "/ai/content_import_sources": get: summary: List content import sources @@ -33840,6 +34362,335 @@ components: example: email: user@example.com company.name: Acme Inc + api_template: + title: API Template + type: object + x-tags: + - AI Content + description: | + An API template describes how to read a knowledge base through its vendor's REST API. Intercom requests the `tree`, a list of the knowledge base's nodes, such as folders and pages. For each node that is content, it then requests the `item`, such as the page's body. `mapping` says which fields of the node and the item become the imported content. + + A placeholder such as `{space_id}` in `base_url`, a path or a query value is filled from `variables`. In the item request, it can also be filled from `item.node_values`. Values filled into `base_url` or a path are URL-encoded. `{token}` stands for the source's token. It can only be used in `auth.value` or as an entire query value. + + When a template check fails, creating the source returns a `422` error. Its `field` is `template.` followed by the failing field, and its message is ` fails the check`. Each field below names its checks in brackets. Top-level keys other than the ones below are ignored and not stored. + + A sync fails if the tree response is over 25 MB or has more than 50,000 nodes. Nodes nested more than 12 levels deep aren't imported. An item whose response is over 10 MB, or that the vendor returns as not found, is skipped. Redirects aren't followed. + properties: + name: + type: string + description: The name of the knowledge base. The imported content is filed + in a folder with this name. It can't be blank (`blank`). + example: Example Docs + base_url: + type: string + description: The base URL of the vendor's API. It must be an `https` URL + with a host (`not_https`), with no query or fragment (`query_or_fragment`) + and no user name or password (`userinfo`). It can't be on an Intercom + domain (`intercom_host`), and must be a valid URL (`invalid`). It can + use placeholders from `variables` (`undeclared_placeholder`). + example: https://api.example.com/v1 + variables: + type: array + description: The names of the template's variables. Each name may only use + letters, digits and underscores (`invalid`), and can't look like a credential, + such as `api_key`, `token` or `secret` (`credential_name`). Use an empty + list if the template has no variables. + items: + type: string + example: + - space_id + auth: + type: object + description: How the token is sent to the vendor. It must be an object (`invalid`). + properties: + header: + type: string + description: The name of the request header that carries the token, such + as `Authorization` or `X-API-Key`. It may only use letters, digits + and hyphens (`invalid`), and must contain `auth`, `key`, `token` or + `secret` (`not_credential`). It can't be a header that controls the + connection, routing or cookies, such as `Host`, `Cookie`, `Forwarded` + or a `Proxy-` header (`reserved`). + example: Authorization + value: + type: string + description: The header's value. It must be `{token}`, optionally after + a scheme word and a space, such as `Bearer {token}` (`literal_text`). + A scheme word starts with a letter and has at most 24 letters and + hyphens. + example: 'Bearer {token}' + required: + - header + - value + tree: + type: object + description: The request that lists the knowledge base's nodes. It must be + an object (`invalid`) with `path`, `nodes` and `content_if` (`missing_keys`). + Its path and query values can only use placeholders from `variables` + (`undeclared_placeholder`). + properties: + path: + type: string + description: The request path, relative to `base_url`. It can't be an + absolute URL or contain `//` (`not_relative`), can't contain `?` or + `#` (`query_or_fragment`), and must be a valid URL path (`invalid`). + Use `query` for query parameters. + example: "/spaces/{space_id}/pages" + query: + type: object + description: The query parameters to send. Values must be strings (`invalid`). + A value of exactly `{token}` is replaced with the source's token. A + parameter whose name looks like a credential, such as `api_key` or + `access_token`, must have the value `{token}` (`literal_credential`). + additionalProperties: + type: string + example: + per_page: '100' + nodes: + type: array + description: The keys to follow in the tree response to reach the list + of nodes. Use an empty list if the response is the list. + items: + oneOf: + - type: string + - type: integer + example: + - pages + children: + type: string + description: The key on a node that holds its child nodes, for a tree + whose nodes are nested. + example: pages + content_if: + type: array + description: The conditions for a node to be imported as content. A condition + is an object of keys and values, and a node matches it when the node + has each of those values at those keys. A node is imported when it + matches any condition. It must be a non-empty list of objects (`invalid`). + items: + type: object + additionalProperties: true + example: + - type: document + folder_if: + type: array + description: The conditions, in the same form as `content_if`, for a node + to become a folder. A folder's child nodes are filed in it. A folder + is named with `mapping.title` read from the node, and a node without + a title doesn't become a folder. It must be a list of objects (`invalid`). + items: + type: object + additionalProperties: true + example: + - type: group + folder_if_has_children: + type: boolean + description: Whether a node that has child nodes becomes a folder. + example: true + required: + - path + - nodes + - content_if + item: + type: object + description: The request that fetches a content node's item, made once for + each node that matches `tree.content_if`. It must be an object (`invalid`) + with a `path` (`missing_keys`). Its path and query values can use placeholders + from `variables` and `node_values` (`undeclared_placeholder`). + properties: + path: + type: string + description: The request path, relative to `base_url`. It has the same + checks as `tree.path`. + example: "/spaces/{space_id}/pages/{page_id}" + query: + type: object + description: The query parameters to send. It has the same checks as + `tree.query`. + additionalProperties: + type: string + example: {} + node_values: + type: object + description: Placeholders filled from the node, each with the keys to + follow in the node to reach its value. It must be an object (`invalid`), + and its names can't look like credentials (`credential_name`). A value + filled into the path may only use letters, digits, `.`, `_` and `-`, + or the sync fails. + additionalProperties: + type: array + items: + oneOf: + - type: string + - type: integer + example: + page_id: + - id + required: + - path + mapping: + type: object + description: Where each field of the imported content comes from. Each value + is a list that starts with `node` or `item`, followed by the keys to follow + in it. An integer key indexes into a list. It must be an object (`invalid`) + with `id`, `title`, `body` and `updated_at` (`missing_keys`), and each + value must have this form (`invalid`). + properties: + id: + type: array + description: The node's unique identifier. It must start with `node`. + items: + oneOf: + - type: string + - type: integer + example: + - node + - id + title: + type: array + description: The title. Folders always read it from the node. + items: + oneOf: + - type: string + - type: integer + example: + - node + - title + body: + type: array + description: The body, in `body_format`. + items: + oneOf: + - type: string + - type: integer + example: + - item + - body + updated_at: + type: array + description: When the content was last updated, as a date and time such + as `2024-12-18T15:47:39Z`. A value that can't be read as a date is + ignored. + items: + oneOf: + - type: string + - type: integer + example: + - item + - updatedAt + item_id: + type: array + description: An identifier shared by nodes that are the same item, such + as a page listed in two folders. The item is fetched and imported once, + in the first node's folder. It must start with `node`. + items: + oneOf: + - type: string + - type: integer + example: + - node + - page_id + required: + - id + - title + - body + - updated_at + body_format: + type: string + description: The format of the body (`unknown`). HTML is sanitized, Markdown + is converted to HTML without any front matter, and plain text keeps its + line breaks. + enum: + - html + - markdown + - plain_text + example: html + required: + - name + - base_url + - variables + - auth + - tree + - item + - mapping + - body_format + api_template_source: + title: API Template Source + type: object + x-tags: + - AI Content + description: A content source that imports a knowledge base through its vendor's + REST API, as its API template describes. The template is returned as it + was stored. The source's token is never returned. + nullable: false + properties: + type: + type: string + readOnly: true + description: Always `api_template_source`. + enum: + - api_template_source + example: api_template_source + id: + type: string + readOnly: true + description: The unique identifier for the API template source, which is + given by Intercom. + example: '494' + template: + "$ref": "#/components/schemas/api_template" + variables: + type: object + description: The values for the template's variables. Only the variables + the template declares are kept, as strings. + additionalProperties: + type: string + example: + space_id: help-center + created_at: + type: integer + format: date-time + readOnly: true + description: The time when the API template source was created. + example: 1734537259 + latest_sync: + type: object + nullable: true + readOnly: true + description: The source's most recent sync, or `null` if no sync has started. + properties: + id: + type: string + description: The unique identifier for the sync. + example: '1287' + status: + type: string + description: The status of the sync. It's `in_progress` while the sync + runs, then `success`, `failed`, `cancelled` or `skipped`. + enum: + - in_progress + - success + - failed + - cancelled + - skipped + example: success + created_at: + type: integer + format: date-time + description: The time when the sync started. + example: 1734537259 + updated_at: + type: integer + format: date-time + description: The time when the sync was last updated. + example: 1734537265 + required: + - type + - id + - template + - variables + - created_at + - latest_sync app: title: App type: object @@ -40027,6 +40878,34 @@ components: - type - user - visitor + create_api_template_source_request: + title: Create API Template Source Payload + type: object + description: You can create an API template source to import a knowledge base + through its vendor's REST API. + nullable: false + properties: + template: + "$ref": "#/components/schemas/api_template" + variables: + type: object + description: A value for each variable the template declares. A value may + only use letters, digits, `.`, `_` and `-`, and can't be only dots. Keys + the template doesn't declare are ignored. + additionalProperties: + type: string + example: + space_id: help-center + auth_token: + type: string + description: The token for the vendor's API, sent as `auth.value` describes. + It may only use printable ASCII characters. Intercom checks it with the + vendor before creating the source. It's stored with the source and is + never returned. + example: vendor-api-token + required: + - template + - auth_token create_audience_request: title: Create Audience Request type: object From 1a4eab5820739d35759b2d78abf4ea8a39ef46c9 Mon Sep 17 00:00:00 2001 From: kilian-tennyson Date: Fri, 23 Oct 2026 11:07:08 +0100 Subject: [PATCH 2/3] Clarify sync conflicts, automatic syncs and node value rules Relabel the second sync 409 example: a sync on a source that's already being deleted gets the 'already running' conflict, and 'This source is being deleted' only comes back when a delete starts during the request. Say that Intercom syncs each source automatically about once a day, on the sync endpoint and on latest_sync. Say that a blank node value fails the sync too, not only one with characters outside letters, digits, '.', '_' and '-'. --- descriptions/0/api.intercom.io.yaml | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 2e6f0e34..e19f77f2 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -1151,7 +1151,7 @@ paths: description: | You can start a sync of an API template source, which imports its content from the vendor again. The sync runs in the background: the response is the source, with the new sync as its `latest_sync`. Retrieve the source to follow the sync's status. - A source runs one sync at a time. + A source runs one sync at a time. Intercom also syncs each source automatically, about once a day, so you only need this endpoint to sync sooner. OAuth tokens must have the `read_write_ai_content` scope. parameters: @@ -1283,7 +1283,7 @@ paths: errors: - code: conflict message: A sync is already running for this source - Source being deleted: + Deletion started during the request: value: type: error.list request_id: d7d75f78-fb59-43db-841c-1c88b4f08709 @@ -34515,8 +34515,8 @@ components: description: Placeholders filled from the node, each with the keys to follow in the node to reach its value. It must be an object (`invalid`), and its names can't look like credentials (`credential_name`). A value - filled into the path may only use letters, digits, `.`, `_` and `-`, - or the sync fails. + that is blank, or that uses anything other than letters, digits, `.`, + `_` and `-`, fails the sync. additionalProperties: type: array items: @@ -34658,6 +34658,8 @@ components: nullable: true readOnly: true description: The source's most recent sync, or `null` if no sync has started. + Intercom also syncs each source automatically, about once a day, so this + can be a sync you didn't start. properties: id: type: string From 60e0f303ae08c3a1e43d00bbdd39b53bb3a47526 Mon Sep 17 00:00:00 2001 From: kilian-tennyson Date: Fri, 23 Oct 2026 12:35:32 +0100 Subject: [PATCH 3/3] Correct API template source checks, sync limits and errors - Use the Preview Intercom-Version header for the three endpoints. - base_url: an unparseable URL fails not_https; drop the invalid check. - tree.path: a colon in the first segment fails not_relative. - item.node_values: only values filled into the path must be URL-safe. - Document one tree request per sync, no paging, 429 retries, and that a redirect fails the sync. - mapping: content without an id or title isn't imported. - Sync 422: the token can't be replaced and automatic syncs stop. - Create 422: document the tree size and token check messages, and add examples for a large tree, an invalid variable and several errors. --- descriptions/0/api.intercom.io.yaml | 80 +++++++++++++++++++++-------- 1 file changed, 58 insertions(+), 22 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index e19f77f2..ba70acdd 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -791,7 +791,7 @@ paths: - name: Intercom-Version in: header schema: - "$ref": "#/components/schemas/intercom_version" + "$ref": "#/components/schemas/intercom_version_preview" tags: - AI Content operationId: createApiTemplateSource @@ -906,7 +906,9 @@ paths: Each error's `field` names the request field that failed, such as `template.base_url`, `variables.space_id` or `auth_token`. A missing value has the code `parameter_not_found`, and any other failure has the code `parameter_invalid`. - When a template check fails, the message names the check: ` fails the check`. The checks are listed in the API Template schema. A tree response over 25 MB fails on `template.tree`. + When a template check fails, the message names the check: ` fails the check`. The checks are listed in the API Template schema. A tree response over 25 MB fails on `template.tree` with the message `'s tree response is too large: over the 25 MB cap`, where `` is the template's name. + + If the vendor answers the token check with `401` or `403`, the error is on `auth_token` with the message ` rejected the token`. If it answers with anything other than success, `401` or `403`, such as a `404` on `tree.path`, a redirect, a `429`, a `5xx` or a timeout, the error is on `auth_token` with the message ` could not be reached to check the token`. The check isn't retried. content: application/json: examples: @@ -942,6 +944,15 @@ paths: - code: parameter_not_found field: variables.space_id message: space_id is required + Invalid variable value: + value: + type: error.list + request_id: 8e6ae348-d9da-41a7-bf01-693dd7accede + errors: + - code: parameter_invalid + field: variables.space_id + message: "space_id may only use letters, digits, '.', '_' and + '-', and can't be only dots" Missing token: value: type: error.list @@ -966,6 +977,26 @@ paths: - code: parameter_invalid field: auth_token message: Example Docs could not be reached to check the token + Tree response too large: + value: + type: error.list + request_id: d5ab4057-55a5-4904-8afe-0d015f5fd288 + errors: + - code: parameter_invalid + field: template.tree + message: "Example Docs's tree response is too large: over the + 25 MB cap" + Several errors: + value: + type: error.list + request_id: 2e5f0311-38de-42fc-8625-b664038601b7 + errors: + - code: parameter_not_found + field: auth_token + message: A token is required + - code: parameter_invalid + field: template.auth.header + message: auth.header fails the not_credential check schema: "$ref": "#/components/schemas/error" requestBody: @@ -1039,7 +1070,7 @@ paths: - name: Intercom-Version in: header schema: - "$ref": "#/components/schemas/intercom_version" + "$ref": "#/components/schemas/intercom_version_preview" tags: - AI Content responses: @@ -1151,14 +1182,14 @@ paths: description: | You can start a sync of an API template source, which imports its content from the vendor again. The sync runs in the background: the response is the source, with the new sync as its `latest_sync`. Retrieve the source to follow the sync's status. - A source runs one sync at a time. Intercom also syncs each source automatically, about once a day, so you only need this endpoint to sync sooner. + A source runs one sync at a time. Intercom also syncs each source automatically, about once a day, unless the vendor has rejected the token, so you only need this endpoint to sync sooner. OAuth tokens must have the `read_write_ai_content` scope. parameters: - name: Intercom-Version in: header schema: - "$ref": "#/components/schemas/intercom_version" + "$ref": "#/components/schemas/intercom_version_preview" tags: - AI Content responses: @@ -1293,7 +1324,9 @@ paths: schema: "$ref": "#/components/schemas/error" '422': - description: The vendor no longer accepts the source's token. + description: The vendor no longer accepts the source's token. The source's + token can't be replaced, and Intercom stops syncing the source automatically. + To import with a new token, create a new source. content: application/json: examples: @@ -34372,9 +34405,9 @@ components: A placeholder such as `{space_id}` in `base_url`, a path or a query value is filled from `variables`. In the item request, it can also be filled from `item.node_values`. Values filled into `base_url` or a path are URL-encoded. `{token}` stands for the source's token. It can only be used in `auth.value` or as an entire query value. - When a template check fails, creating the source returns a `422` error. Its `field` is `template.` followed by the failing field, and its message is ` fails the check`. Each field below names its checks in brackets. Top-level keys other than the ones below are ignored and not stored. + When a template check fails, creating the source returns a `422` error whose message is ` fails the check`, where `` is the failing field below; see the create endpoint for the error shape. Each field below names its checks in brackets. Top-level keys other than the ones below are ignored and not stored. - A sync fails if the tree response is over 25 MB or has more than 50,000 nodes. Nodes nested more than 12 levels deep aren't imported. An item whose response is over 10 MB, or that the vendor returns as not found, is skipped. Redirects aren't followed. + Intercom sends one tree request per sync. Paging isn't supported. A sync fails if the tree response is over 25 MB or has more than 50,000 nodes. Nodes nested more than 12 levels deep aren't imported. An item whose response is over 10 MB, or that the vendor returns as not found, is skipped. A redirect isn't followed and fails the sync. During a sync, if the vendor answers `429`, Intercom waits for the time in its `Retry-After` header, or 60 seconds if there's none, and then retries. If the vendor keeps answering `429`, the sync fails. properties: name: type: string @@ -34384,10 +34417,11 @@ components: base_url: type: string description: The base URL of the vendor's API. It must be an `https` URL - with a host (`not_https`), with no query or fragment (`query_or_fragment`) - and no user name or password (`userinfo`). It can't be on an Intercom - domain (`intercom_host`), and must be a valid URL (`invalid`). It can - use placeholders from `variables` (`undeclared_placeholder`). + with a host (`not_https`); a URL that can't be parsed, including one + with malformed percent-encoding, also fails `not_https`. It must have + no query or fragment (`query_or_fragment`) and no user name or password + (`userinfo`), and can't be on an Intercom domain (`intercom_host`). It + can use placeholders from `variables` (`undeclared_placeholder`). example: https://api.example.com/v1 variables: type: array @@ -34432,9 +34466,9 @@ components: path: type: string description: The request path, relative to `base_url`. It can't be an - absolute URL or contain `//` (`not_relative`), can't contain `?` or - `#` (`query_or_fragment`), and must be a valid URL path (`invalid`). - Use `query` for query parameters. + absolute URL, contain `//` or have a `:` in its first segment (`not_relative`), + can't contain `?` or `#` (`query_or_fragment`), and must be a valid + URL path (`invalid`). Use `query` for query parameters. example: "/spaces/{space_id}/pages" query: type: object @@ -34445,7 +34479,7 @@ components: additionalProperties: type: string example: - per_page: '100' + status: published nodes: type: array description: The keys to follow in the tree response to reach the list @@ -34514,9 +34548,9 @@ components: type: object description: Placeholders filled from the node, each with the keys to follow in the node to reach its value. It must be an object (`invalid`), - and its names can't look like credentials (`credential_name`). A value - that is blank, or that uses anything other than letters, digits, `.`, - `_` and `-`, fails the sync. + and its names can't look like credentials (`credential_name`). A blank + value fails the sync. A value filled into the path must use only letters, + digits, `.`, `_` and `-`, and can't be only dots, or the sync fails. additionalProperties: type: array items: @@ -34539,6 +34573,7 @@ components: id: type: array description: The node's unique identifier. It must start with `node`. + A node whose id is blank isn't imported, though its child nodes are. items: oneOf: - type: string @@ -34548,7 +34583,8 @@ components: - id title: type: array - description: The title. Folders always read it from the node. + description: The title. Folders always read it from the node. Content + without a title isn't imported. items: oneOf: - type: string @@ -34658,8 +34694,8 @@ components: nullable: true readOnly: true description: The source's most recent sync, or `null` if no sync has started. - Intercom also syncs each source automatically, about once a day, so this - can be a sync you didn't start. + Intercom also syncs each source automatically, about once a day, unless + the vendor has rejected the token, so this can be a sync you didn't start. properties: id: type: string