From 54869dc4851503dc45966b5e3987d1d6ab64cdd6 Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Wed, 21 Oct 2026 12:51:27 +0100 Subject: [PATCH 1/8] Document AI Content scope, errors, pagination and external page fields Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 451 +++++++++++++++++++-- descriptions/2.17/api.intercom.io.yaml | 516 +++++++++++++++++++++++-- 2 files changed, 893 insertions(+), 74 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index dcbc3ebd..b2ac4e88 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -792,10 +792,30 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" + - name: page + in: query + schema: + type: integer + minimum: 1 + default: 1 + description: The page of results to fetch. Defaults to the first page. + example: 1 + - name: per_page + in: query + schema: + type: integer + minimum: 1 + maximum: 150 + default: 50 + description: The number of results to return per page. Maximum 150. + example: 50 tags: - AI Content operationId: listContentImportSources - description: You can retrieve a list of all content import sources for a workspace. + description: | + You can retrieve a list of all content import sources for a workspace. + + Requires the `read_write_ai_content` OAuth scope. responses: '200': description: successful @@ -853,6 +873,34 @@ paths: 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" + '400': + description: Bad request + content: + application/json: + examples: + Invalid page: + value: + type: error.list + request_id: 6c1f2a54-8d0b-4e0e-9a43-0f5b1d7a2c11 + errors: + - code: parameter_invalid + message: Page must be greater than or equal to 1 + Page size too large: + value: + type: error.list + request_id: b7d94e0a-3f52-4c58-8a1e-52c0e9d36f27 + errors: + - code: parameter_invalid + message: Page size must be less than or equal to 150 schema: "$ref": "#/components/schemas/error" post: @@ -865,8 +913,10 @@ paths: tags: - AI Content operationId: createContentImportSource - description: You can create a new content import source by sending a POST request - to this endpoint. + description: | + You can create a new content import source by sending a POST request to this endpoint. + + Requires the `read_write_ai_content` OAuth scope. responses: '200': description: successful @@ -898,6 +948,48 @@ paths: 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" + '400': + description: Bad request + content: + application/json: + examples: + Missing parameter: + value: + type: error.list + request_id: 0a7e5c31-9b24-4d86-b3f1-6e8d2c4a9f15 + errors: + - code: parameter_not_found + message: sync_behavior is a required parameter + Invalid URL: + value: + type: error.list + request_id: 73d1b8e6-4c0a-4f59-82d7-a5e91c3b0f48 + errors: + - code: parameter_invalid + message: URL must be a valid URI with a http or https protocol + Sync behavior must be api: + value: + type: error.list + request_id: c5f09a27-3e81-4b6d-9a42-d8b17e6c0a93 + errors: + - code: parameter_invalid + message: Sync behavior must be api + Invalid audience IDs: + value: + type: error.list + request_id: 1e6b3d98-a2c7-4f05-8b91-47d0c5e2a6f3 + errors: + - code: parameter_invalid + message: audience_ids contains invalid audience references schema: "$ref": "#/components/schemas/error" requestBody: @@ -923,9 +1015,10 @@ paths: delete: summary: Delete a content import source operationId: deleteContentImportSource - description: You can delete a content import source by making a DELETE request - this endpoint. This will also delete all external pages that were imported - from this source. + description: | + You can delete a content import source by making a DELETE request this endpoint. This will also delete all external pages that were imported from this source. + + Requires the `read_write_ai_content` OAuth scope. parameters: - name: Intercom-Version in: header @@ -948,11 +1041,36 @@ paths: 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: Content import source not found + content: + application/json: + examples: + Content import source not found: + value: + type: error.list + request_id: 2f8a6d13-5b7c-4e49-b0d2-9e1c4a7f3b58 + errors: + - code: not_found + message: Resource Not Found schema: "$ref": "#/components/schemas/error" get: summary: Retrieve a content import source operationId: getContentImportSource + description: | + You can retrieve a content import source. + + Requires the `read_write_ai_content` OAuth scope. parameters: - name: Intercom-Version in: header @@ -991,6 +1109,27 @@ paths: 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: Content import source not found + content: + application/json: + examples: + Content import source not found: + value: + type: error.list + request_id: 2f8a6d13-5b7c-4e49-b0d2-9e1c4a7f3b58 + errors: + - code: not_found + message: Resource Not Found schema: "$ref": "#/components/schemas/error" put: @@ -1003,7 +1142,10 @@ paths: tags: - AI Content operationId: updateContentImportSource - description: You can update an existing content import source. + description: | + You can update an existing content import source. + + Requires the `read_write_ai_content` OAuth scope. responses: '200': description: successful @@ -1035,6 +1177,55 @@ paths: 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" + '400': + description: Bad request + content: + application/json: + examples: + Missing parameter: + value: + type: error.list + request_id: 9d3a1f60-5e27-4c84-a0b6-2f7c8e1d4b59 + errors: + - code: parameter_not_found + message: url is a required parameter + Sync behavior must be api: + value: + type: error.list + request_id: 4b8e2c75-0d19-4a63-95f8-e3a1b7c60d24 + errors: + - code: parameter_invalid + message: Sync behavior must be api + Invalid audience IDs: + value: + type: error.list + request_id: f2c75a09-6b3e-4d18-b4a7-80e9d1c35f62 + errors: + - code: parameter_invalid + message: audience_ids contains invalid audience references + schema: + "$ref": "#/components/schemas/error" + '404': + description: Content import source not found + content: + application/json: + examples: + Content import source not found: + value: + type: error.list + request_id: 2f8a6d13-5b7c-4e49-b0d2-9e1c4a7f3b58 + errors: + - code: not_found + message: Resource Not Found schema: "$ref": "#/components/schemas/error" requestBody: @@ -1056,10 +1247,30 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" + - name: page + in: query + schema: + type: integer + minimum: 1 + default: 1 + description: The page of results to fetch. Defaults to the first page. + example: 1 + - name: per_page + in: query + schema: + type: integer + minimum: 1 + maximum: 150 + default: 50 + description: The number of results to return per page. Maximum 150. + example: 50 tags: - AI Content operationId: listExternalPages - description: You can retrieve a list of all external pages for a workspace. + description: | + You can retrieve a list of all external pages for a workspace. + + Requires the `read_write_ai_content` OAuth scope. responses: '200': description: successful @@ -1081,6 +1292,9 @@ paths: locale: en source_id: 42 external_id: '3' + tags: + type: tag.list + tags: [] created_at: 1734537269 updated_at: 1734537269 last_ingested_at: 1734537269 @@ -1099,6 +1313,9 @@ paths: locale: en source_id: 41 external_id: '2' + tags: + type: tag.list + tags: [] created_at: 1734537269 updated_at: 1734537269 last_ingested_at: 1734537269 @@ -1114,6 +1331,9 @@ paths: locale: en source_id: 40 external_id: '1' + tags: + type: tag.list + tags: [] created_at: 1734537269 updated_at: 1734537269 last_ingested_at: 1734537269 @@ -1138,6 +1358,34 @@ paths: 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" + '400': + description: Bad request + content: + application/json: + examples: + Invalid page: + value: + type: error.list + request_id: 6c1f2a54-8d0b-4e0e-9a43-0f5b1d7a2c11 + errors: + - code: parameter_invalid + message: Page must be greater than or equal to 1 + Page size too large: + value: + type: error.list + request_id: b7d94e0a-3f52-4c58-8a1e-52c0e9d36f27 + errors: + - code: parameter_invalid + message: Page size must be less than or equal to 150 schema: "$ref": "#/components/schemas/error" post: @@ -1150,9 +1398,10 @@ paths: tags: - AI Content operationId: createExternalPage - description: You can create a new external page by sending a POST request to - this endpoint. If an external page already exists with the specified source_id - and external_id, it will be updated instead. + description: | + You can create a new external page by sending a POST request to this endpoint. If an external page already exists with the specified source_id and external_id, it will be updated instead. + + Requires the `read_write_ai_content` OAuth scope. responses: '200': description: successful @@ -1173,6 +1422,9 @@ paths: locale: en source_id: 44 external_id: abc1234 + tags: + type: tag.list + tags: [] created_at: 1734537273 updated_at: 1734537274 last_ingested_at: 1734537274 @@ -1181,6 +1433,34 @@ paths: - 2 schema: "$ref": "#/components/schemas/external_page" + '400': + description: Bad request + content: + application/json: + examples: + Missing parameter: + value: + type: error.list + request_id: 3a9d6e21-8f04-4b7c-a5d3-1c0e7b92f846 + errors: + - code: parameter_not_found + message: external_id is a required parameter + Unsupported locale: + value: + type: error.list + request_id: a8e14c63-2d75-4f09-b1a8-6d3f90c5e7b2 + errors: + - code: parameter_invalid + message: Locale must be supported + Source is not an API source: + value: + type: error.list + request_id: 5f0b9d84-1a36-4e72-8c4d-b27e5a1f0c69 + errors: + - code: parameter_invalid + message: Content Import Source must have API sync behaviour + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -1193,6 +1473,13 @@ paths: 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': @@ -1244,8 +1531,10 @@ paths: tags: - AI Content operationId: deleteExternalPage - description: Sending a DELETE request for an external page will remove it from - the content library UI and from being used for AI answers. + description: | + Sending a DELETE request for an external page will remove it from the content library UI and from being used for AI answers. + + Requires the `read_write_ai_content` OAuth scope. responses: '200': description: successful @@ -1266,6 +1555,9 @@ paths: locale: en source_id: 45 external_id: '4' + tags: + type: tag.list + tags: [] created_at: 1734537276 updated_at: 1734537276 last_ingested_at: 1734537276 @@ -1286,6 +1578,27 @@ paths: 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: External page not found + content: + application/json: + examples: + External page not found: + value: + type: error.list + request_id: d41b7e92-6a03-4f8c-91e5-3c2a8b0f6d74 + errors: + - code: not_found + message: Resource Not Found schema: "$ref": "#/components/schemas/error" get: @@ -1298,7 +1611,10 @@ paths: tags: - AI Content operationId: getExternalPage - description: You can retrieve an external page. + description: | + You can retrieve an external page. + + Requires the `read_write_ai_content` OAuth scope. responses: '200': description: successful @@ -1319,6 +1635,9 @@ paths: locale: en source_id: 46 external_id: '5' + tags: + type: tag.list + tags: [] created_at: 1734537278 updated_at: 1734537278 last_ingested_at: 1734537278 @@ -1339,6 +1658,27 @@ paths: 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: External page not found + content: + application/json: + examples: + External page not found: + value: + type: error.list + request_id: d41b7e92-6a03-4f8c-91e5-3c2a8b0f6d74 + errors: + - code: not_found + message: Resource Not Found schema: "$ref": "#/components/schemas/error" put: @@ -1351,8 +1691,10 @@ paths: tags: - AI Content operationId: updateExternalPage - description: You can update an existing external page (if it was created via - the API). + description: | + You can update an existing external page (if it was created via the API). + + Requires the `read_write_ai_content` OAuth scope. responses: '200': description: successful @@ -1373,6 +1715,9 @@ paths: locale: en source_id: 47 external_id: '5678' + tags: + type: tag.list + tags: [] created_at: 1734537280 updated_at: 1734537281 last_ingested_at: 1734537281 @@ -1381,6 +1726,34 @@ paths: - 2 schema: "$ref": "#/components/schemas/external_page" + '400': + description: Bad request + content: + application/json: + examples: + Missing parameter: + value: + type: error.list + request_id: e07c4a15-9b62-4d38-a1f5-c3d8b6e20a74 + errors: + - code: parameter_not_found + message: html is a required parameter + Source cannot be changed: + value: + type: error.list + request_id: 2d9f6b30-7a58-4c14-93e6-0b4a1d8c5f27 + errors: + - code: parameter_invalid + message: You can't update source_id + Unsupported locale: + value: + type: error.list + request_id: b61a3e97-4c08-4f25-8d70-9e5c2a1b7d43 + errors: + - code: parameter_invalid + message: Locale must be supported + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -1393,6 +1766,13 @@ paths: 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': @@ -34780,10 +35160,12 @@ components: example: api status: type: string - description: The status of the content import source. + description: The status of the content import source. A source that is being + deleted has the status `deletion_in_progress`. enum: - active - deactivated + - deletion_in_progress default: active example: active url: @@ -37290,7 +37672,8 @@ components: example: active url: type: string - description: The URL of the content import source. + description: The URL of the content import source. It must be an http or https + URL on a publicly reachable domain. example: https://help.example.com audience_ids: nullable: true @@ -37586,10 +37969,8 @@ components: example: true locale: type: string - description: Always en - enum: - - en - default: en + description: The language code of the external page, for example `en` + or `fr`. It must be a language supported by the workspace. example: en source_id: type: integer @@ -41774,10 +42155,8 @@ components: example: true locale: type: string - description: Always en - enum: - - en - default: en + description: The language code of the external page, for example `en` + or `fr`. example: en source_id: type: integer @@ -41793,6 +42172,8 @@ components: description: The identifier for the external page which was given by the source. Must be unique for the source. example: '5678' + tags: + "$ref": "#/components/schemas/tags" created_at: type: integer format: date-time @@ -46590,8 +46971,9 @@ components: example: active url: type: string - description: The URL of the content import source. This may only be different - from the existing value if the sync behavior is API. + description: The URL of the content import source. It must be an http or https + URL on a publicly reachable domain. This may only be different from the + existing value if the sync behavior is API. example: https://help.example.com audience_ids: nullable: true @@ -46716,17 +47098,10 @@ components: description: Whether the external page should be used to answer questions by AI Sales Agent. example: true - fin_availability: - type: boolean - description: Deprecated. Use ai_agent_availability, ai_copilot_availability, - and ai_sales_agent_availability instead. - example: true locale: type: string - description: Always en - enum: - - en - default: en + description: The language code of the external page, for example `en` + or `fr`. It must be a language supported by the workspace. example: en source_id: type: integer @@ -46758,9 +47133,9 @@ components: required: - title - html - - url - locale - source_id + - external_id update_team_members_request: description: | The request payload for updating a team's membership. diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 46f3a062..d8106b63 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -1519,10 +1519,30 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" + - name: page + in: query + schema: + type: integer + minimum: 1 + default: 1 + description: The page of results to fetch. Defaults to the first page. + example: 1 + - name: per_page + in: query + schema: + type: integer + minimum: 1 + maximum: 150 + default: 50 + description: The number of results to return per page. Maximum 150. + example: 50 tags: - AI Content operationId: listContentImportSources - description: You can retrieve a list of all content import sources for a workspace. + description: | + You can retrieve a list of all content import sources for a workspace. + + Requires the `read_write_ai_content` OAuth scope. responses: '200': description: successful @@ -1580,6 +1600,34 @@ paths: 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" + '400': + description: Bad request + content: + application/json: + examples: + Invalid page: + value: + type: error.list + request_id: 6c1f2a54-8d0b-4e0e-9a43-0f5b1d7a2c11 + errors: + - code: parameter_invalid + message: Page must be greater than or equal to 1 + Page size too large: + value: + type: error.list + request_id: b7d94e0a-3f52-4c58-8a1e-52c0e9d36f27 + errors: + - code: parameter_invalid + message: Page size must be less than or equal to 150 schema: "$ref": "#/components/schemas/error" post: @@ -1592,8 +1640,10 @@ paths: tags: - AI Content operationId: createContentImportSource - description: You can create a new content import source by sending a POST request - to this endpoint. + description: | + You can create a new content import source by sending a POST request to this endpoint. + + Requires the `read_write_ai_content` OAuth scope. responses: '200': description: successful @@ -1625,6 +1675,48 @@ paths: 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" + '400': + description: Bad request + content: + application/json: + examples: + Missing parameter: + value: + type: error.list + request_id: 0a7e5c31-9b24-4d86-b3f1-6e8d2c4a9f15 + errors: + - code: parameter_not_found + message: sync_behavior is a required parameter + Invalid URL: + value: + type: error.list + request_id: 73d1b8e6-4c0a-4f59-82d7-a5e91c3b0f48 + errors: + - code: parameter_invalid + message: URL must be a valid URI with a http or https protocol + Sync behavior must be api: + value: + type: error.list + request_id: c5f09a27-3e81-4b6d-9a42-d8b17e6c0a93 + errors: + - code: parameter_invalid + message: Sync behavior must be api + Invalid audience IDs: + value: + type: error.list + request_id: 1e6b3d98-a2c7-4f05-8b91-47d0c5e2a6f3 + errors: + - code: parameter_invalid + message: audience_ids contains invalid audience references schema: "$ref": "#/components/schemas/error" requestBody: @@ -1650,9 +1742,10 @@ paths: delete: summary: Delete a content import source operationId: deleteContentImportSource - description: You can delete a content import source by making a DELETE request - this endpoint. This will also delete all external pages that were imported - from this source. + description: | + You can delete a content import source by making a DELETE request this endpoint. This will also delete all external pages that were imported from this source. + + Requires the `read_write_ai_content` OAuth scope. parameters: - name: Intercom-Version in: header @@ -1675,11 +1768,36 @@ paths: 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: Content import source not found + content: + application/json: + examples: + Content import source not found: + value: + type: error.list + request_id: 2f8a6d13-5b7c-4e49-b0d2-9e1c4a7f3b58 + errors: + - code: not_found + message: Resource Not Found schema: "$ref": "#/components/schemas/error" get: summary: Retrieve a content import source operationId: getContentImportSource + description: | + You can retrieve a content import source. + + Requires the `read_write_ai_content` OAuth scope. parameters: - name: Intercom-Version in: header @@ -1718,6 +1836,27 @@ paths: 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: Content import source not found + content: + application/json: + examples: + Content import source not found: + value: + type: error.list + request_id: 2f8a6d13-5b7c-4e49-b0d2-9e1c4a7f3b58 + errors: + - code: not_found + message: Resource Not Found schema: "$ref": "#/components/schemas/error" put: @@ -1730,7 +1869,10 @@ paths: tags: - AI Content operationId: updateContentImportSource - description: You can update an existing content import source. + description: | + You can update an existing content import source. + + Requires the `read_write_ai_content` OAuth scope. responses: '200': description: successful @@ -1762,6 +1904,55 @@ paths: 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" + '400': + description: Bad request + content: + application/json: + examples: + Missing parameter: + value: + type: error.list + request_id: 9d3a1f60-5e27-4c84-a0b6-2f7c8e1d4b59 + errors: + - code: parameter_not_found + message: url is a required parameter + Sync behavior must be api: + value: + type: error.list + request_id: 4b8e2c75-0d19-4a63-95f8-e3a1b7c60d24 + errors: + - code: parameter_invalid + message: Sync behavior must be api + Invalid audience IDs: + value: + type: error.list + request_id: f2c75a09-6b3e-4d18-b4a7-80e9d1c35f62 + errors: + - code: parameter_invalid + message: audience_ids contains invalid audience references + schema: + "$ref": "#/components/schemas/error" + '404': + description: Content import source not found + content: + application/json: + examples: + Content import source not found: + value: + type: error.list + request_id: 2f8a6d13-5b7c-4e49-b0d2-9e1c4a7f3b58 + errors: + - code: not_found + message: Resource Not Found schema: "$ref": "#/components/schemas/error" requestBody: @@ -1783,10 +1974,30 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" + - name: page + in: query + schema: + type: integer + minimum: 1 + default: 1 + description: The page of results to fetch. Defaults to the first page. + example: 1 + - name: per_page + in: query + schema: + type: integer + minimum: 1 + maximum: 150 + default: 50 + description: The number of results to return per page. Maximum 150. + example: 50 tags: - AI Content operationId: listExternalPages - description: You can retrieve a list of all external pages for a workspace. + description: | + You can retrieve a list of all external pages for a workspace. + + Requires the `read_write_ai_content` OAuth scope. responses: '200': description: successful @@ -1809,6 +2020,9 @@ paths: source_id: 42 external_id: '3' audience_ids: [] + tags: + type: tag.list + tags: [] created_at: 1734537269 updated_at: 1734537269 last_ingested_at: 1734537269 @@ -1825,6 +2039,9 @@ paths: source_id: 41 external_id: '2' audience_ids: [] + tags: + type: tag.list + tags: [] created_at: 1734537269 updated_at: 1734537269 last_ingested_at: 1734537269 @@ -1841,6 +2058,9 @@ paths: source_id: 40 external_id: '1' audience_ids: [] + tags: + type: tag.list + tags: [] created_at: 1734537269 updated_at: 1734537269 last_ingested_at: 1734537269 @@ -1865,6 +2085,34 @@ paths: 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" + '400': + description: Bad request + content: + application/json: + examples: + Invalid page: + value: + type: error.list + request_id: 6c1f2a54-8d0b-4e0e-9a43-0f5b1d7a2c11 + errors: + - code: parameter_invalid + message: Page must be greater than or equal to 1 + Page size too large: + value: + type: error.list + request_id: b7d94e0a-3f52-4c58-8a1e-52c0e9d36f27 + errors: + - code: parameter_invalid + message: Page size must be less than or equal to 150 schema: "$ref": "#/components/schemas/error" post: @@ -1877,9 +2125,10 @@ paths: tags: - AI Content operationId: createExternalPage - description: You can create a new external page by sending a POST request to - this endpoint. If an external page already exists with the specified source_id - and external_id, it will be updated instead. + description: | + You can create a new external page by sending a POST request to this endpoint. If an external page already exists with the specified source_id and external_id, it will be updated instead. + + Requires the `read_write_ai_content` OAuth scope. responses: '200': description: successful @@ -1903,6 +2152,9 @@ paths: audience_ids: - 1 - 2 + tags: + type: tag.list + tags: [] created_at: 1734537273 updated_at: 1734537274 last_ingested_at: 1734537274 @@ -1920,6 +2172,62 @@ paths: 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" + '400': + description: Bad request + content: + application/json: + examples: + Missing parameter: + value: + type: error.list + request_id: 3a9d6e21-8f04-4b7c-a5d3-1c0e7b92f846 + errors: + - code: parameter_not_found + message: external_id is a required parameter + Unsupported locale: + value: + type: error.list + request_id: a8e14c63-2d75-4f09-b1a8-6d3f90c5e7b2 + errors: + - code: parameter_invalid + message: Locale must be supported + Source is not an API source: + value: + type: error.list + request_id: 5f0b9d84-1a36-4e72-8c4d-b27e5a1f0c69 + errors: + - code: parameter_invalid + message: Content Import Source must have API sync behaviour + schema: + "$ref": "#/components/schemas/error" + '404': + description: Content import source or audience not found + content: + application/json: + examples: + Content import source not found: + value: + type: error.list + request_id: 58c2f0b9-7e14-4a3d-a6c8-1d9b3e5f7a02 + errors: + - code: content_import_source_not_found + message: Content Import Source not found + Unknown audience IDs: + value: + type: error.list + request_id: e9a30c47-1b6d-4d52-8f0a-7c5e2b9d1a36 + errors: + - code: parameter_invalid + message: 'audience_ids contains unknown audience IDs: 999' schema: "$ref": "#/components/schemas/error" requestBody: @@ -1958,8 +2266,10 @@ paths: tags: - AI Content operationId: deleteExternalPage - description: Sending a DELETE request for an external page will remove it from - the content library UI and from being used for AI answers. + description: | + Sending a DELETE request for an external page will remove it from the content library UI and from being used for AI answers. + + Requires the `read_write_ai_content` OAuth scope. responses: '200': description: successful @@ -1981,6 +2291,9 @@ paths: source_id: 45 external_id: '4' audience_ids: [] + tags: + type: tag.list + tags: [] created_at: 1734537276 updated_at: 1734537276 last_ingested_at: 1734537276 @@ -1998,6 +2311,27 @@ paths: 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: External page not found + content: + application/json: + examples: + External page not found: + value: + type: error.list + request_id: d41b7e92-6a03-4f8c-91e5-3c2a8b0f6d74 + errors: + - code: not_found + message: Resource Not Found schema: "$ref": "#/components/schemas/error" get: @@ -2010,7 +2344,10 @@ paths: tags: - AI Content operationId: getExternalPage - description: You can retrieve an external page. + description: | + You can retrieve an external page. + + Requires the `read_write_ai_content` OAuth scope. responses: '200': description: successful @@ -2032,6 +2369,9 @@ paths: source_id: 46 external_id: '5' audience_ids: [] + tags: + type: tag.list + tags: [] created_at: 1734537278 updated_at: 1734537278 last_ingested_at: 1734537278 @@ -2049,6 +2389,27 @@ paths: 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: External page not found + content: + application/json: + examples: + External page not found: + value: + type: error.list + request_id: d41b7e92-6a03-4f8c-91e5-3c2a8b0f6d74 + errors: + - code: not_found + message: Resource Not Found schema: "$ref": "#/components/schemas/error" put: @@ -2061,8 +2422,10 @@ paths: tags: - AI Content operationId: updateExternalPage - description: You can update an existing external page (if it was created via - the API). + description: | + You can update an existing external page (if it was created via the API). + + Requires the `read_write_ai_content` OAuth scope. responses: '200': description: successful @@ -2086,6 +2449,9 @@ paths: audience_ids: - 1 - 2 + tags: + type: tag.list + tags: [] created_at: 1734537280 updated_at: 1734537281 last_ingested_at: 1734537281 @@ -2103,6 +2469,69 @@ paths: 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" + '400': + description: Bad request + content: + application/json: + examples: + Missing parameter: + value: + type: error.list + request_id: e07c4a15-9b62-4d38-a1f5-c3d8b6e20a74 + errors: + - code: parameter_not_found + message: html is a required parameter + Source cannot be changed: + value: + type: error.list + request_id: 2d9f6b30-7a58-4c14-93e6-0b4a1d8c5f27 + errors: + - code: parameter_invalid + message: You can't update source_id + Unsupported locale: + value: + type: error.list + request_id: b61a3e97-4c08-4f25-8d70-9e5c2a1b7d43 + errors: + - code: parameter_invalid + message: Locale must be supported + schema: + "$ref": "#/components/schemas/error" + '404': + description: External page, content import source or audience not found + content: + application/json: + examples: + External page not found: + value: + type: error.list + request_id: d41b7e92-6a03-4f8c-91e5-3c2a8b0f6d74 + errors: + - code: not_found + message: Resource Not Found + Content import source not found: + value: + type: error.list + request_id: 58c2f0b9-7e14-4a3d-a6c8-1d9b3e5f7a02 + errors: + - code: content_import_source_not_found + message: Content Import Source not found + Unknown audience IDs: + value: + type: error.list + request_id: e9a30c47-1b6d-4d52-8f0a-7c5e2b9d1a36 + errors: + - code: parameter_invalid + message: 'audience_ids contains unknown audience IDs: 999' schema: "$ref": "#/components/schemas/error" requestBody: @@ -30247,10 +30676,12 @@ components: example: api status: type: string - description: The status of the content import source. + description: The status of the content import source. A source that is being + deleted has the status `deletion_in_progress`. enum: - active - deactivated + - deletion_in_progress default: active example: active url: @@ -32785,7 +33216,8 @@ components: example: active url: type: string - description: The URL of the content import source. + description: The URL of the content import source. It must be an http or https + URL on a publicly reachable domain. example: https://help.example.com audience_ids: nullable: true @@ -33074,12 +33506,16 @@ components: by AI Copilot. Will not default when updating an existing external page. default: false example: true + ai_sales_agent_availability: + type: boolean + description: Whether the external page should be used to answer questions + by AI Sales Agent. Will not default when updating an existing external page. + default: false + example: true locale: type: string - description: Always en - enum: - - en - default: en + description: The language code of the external page, for example `en` + or `fr`. It must be a language supported by the workspace. example: en source_id: type: integer @@ -36536,10 +36972,8 @@ components: example: true locale: type: string - description: Always en - enum: - - en - default: en + description: The language code of the external page, for example `en` + or `fr`. example: en source_id: type: integer @@ -36579,6 +37013,8 @@ components: format: date-time description: The time when the external page was last ingested. example: 1672928610 + tags: + "$ref": "#/components/schemas/tags" required: - id - type @@ -40688,8 +41124,9 @@ components: example: active url: type: string - description: The URL of the content import source. This may only be different - from the existing value if the sync behavior is API. + description: The URL of the content import source. It must be an http or https + URL on a publicly reachable domain. This may only be different from the + existing value if the sync behavior is API. example: https://help.example.com audience_ids: nullable: true @@ -40783,18 +41220,25 @@ components: description: The URL of the external page. This will be used by Fin to link end users to the page it based its answer on. example: https://help.example.com/en/articles/1234-getting-started - fin_availability: + ai_agent_availability: type: boolean description: Whether the external page should be used to answer questions - by Fin. - default: true + by AI Agent. + example: true + ai_copilot_availability: + type: boolean + description: Whether the external page should be used to answer questions + by AI Copilot. + example: true + ai_sales_agent_availability: + type: boolean + description: Whether the external page should be used to answer questions + by AI Sales Agent. example: true locale: type: string - description: Always en - enum: - - en - default: en + description: The language code of the external page, for example `en` + or `fr`. It must be a language supported by the workspace. example: en source_id: type: integer @@ -40827,9 +41271,9 @@ components: required: - title - html - - url - locale - source_id + - external_id update_ticket_request: description: You can update a Ticket type: object From 0dde519f202af00b1cd0382369d028d6110cce11 Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Wed, 21 Oct 2026 12:52:18 +0100 Subject: [PATCH 2/8] Align data connector docs with API behaviour Document OAuth scopes and the token scope error, add missing response and request fields, extend execution result enums, fix example cursors and examples to match actual responses, and document the create 400. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 167 +++++++++++++++++++-- descriptions/2.17/api.intercom.io.yaml | 194 +++++++++++++++++++++++-- 2 files changed, 334 insertions(+), 27 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index b2ac4e88..36debdd3 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -19470,6 +19470,8 @@ paths: operationId: listDataConnectors description: | Returns a paginated list of all data connectors for the workspace, ordered by most recently updated first. Data connectors allow workflows and AI agents to make HTTP requests to external APIs. + + Requires the `read_workflow_connector_execution_result` or `read_write_data_connectors` OAuth scope. responses: '200': description: successful @@ -19486,6 +19488,7 @@ paths: description: Fetches order status from external fulfillment API state: live http_method: post + enforce_auth: true direct_fin_usage: false created_by_admin_id: '128' updated_by_admin_id: '128' @@ -19496,7 +19499,7 @@ paths: type: pages per_page: 20 next: - starting_after: WzE3MDc1OTQ3MTUuMCwxMjM0NV0= + starting_after: WzE3Njg5MTg5MzUuMCwxMjM0NSxudWxsXQ== schema: "$ref": "#/components/schemas/data_connector_list" '400': @@ -19525,6 +19528,13 @@ paths: 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" post: @@ -19539,6 +19549,8 @@ paths: operationId: createDataConnector description: | Create a new data connector. The connector is created in `draft` state. Configure its URL, headers, data inputs, and other settings, then set it to `live` when ready. + + Requires the `read_write_data_connectors` OAuth scope. responses: '201': description: Data connector created @@ -19552,6 +19564,10 @@ paths: name: Get Order Status description: Looks up order status from an external service state: draft + url: "https://api.example.com/orders/{{order_id}}/status" + headers: + - name: Content-Type + value: "****" http_method: get direct_fin_usage: true audiences: @@ -19572,6 +19588,7 @@ paths: token_ids: [] customer_authentication: true bypass_authentication: false + enforce_auth: true validate_missing_attributes: true created_by_admin_id: '128' updated_by_admin_id: '128' @@ -19580,6 +19597,27 @@ paths: execution_results_url: "/data_connectors/125/execution_results" schema: "$ref": "#/components/schemas/data_connector_detail" + '400': + description: Invalid parameter + content: + application/json: + examples: + Unpermitted property in headers: + value: + type: error.list + request_id: b4a45e2c-7a8d-4f3e-9c1a-2d5e8f7a6b3c + errors: + - code: parameter_invalid + message: "found unpermitted parameter: :description" + Audiences is not an array: + value: + type: error.list + request_id: f1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b + errors: + - code: parameter_invalid + message: "found unpermitted parameter: :audiences" + schema: + "$ref": "#/components/schemas/error" '422': description: Invalid parameter content: @@ -19641,6 +19679,13 @@ paths: 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" requestBody: @@ -19716,6 +19761,8 @@ paths: You can retrieve the full detail of a single data connector by its ID. The response includes configuration, data inputs, response fields, and object mappings. + + Requires the `read_workflow_connector_execution_result` or `read_write_data_connectors` OAuth scope. responses: '200': description: Data connector found @@ -19729,6 +19776,7 @@ paths: name: Order Status Service description: Fetches order status from external fulfillment API state: live + headers: [] http_method: post direct_fin_usage: false audiences: @@ -19744,8 +19792,6 @@ paths: return transform(inputs['data']) language: python - client_function_name: - client_function_timeout_ms: data_inputs: - name: conversation_id type: string @@ -19761,7 +19807,7 @@ paths: token_ids: [] customer_authentication: false bypass_authentication: false - validate_missing_attributes: + enforce_auth: true created_by_admin_id: '456' updated_by_admin_id: '456' created_at: '2025-11-15T09:30:00Z' @@ -19780,7 +19826,7 @@ paths: request_id: b4a45e2c-7a8d-4f3e-9c1a-2d5e8f7a6b3c errors: - code: parameter_invalid - message: "Invalid state_version. Must be one of: live, draft" + message: "Invalid state_version. Must be one of: draft, live" schema: "$ref": "#/components/schemas/error" '404': @@ -19809,6 +19855,13 @@ paths: 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" delete: @@ -19830,6 +19883,8 @@ paths: operationId: deleteDataConnector description: | Delete an existing data connector. The connector must be in `draft` state and must not be in use by any workflows or AI agents. + + Requires the `read_write_data_connectors` OAuth scope. responses: '200': description: Data connector deleted @@ -19890,6 +19945,13 @@ paths: 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" patch: @@ -19911,6 +19973,8 @@ paths: operationId: updateDataConnector description: | Update an existing data connector. Only provided fields are changed. Set `state` to `live` or `draft` to change the connector's state. + + Requires the `read_write_data_connectors` OAuth scope. requestBody: content: application/json: @@ -19960,6 +20024,7 @@ paths: name: Updated Connector Name description: Updated description state: draft + headers: [] http_method: post direct_fin_usage: false audiences: @@ -19967,9 +20032,6 @@ paths: - leads execution_type: server_side configuration_response_type: test_response_type - data_transformation_type: - client_function_name: - client_function_timeout_ms: data_inputs: - name: conversation_id type: string @@ -19981,6 +20043,7 @@ paths: token_ids: [] customer_authentication: false bypass_authentication: false + enforce_auth: true validate_missing_attributes: false created_by_admin_id: '456' updated_by_admin_id: '456' @@ -20099,6 +20162,13 @@ paths: 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" "/data_connectors/{data_connector_id}/execution_results": @@ -20158,6 +20228,8 @@ paths: - non_fin_standalone_action_identity_verification_error - request_validation_error - client_side_action_error + - code_block_transformation_error + - otp_preview_not_supported_error - name: start_ts in: query required: false @@ -20187,6 +20259,8 @@ paths: Results from the last hour are returned by default. Use `start_ts` and `end_ts` to customize the time range. Request/response bodies are excluded by default. Use `include_bodies=true` to include them. + + Requires the `read_workflow_connector_execution_result` or `read_write_data_connectors` OAuth scope. responses: '200': description: successful @@ -20213,7 +20287,6 @@ paths: id: '99000' data_connector_id: '12345' success: false - http_status: http_method: post error_type: 3rd_party_error error_message: Connection refused @@ -20223,7 +20296,7 @@ paths: type: pages per_page: 10 next: - starting_after: WzE3MDc1OTQ3MTUuMCw5OTAwMF0= + starting_after: WzE3NzA3NDU1MTUuMCw5OTAwMCxudWxsXQ== schema: "$ref": "#/components/schemas/data_connector_execution_result_list" '401': @@ -20238,6 +20311,13 @@ paths: 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" '400': @@ -20251,7 +20331,7 @@ paths: request_id: test-uuid-replacement errors: - code: parameter_invalid - message: "Invalid error_type. Must be one of: request_configuration_error, faraday_error, 3rd_party_error, response_mapping_error, token_refresh_error, fin_action_response_formatting_error, fin_action_identity_verification_error, email_verification_error, non_fin_standalone_action_identity_verification_error, request_validation_error, client_side_action_error" + message: "Invalid error_type. Must be one of: request_configuration_error, faraday_error, 3rd_party_error, response_mapping_error, token_refresh_error, fin_action_response_formatting_error, fin_action_identity_verification_error, email_verification_error, non_fin_standalone_action_identity_verification_error, request_validation_error, client_side_action_error, code_block_transformation_error, otp_preview_not_supported_error" Invalid timestamp: value: type: error.list @@ -20259,6 +20339,13 @@ paths: errors: - code: parameter_invalid message: start_ts must be a Unix timestamp (integer) + Invalid cursor: + value: + type: error.list + request_id: test-uuid-replacement + errors: + - code: client_error + message: Invalid starting_after param. Please try again using a starting_after value from a paginated response schema: "$ref": "#/components/schemas/error" '404': @@ -20303,6 +20390,8 @@ paths: description: | Retrieve details for a specific data connector execution result. Always includes request/response bodies and the sanitised request URL. + + Requires the `read_workflow_connector_execution_result` or `read_write_data_connectors` OAuth scope. responses: '200': description: successful @@ -20340,6 +20429,13 @@ paths: 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': @@ -39654,6 +39750,9 @@ components: type: string description: A description of what this data connector does. example: Looks up order status from an external service + internal_description: + type: string + description: The internal description of the data connector. http_method: type: string description: The HTTP method used when calling the external API. @@ -39701,6 +39800,9 @@ components: type: string description: The header value. Supports template variables. example: application/json + required: + - name + - value data_inputs: type: array description: Input parameters accepted by the connector. @@ -39731,6 +39833,11 @@ components: default_value: type: string description: The default value for the parameter. Defaults to an empty string if omitted. + required: + - name + - description + - type + - required customer_authentication: type: boolean description: Whether the connector requires customer authentication before executing. Defaults to false. @@ -39739,6 +39846,9 @@ components: type: boolean description: Whether authentication is bypassed entirely (public endpoint). Defaults to false. example: false + enforce_auth: + type: boolean + description: Whether authentication is enforced for this connector. validate_missing_attributes: type: boolean description: Whether to validate that all required data inputs have values before executing. @@ -39812,6 +39922,9 @@ components: type: string description: A description of what this data connector does. example: Updated description + internal_description: + type: string + description: The internal description of the data connector. state: type: string description: The desired state of the connector. @@ -39865,6 +39978,9 @@ components: type: string description: The header value. Supports template variables. example: application/json + required: + - name + - value data_inputs: type: array description: The input parameters accepted by this data connector. Replaces all existing inputs. @@ -39895,6 +40011,11 @@ components: default_value: type: string description: The default value for this input, if any. + required: + - name + - description + - type + - required customer_authentication: type: boolean description: Whether OTP authentication is enabled for this connector. @@ -39903,6 +40024,9 @@ components: type: boolean description: Whether authentication is bypassed for this connector. example: false + enforce_auth: + type: boolean + description: Whether authentication is enforced for this connector. validate_missing_attributes: type: boolean description: Whether to validate missing attributes before execution. @@ -39987,6 +40111,9 @@ components: nullable: true description: A description of what this data connector does. example: Fetches order status from external fulfillment API + internal_description: + type: string + description: The internal description of the data connector. state: type: string description: The current state of the data connector. @@ -40004,6 +40131,10 @@ components: - delete - patch example: post + enforce_auth: + type: boolean + description: Whether authentication is enforced for this connector. + example: true direct_fin_usage: type: boolean description: Whether this data connector is assigned to Fin for direct usage. @@ -40058,6 +40189,9 @@ components: nullable: true description: A description of what this data connector does. example: Fetches order status from external fulfillment API + internal_description: + type: string + description: The internal description of the data connector. state: type: string description: The current state of the data connector. @@ -40287,6 +40421,10 @@ components: type: boolean description: Whether authentication is bypassed for this connector. example: false + enforce_auth: + type: boolean + description: Whether authentication is enforced for this connector. + example: true validate_missing_attributes: type: boolean nullable: true @@ -40371,6 +40509,8 @@ components: - non_fin_standalone_action_identity_verification_error - request_validation_error - client_side_action_error + - code_block_transformation_error + - otp_preview_not_supported_error example: 3rd_party_error error_message: type: string @@ -40396,6 +40536,7 @@ components: - triggerable_custom_bot - inbox - fin + - synthetic_test example: workflow source_id: type: string @@ -40469,7 +40610,7 @@ components: starting_after: type: string description: The cursor value to use for the next page. - example: WzE3MDc1OTQ3MTUuMCw5OTAwMF0= + example: WzE3NzA3NDU1MTUuMCw5OTAwMCxudWxsXQ== data_connector_list: title: Data Connector List type: object @@ -40507,7 +40648,7 @@ components: starting_after: type: string description: The cursor value to use for the next page. - example: WzE3MDc1OTQ3MTUuMCwxMjM0NV0= + example: WzE3Njg5MTg5MzUuMCwxMjM0NSxudWxsXQ== data_connector_version_list: title: Data Connector Version List type: object diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index d8106b63..d16c2d77 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -18488,6 +18488,8 @@ paths: operationId: listDataConnectors description: | Returns a paginated list of all data connectors for the workspace, ordered by most recently updated first. Data connectors allow workflows and AI agents to make HTTP requests to external APIs. + + Requires the `read_workflow_connector_execution_result` or `read_write_data_connectors` OAuth scope. responses: '200': description: successful @@ -18504,6 +18506,7 @@ paths: description: Fetches order status from external fulfillment API state: live http_method: post + enforce_auth: true direct_fin_usage: false created_by_admin_id: '128' updated_by_admin_id: '128' @@ -18514,7 +18517,7 @@ paths: type: pages per_page: 20 next: - starting_after: WzE3MDc1OTQ3MTUuMCwxMjM0NV0= + starting_after: WzE3Njg5MTg5MzUuMCwxMjM0NSxudWxsXQ== schema: "$ref": "#/components/schemas/data_connector_list" '400': @@ -18543,6 +18546,13 @@ paths: 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" post: @@ -18557,6 +18567,8 @@ paths: operationId: createDataConnector description: | Create a new data connector. The connector is created in `draft` state. Configure its URL, headers, data inputs, and other settings, then set it to `live` when ready. + + Requires the `read_write_data_connectors` OAuth scope. responses: '201': description: Data connector created @@ -18570,6 +18582,10 @@ paths: name: Get Order Status description: Looks up order status from an external service state: draft + url: "https://api.example.com/orders/{{order_id}}/status" + headers: + - name: Content-Type + value: "****" http_method: get direct_fin_usage: true audiences: @@ -18590,6 +18606,7 @@ paths: token_ids: [] customer_authentication: true bypass_authentication: false + enforce_auth: true validate_missing_attributes: true created_by_admin_id: '128' updated_by_admin_id: '128' @@ -18598,6 +18615,27 @@ paths: execution_results_url: "/data_connectors/125/execution_results" schema: "$ref": "#/components/schemas/data_connector_detail" + '400': + description: Invalid parameter + content: + application/json: + examples: + Unpermitted property in headers: + value: + type: error.list + request_id: b4a45e2c-7a8d-4f3e-9c1a-2d5e8f7a6b3c + errors: + - code: parameter_invalid + message: "found unpermitted parameter: :description" + Audiences is not an array: + value: + type: error.list + request_id: f1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b + errors: + - code: parameter_invalid + message: "found unpermitted parameter: :audiences" + schema: + "$ref": "#/components/schemas/error" '422': description: Invalid parameter content: @@ -18631,6 +18669,13 @@ paths: 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" requestBody: @@ -18706,6 +18751,8 @@ paths: You can retrieve the full detail of a single data connector by its ID. The response includes configuration, data inputs, response fields, and object mappings. + + Requires the `read_workflow_connector_execution_result` or `read_write_data_connectors` OAuth scope. responses: '200': description: Data connector found @@ -18719,6 +18766,7 @@ paths: name: Order Status Service description: Fetches order status from external fulfillment API state: live + headers: [] http_method: post direct_fin_usage: false audiences: @@ -18726,9 +18774,6 @@ paths: - leads execution_type: server_side configuration_response_type: test_response_type - data_transformation_type: - client_function_name: - client_function_timeout_ms: data_inputs: - name: conversation_id type: string @@ -18744,7 +18789,7 @@ paths: token_ids: [] customer_authentication: false bypass_authentication: false - validate_missing_attributes: + enforce_auth: true created_by_admin_id: '456' updated_by_admin_id: '456' created_at: '2025-11-15T09:30:00Z' @@ -18763,7 +18808,7 @@ paths: request_id: b4a45e2c-7a8d-4f3e-9c1a-2d5e8f7a6b3c errors: - code: parameter_invalid - message: "Invalid state_version. Must be one of: live, draft" + message: "Invalid state_version. Must be one of: draft, live" schema: "$ref": "#/components/schemas/error" '404': @@ -18792,6 +18837,13 @@ paths: 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" delete: @@ -18813,6 +18865,8 @@ paths: operationId: deleteDataConnector description: | Delete an existing data connector. The connector must be in `draft` state and must not be in use by any workflows or AI agents. + + Requires the `read_write_data_connectors` OAuth scope. responses: '200': description: Data connector deleted @@ -18873,6 +18927,13 @@ paths: 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" patch: @@ -18894,6 +18955,8 @@ paths: operationId: updateDataConnector description: | Update an existing data connector. Only provided fields are changed. Set `state` to `live` or `draft` to change the connector's state. + + Requires the `read_write_data_connectors` OAuth scope. requestBody: content: application/json: @@ -18933,6 +18996,7 @@ paths: name: Updated Connector Name description: Updated description state: draft + headers: [] http_method: post direct_fin_usage: false audiences: @@ -18940,9 +19004,6 @@ paths: - leads execution_type: server_side configuration_response_type: test_response_type - data_transformation_type: - client_function_name: - client_function_timeout_ms: data_inputs: - name: conversation_id type: string @@ -18954,6 +19015,7 @@ paths: token_ids: [] customer_authentication: false bypass_authentication: false + enforce_auth: true validate_missing_attributes: false created_by_admin_id: '456' updated_by_admin_id: '456' @@ -19030,6 +19092,13 @@ paths: 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" "/data_connectors/{data_connector_id}/execution_results": @@ -19089,6 +19158,8 @@ paths: - non_fin_standalone_action_identity_verification_error - request_validation_error - client_side_action_error + - code_block_transformation_error + - otp_preview_not_supported_error - name: start_ts in: query required: false @@ -19118,6 +19189,8 @@ paths: Results from the last hour are returned by default. Use `start_ts` and `end_ts` to customize the time range. Request/response bodies are excluded by default. Use `include_bodies=true` to include them. + + Requires the `read_workflow_connector_execution_result` or `read_write_data_connectors` OAuth scope. responses: '200': description: successful @@ -19144,7 +19217,6 @@ paths: id: '99000' data_connector_id: '12345' success: false - http_status: http_method: post error_type: 3rd_party_error error_message: Connection refused @@ -19154,7 +19226,7 @@ paths: type: pages per_page: 10 next: - starting_after: WzE3MDc1OTQ3MTUuMCw5OTAwMF0= + starting_after: WzE3NzA3NDU1MTUuMCw5OTAwMCxudWxsXQ== schema: "$ref": "#/components/schemas/data_connector_execution_result_list" '401': @@ -19169,6 +19241,13 @@ paths: 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" '400': @@ -19182,7 +19261,7 @@ paths: request_id: test-uuid-replacement errors: - code: parameter_invalid - message: "Invalid error_type. Must be one of: request_configuration_error, faraday_error, 3rd_party_error, response_mapping_error, token_refresh_error, fin_action_response_formatting_error, fin_action_identity_verification_error, email_verification_error, non_fin_standalone_action_identity_verification_error, request_validation_error, client_side_action_error" + message: "Invalid error_type. Must be one of: request_configuration_error, faraday_error, 3rd_party_error, response_mapping_error, token_refresh_error, fin_action_response_formatting_error, fin_action_identity_verification_error, email_verification_error, non_fin_standalone_action_identity_verification_error, request_validation_error, client_side_action_error, code_block_transformation_error, otp_preview_not_supported_error" Invalid timestamp: value: type: error.list @@ -19190,6 +19269,13 @@ paths: errors: - code: parameter_invalid message: start_ts must be a Unix timestamp (integer) + Invalid cursor: + value: + type: error.list + request_id: test-uuid-replacement + errors: + - code: client_error + message: Invalid starting_after param. Please try again using a starting_after value from a paginated response schema: "$ref": "#/components/schemas/error" '404': @@ -19234,6 +19320,8 @@ paths: description: | Retrieve details for a specific data connector execution result. Always includes request/response bodies and the sanitised request URL. + + Requires the `read_workflow_connector_execution_result` or `read_write_data_connectors` OAuth scope. responses: '200': description: successful @@ -19271,6 +19359,13 @@ paths: 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': @@ -35165,6 +35260,9 @@ components: type: string description: A description of what this data connector does. example: Looks up order status from an external service + internal_description: + type: string + description: The internal description of the data connector. http_method: type: string description: The HTTP method used when calling the external API. @@ -35212,6 +35310,9 @@ components: type: string description: The header value. Supports template variables. example: application/json + required: + - name + - value data_inputs: type: array description: Input parameters accepted by the connector. @@ -35242,6 +35343,11 @@ components: default_value: type: string description: The default value for the parameter. Defaults to an empty string if omitted. + required: + - name + - description + - type + - required customer_authentication: type: boolean description: Whether the connector requires customer authentication before executing. Defaults to false. @@ -35250,6 +35356,9 @@ components: type: boolean description: Whether authentication is bypassed entirely (public endpoint). Defaults to false. example: false + enforce_auth: + type: boolean + description: Whether authentication is enforced for this connector. validate_missing_attributes: type: boolean description: Whether to validate that all required data inputs have values before executing. @@ -35285,6 +35394,9 @@ components: type: string description: A description of what this data connector does. example: Updated description + internal_description: + type: string + description: The internal description of the data connector. state: type: string description: The desired state of the connector. @@ -35338,6 +35450,9 @@ components: type: string description: The header value. Supports template variables. example: application/json + required: + - name + - value data_inputs: type: array description: The input parameters accepted by this data connector. Replaces all existing inputs. @@ -35368,6 +35483,11 @@ components: default_value: type: string description: The default value for this input, if any. + required: + - name + - description + - type + - required customer_authentication: type: boolean description: Whether OTP authentication is enabled for this connector. @@ -35376,6 +35496,9 @@ components: type: boolean description: Whether authentication is bypassed for this connector. example: false + enforce_auth: + type: boolean + description: Whether authentication is enforced for this connector. validate_missing_attributes: type: boolean description: Whether to validate missing attributes before execution. @@ -35422,6 +35545,9 @@ components: nullable: true description: A description of what this data connector does. example: Fetches order status from external fulfillment API + internal_description: + type: string + description: The internal description of the data connector. state: type: string description: The current state of the data connector. @@ -35439,6 +35565,10 @@ components: - delete - patch example: post + enforce_auth: + type: boolean + description: Whether authentication is enforced for this connector. + example: true direct_fin_usage: type: boolean description: Whether this data connector is assigned to Fin for direct usage. @@ -35493,6 +35623,9 @@ components: nullable: true description: A description of what this data connector does. example: Fetches order status from external fulfillment API + internal_description: + type: string + description: The internal description of the data connector. state: type: string description: The current state of the data connector. @@ -35576,6 +35709,32 @@ components: - full_access - redacted_access - code_block_transformation + transform_code_block: + type: object + nullable: true + description: | + The code block used to transform the connector's response when `data_transformation_type` is + `code_block_transformation`. Omitted if the connector has no transform code block configured. + example: + code: | + def transform(response): + return {"status": response["order_status"]} + + return transform(inputs['data']) + language: python + properties: + code: + type: string + description: The source code of the transform code block. The API response body is available as `inputs['data']`, and the code must end with a top-level `return` of the transformed value. + example: | + def transform(response): + return {"status": response["order_status"]} + + return transform(inputs['data']) + language: + type: string + description: The programming language of the transform code block. Currently always `python`. + example: python client_function_name: type: string nullable: true @@ -35696,6 +35855,10 @@ components: type: boolean description: Whether authentication is bypassed for this connector. example: false + enforce_auth: + type: boolean + description: Whether authentication is enforced for this connector. + example: true validate_missing_attributes: type: boolean nullable: true @@ -35780,6 +35943,8 @@ components: - non_fin_standalone_action_identity_verification_error - request_validation_error - client_side_action_error + - code_block_transformation_error + - otp_preview_not_supported_error example: 3rd_party_error error_message: type: string @@ -35805,6 +35970,7 @@ components: - triggerable_custom_bot - inbox - fin + - synthetic_test example: workflow source_id: type: string @@ -35878,7 +36044,7 @@ components: starting_after: type: string description: The cursor value to use for the next page. - example: WzE3MDc1OTQ3MTUuMCw5OTAwMF0= + example: WzE3NzA3NDU1MTUuMCw5OTAwMCxudWxsXQ== data_connector_list: title: Data Connector List type: object @@ -35916,7 +36082,7 @@ components: starting_after: type: string description: The cursor value to use for the next page. - example: WzE3MDc1OTQ3MTUuMCwxMjM0NV0= + example: WzE3Njg5MTg5MzUuMCwxMjM0NSxudWxsXQ== data_connector_version_list: title: Data Connector Version List type: object From 539a03deb85e615ceb0549110e76b0f9b5665fea Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Wed, 21 Oct 2026 12:55:14 +0100 Subject: [PATCH 3/8] Align Fin Agent API and workflow export error responses and fields with the API Co-Authored-By: Claude Sonnet 5.5 --- descriptions/0/api.intercom.io.yaml | 815 +++++++++++++++++++++--- descriptions/2.17/api.intercom.io.yaml | 816 ++++++++++++++++++++++--- 2 files changed, 1440 insertions(+), 191 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 36debdd3..fcf007f7 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -21874,6 +21874,20 @@ paths: embedded_rules: [] schema: "$ref": "#/components/schemas/workflow_export" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" '404': description: Workflow not found content: @@ -21885,21 +21899,21 @@ paths: request_id: b3c8c472-8478-4f10-a29e-a23dbf921c46 errors: - code: not_found - message: Workflow not found + message: 'Workflow not found with id: 12345' schema: "$ref": "#/components/schemas/error" - '403': - description: Workflow export is not available for this app + '503': + description: Workflow export is currently disabled content: application/json: examples: - Feature not available: + Workflow export disabled: value: type: error.list request_id: d92f7e84-5c31-4a2b-b8e6-9f4c3d2a1b0e errors: - - code: api_plan_restricted - message: Workflow export is not available for this app + - code: service_unavailable + message: Workflow export is currently disabled schema: "$ref": "#/components/schemas/error" "/download/content/data/{job_identifier}": @@ -28972,7 +28986,7 @@ paths: The response is audience-matched to the supplied user: each live, API-triggerable procedure is checked against that user before being included, alongside the static - `reply` and `ask` actions. + `reply`, `ask`, and `escalate` actions. {% admonition type="warning" %} To request access to the Fin Agent API, go to **Settings > Integrations > Fin Agent API** in your workspace and tell us about your use case. Once access is granted, **Fin Agent API** appears under **Fin AI Agent > Deploy**. @@ -28985,22 +28999,223 @@ paths: examples: Successful response: value: - version: Preview - capabilities: - - type: procedure - id: '12345' - name: Reset password - description: Walk the user through resetting their password. - endpoint: /fin/procedures/12345/run - method: POST - - type: reply - description: Reply to an in-progress Fin conversation. - endpoint: /fin/reply - method: POST - - type: ask - description: Ask Fin a single, self-contained question. - endpoint: /fin/ask - method: POST + version: Preview + capabilities: + - name: run_procedure_reset_password_12345 + description: |- + + Walk the user through resetting their password. + + inputSchema: + type: object + properties: + conversation_id: + type: string + description: A unique external ID for the new conversation. Must not already exist for this workspace. + user: + type: object + description: The end user the action is performed for. + properties: + id: + type: string + description: The user's external ID. + name: + type: string + email: + type: string + attributes: + type: object + description: Custom user attributes (max 10). + required: + - id + message: + type: object + description: Optional trigger message posted before the procedure runs. + properties: + body: + type: string + author: + type: string + enum: + - user + - agent + - fin + required: + - body + conversation_metadata: + type: object + properties: + attributes: + type: object + required: + - conversation_id + - user + endpoint: /fin/procedures/12345/run + method: POST + - name: reply + description: Send a user reply into an existing Fin conversation and get Fin's next turn. Use this to continue any ongoing conversation — including one opened by a procedure run — whenever its status is `awaiting_user_reply`. + inputSchema: + type: object + properties: + conversation_id: + type: string + description: External ID of the existing conversation to reply to. + message: + type: object + properties: + author: + type: string + enum: + - user + - agent + - fin + body: + type: string + timestamp: + type: string + timestamp_ms: + type: string + required: + - author + - body + user: + type: object + description: The end user the action is performed for. + properties: + id: + type: string + description: The user's external ID. + name: + type: string + email: + type: string + attributes: + type: object + description: Custom user attributes (max 10). + required: + - id + attachments: + type: array + description: Optional attachments to include with the message. + response_format: + type: string + enum: + - html + - markdown + description: Response body format. Defaults to html. + required: + - conversation_id + - message + - user + endpoint: /fin/reply + method: POST + - name: ask + description: Ask Fin a single question and get one informational answer. Fin never escalates, disambiguates, or asks follow-up questions. Use for one-shot informational lookups. + inputSchema: + type: object + properties: + conversation_id: + type: string + description: External ID for the conversation. + message: + type: object + properties: + author: + type: string + enum: + - user + - agent + - fin + body: + type: string + timestamp: + type: string + timestamp_ms: + type: string + required: + - author + - body + user: + type: object + description: The end user the action is performed for. + properties: + id: + type: string + description: The user's external ID. + name: + type: string + email: + type: string + attributes: + type: object + description: Custom user attributes (max 10). + required: + - id + conversation_metadata: + type: object + properties: + history: + type: array + attributes: + type: object + attachments: + type: array + description: Optional attachments to include with the message. + response_format: + type: string + enum: + - html + - markdown + description: Response body format. Defaults to html. + required: + - conversation_id + - message + - user + endpoint: /fin/ask + method: POST + - name: escalate + description: Hand off to a human team. Summarises the conversation into a new human-facing support conversation routed to the inbox, leaving this one untouched, and notifies you when the handoff completes. Use when the user asks for a human or when you decide Fin can't resolve the request. + inputSchema: + type: object + description: Escalate an existing conversation (conversation_id) or a new one (user) — not both. + oneOf: + - properties: + conversation_id: + type: string + description: External ID of the conversation to escalate. + context: + type: string + maxLength: 10000 + description: Background for the teammate who picks up the handoff. Never shown to the end user. + required: + - conversation_id + additionalProperties: false + - properties: + user: + type: object + description: The end user the action is performed for. + properties: + id: + type: string + description: The user's external ID. + name: + type: string + email: + type: string + attributes: + type: object + description: Custom user attributes (max 10). + required: + - id + context: + type: string + maxLength: 10000 + description: Background for the teammate who picks up the handoff. Never shown to the end user. + required: + - user + additionalProperties: false + endpoint: /fin/escalate + method: POST schema: type: object properties: @@ -29010,26 +29225,23 @@ paths: example: Preview capabilities: type: array - description: The list of capabilities available to this user. + description: The list of capabilities available to this user, as tool definitions. items: type: object properties: - type: - type: string - description: The kind of capability — `procedure` for a runnable procedure, or a static action such as `reply`, `ask`, or `escalate`. - example: procedure - id: - type: string - description: The procedure ID. Present only when `type` is `procedure`. - example: '12345' name: type: string - description: The procedure name. Present only when `type` is `procedure`. - example: Reset password + description: The capability name. Procedures are named `run_procedure__<id>`; the static actions are named `reply`, `ask`, and `escalate`. + example: run_procedure_reset_password_12345 description: type: string - description: A human-readable description of the capability. - example: Walk the user through resetting their password. + nullable: true + description: A description of the capability. For a procedure, the text is wrapped in `<untrusted-content>` tags, and is null when the procedure has no description. + example: Reply to an in-progress Fin conversation. + inputSchema: + type: object + description: A JSON Schema describing the request body to send to the capability's endpoint. + additionalProperties: true endpoint: type: string description: The endpoint path to call to use this capability. @@ -29038,18 +29250,20 @@ paths: type: string description: The HTTP method to use. example: POST + errors: + "$ref": "#/components/schemas/fin_agent_attribute_errors" '400': description: Bad Request content: application/json: examples: - Too many attributes: + Not available in this API version: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: Cannot update more than 10 attributes at once. + - code: intercom_version_invalid + message: Requested resource is not available in current API version schema: "$ref": "#/components/schemas/error" '401': @@ -29064,8 +29278,54 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token not authorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" + '403': + description: Forbidden + content: + application/json: + examples: + Fin Agent API not enabled: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: api_plan_restricted + message: Fin Agent API is not enabled for your app. + Wrong credentials for the Fin Agent API: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: forbidden + message: Use your workspace's Fin Agent API key to call the Fin Agent API + schema: + "$ref": "#/components/schemas/error" + '422': + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + content: + application/json: + examples: + Too many user attributes: + value: + errors: + user: Cannot update more than 10 attributes at once. Received 11 attributes. + schema: + type: object + properties: + errors: + type: object + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + example: + conversation_id: Conversation ID is required + additionalProperties: true requestBody: required: true content: @@ -29178,43 +29438,102 @@ paths: content: application/json: examples: - Conversation ID missing: + Not available in this API version: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: External Conversation ID is required - User ID missing: + - code: intercom_version_invalid + message: Requested resource is not available in current API version + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: User ID is required - Too many history items: + - code: unauthorized + message: Access Token Invalid + Token not authorized: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: Conversation history cannot contain more than 10 items + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" - '401': - description: Unauthorized + '403': + description: Forbidden content: application/json: examples: - Unauthorized: + Fin Agent API not enabled: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: unauthorized - message: Access Token Invalid + - code: api_plan_restricted + message: Fin Agent API is not enabled for your app. + Wrong credentials for the Fin Agent API: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: forbidden + message: Use your workspace's Fin Agent API key to call the Fin Agent API + Response format not available: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: api_plan_restricted + message: The requested response format is not available. schema: "$ref": "#/components/schemas/error" + '422': + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + content: + application/json: + examples: + Conversation ID missing: + value: + errors: + conversation_id: Conversation ID is required + Conversation already exists: + value: + errors: + conversation_id: Fin session already exists for this conversation. Please use /reply to continue the conversation. + Message timestamp missing: + value: + errors: + message: timestamp_ms is required + Too many user attributes: + value: + errors: + user: Cannot update more than 10 attributes at once. Received 11 attributes. + Too many history items: + value: + errors: + conversation_metadata: Conversation history cannot contain more than 10 items + Invalid environment: + value: + errors: + environment: Invalid environment + schema: + type: object + properties: + errors: + type: object + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + example: + conversation_id: Conversation ID is required + additionalProperties: true requestBody: required: true content: @@ -29242,6 +29561,14 @@ paths: type: string description: The identifier of the environment to start the conversation in, if your Fin for Platforms workspace has environments. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment; an identifier that matches no environment is rejected. example: a1b2c3d4e5 + response_format: + type: string + enum: + - html + - markdown + default: html + description: The format of the `body` in Fin's replies. Defaults to `html`. Requesting `markdown` on a workspace where it is not enabled returns a 403 error. + example: html required: - conversation_id - message @@ -29367,13 +29694,13 @@ paths: content: application/json: examples: - Invalid request: + Not available in this API version: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: conversation_id is required + - code: intercom_version_invalid + message: Requested resource is not available in current API version schema: "$ref": "#/components/schemas/error" '401': @@ -29388,8 +29715,73 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token not authorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '403': + description: Forbidden + content: + application/json: + examples: + Fin Agent API not enabled: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: api_plan_restricted + message: Fin Agent API is not enabled for your app. + Wrong credentials for the Fin Agent API: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: forbidden + message: Use your workspace's Fin Agent API key to call the Fin Agent API + Response format not available: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: api_plan_restricted + message: The requested response format is not available. schema: "$ref": "#/components/schemas/error" + '422': + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + content: + application/json: + examples: + Conversation ID missing: + value: + errors: + conversation_id: Conversation ID is required + Conversation not found: + value: + errors: + conversation_id: Conversation not found for the given conversation_id + Message timestamp missing: + value: + errors: + message: timestamp_ms is required + Too many user attributes: + value: + errors: + user: Cannot update more than 10 attributes at once. Received 11 attributes. + schema: + type: object + properties: + errors: + type: object + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + example: + conversation_id: Conversation ID is required + additionalProperties: true requestBody: required: true content: @@ -29411,6 +29803,14 @@ paths: maxItems: 10 items: "$ref": "#/components/schemas/fin_agent_attachment" + response_format: + type: string + enum: + - html + - markdown + default: html + description: The format of the `body` in Fin's replies. Defaults to `html`. Requesting `markdown` on a workspace where it is not enabled returns a 403 error. + example: html required: - conversation_id - message @@ -29546,57 +29946,103 @@ paths: content: application/json: examples: - Procedure not found: + Not available in this API version: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: Procedure not found - Procedure not live: + - code: intercom_version_invalid + message: Requested resource is not available in current API version + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: Procedure is not live - Procedure has no API trigger: + - code: unauthorized + message: Access Token Invalid + Token not authorized: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: Procedure does not have an API trigger - No Fin profile: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '403': + description: Forbidden + content: + application/json: + examples: + Fin Agent API not enabled: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: No Fin profile is configured to handle this conversation. Configure a Fin profile and retry. - Conversation already exists: + - code: api_plan_restricted + message: Fin Agent API is not enabled for your app. + Wrong credentials for the Fin Agent API: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: Fin session already exists for this conversation. Please use /reply to continue the conversation. + - code: forbidden + message: Use your workspace's Fin Agent API key to call the Fin Agent API schema: "$ref": "#/components/schemas/error" - '401': - description: Unauthorized + '422': + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. content: application/json: examples: - Unauthorized: + Conversation ID missing: value: - type: error.list - request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: unauthorized - message: Access Token Invalid + conversation_id: Conversation ID is required + Procedure not found: + value: + errors: + procedure_id: Procedure not found + Procedure not live: + value: + errors: + procedure_id: Procedure is not live + Procedure not available on the Fin Agent API channel: + value: + errors: + procedure_id: Procedure is not available on the Fin Agent API channel + Procedure not available for this user: + value: + errors: + procedure_id: Procedure is not available for this user + No Fin profile: + value: + errors: + base: No Fin profile is configured to handle this conversation. Configure a Fin profile and retry. + Conversation already exists: + value: + errors: + conversation_id: Fin session already exists for this conversation. Please use /reply to continue the conversation. + Invalid environment: + value: + errors: + environment: Invalid environment schema: - "$ref": "#/components/schemas/error" + type: object + properties: + errors: + type: object + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + example: + conversation_id: Conversation ID is required + additionalProperties: true requestBody: required: true content: @@ -29611,7 +30057,23 @@ paths: user: "$ref": "#/components/schemas/fin_agent_user" message: - "$ref": "#/components/schemas/fin_agent_message" + type: object + description: Optional message posted to the conversation before the procedure runs. Only `body` is required. + properties: + body: + type: string + description: The body of the message. + example: Starting your refund request. + author: + type: string + enum: + - user + - agent + - fin + description: The author of the message. + example: agent + required: + - body conversation_metadata: type: object description: Metadata about the conversation. Only attributes are accepted (no history). @@ -29714,6 +30176,7 @@ paths: sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' New conversation: value: + conversation_id: escalate-1a2b3c4d5e6f7a8b intercom_conversation_id: '987654321' status: escalated schema: @@ -29721,7 +30184,7 @@ paths: properties: conversation_id: type: string - description: The external ID of the conversation. Returned when you escalate an existing conversation by `conversation_id` (echoed back). When you escalate a `user`, a new conversation is created and only `intercom_conversation_id` is returned. + description: The external ID of the conversation. When you escalate an existing conversation by `conversation_id`, this echoes the ID you sent. When you escalate a `user`, a new conversation is created and Fin generates this ID for it. example: ext-123 intercom_conversation_id: type: string @@ -29743,20 +30206,13 @@ paths: content: application/json: examples: - Neither identifier provided: - value: - type: error.list - request_id: b68959ea-6328-4f70-83cb-e7913dba1542 - errors: - - code: parameter_invalid - message: Either conversation_id or user must be provided - Conversation not found: + Not available in this API version: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: Conversation not found + - code: intercom_version_invalid + message: Requested resource is not available in current API version schema: "$ref": "#/components/schemas/error" '401': @@ -29771,8 +30227,74 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token not authorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '403': + description: Forbidden + content: + application/json: + examples: + Fin Agent API not enabled: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: api_plan_restricted + message: Fin Agent API is not enabled for your app. + Wrong credentials for the Fin Agent API: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: forbidden + message: Use your workspace's Fin Agent API key to call the Fin Agent API schema: "$ref": "#/components/schemas/error" + '422': + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + content: + application/json: + examples: + Neither identifier provided: + value: + errors: + base: Either conversation_id or user must be provided + Both identifiers provided: + value: + errors: + base: Provide either conversation_id or user, not both + Conversation not found: + value: + errors: + conversation_id: Conversation not found for the given conversation_id + User not supported on Fin for Platforms: + value: + errors: + user: user is not supported for Fin for platforms; only escalating an existing conversation with conversation_id is. + Context too long: + value: + errors: + context: context must be 10000 characters or fewer + Deprecated message field: + value: + errors: + message: message is no longer supported; provide context instead + schema: + type: object + properties: + errors: + type: object + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + example: + conversation_id: Conversation ID is required + additionalProperties: true requestBody: required: true content: @@ -29887,6 +30409,27 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + '403': + description: Forbidden + content: + application/json: + examples: + Fin Agent API not enabled: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: api_plan_restricted + message: Fin Agent API is not enabled for your app. + Wrong credentials for the Fin Agent API: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: forbidden + message: Use your workspace's Fin Agent API key to call the Fin Agent API + schema: + "$ref": "#/components/schemas/error" '422': description: | The rating could not be recorded. Common causes: no conversation exists for the given @@ -30069,13 +30612,13 @@ paths: content: application/json: examples: - Invalid request: + Not available in this API version: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: conversation_id is required + - code: intercom_version_invalid + message: Requested resource is not available in current API version schema: "$ref": "#/components/schemas/error" '401': @@ -30090,8 +30633,81 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token not authorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '403': + description: Forbidden + content: + application/json: + examples: + Fin Agent API not enabled: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: api_plan_restricted + message: Fin Agent API is not enabled for your app. + Wrong credentials for the Fin Agent API: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: forbidden + message: Use your workspace's Fin Agent API key to call the Fin Agent API + Response format not available: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: api_plan_restricted + message: The requested response format is not available. schema: "$ref": "#/components/schemas/error" + '422': + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + content: + application/json: + examples: + Conversation ID missing: + value: + errors: + conversation_id: Conversation ID is required + Conversation already exists: + value: + errors: + conversation_id: Fin session already exists for this conversation. Please use /reply to continue the conversation. + Message timestamp missing: + value: + errors: + message: timestamp_ms is required + Too many user attributes: + value: + errors: + user: Cannot update more than 10 attributes at once. Received 11 attributes. + Too many history items: + value: + errors: + conversation_metadata: Conversation history cannot contain more than 10 items + Invalid environment: + value: + errors: + environment: Invalid environment + schema: + type: object + properties: + errors: + type: object + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + example: + conversation_id: Conversation ID is required + additionalProperties: true requestBody: required: true content: @@ -30119,6 +30735,14 @@ paths: type: string description: The identifier of the environment to start the conversation in, if your Fin for Platforms workspace has environments. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment; an identifier that matches no environment is rejected. example: a1b2c3d4e5 + response_format: + type: string + enum: + - html + - markdown + default: html + description: The format of the `body` in Fin's replies. Defaults to `html`. Requesting `markdown` on a workspace where it is not enabled returns a 403 error. + example: html required: - conversation_id - message @@ -42408,13 +43032,14 @@ components: The timestamp when the message was created. Used to deduplicate messages sent within a 5 minute window. Ideally should include milliseconds for higher precision. + Send either `timestamp` or `timestamp_ms`. If you send both, `timestamp_ms` is used. example: '2025-01-24T10:01:20.000Z' timestamp_ms: type: string format: date-time description: | The timestamp when the message was created, with millisecond precision. - Only present in event responses (fin_replied). + Accepted in place of `timestamp` when you send a message, and also present in event responses (fin_replied). example: '2025-01-24T10:01:20.456Z' required: - author diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index d16c2d77..c6ebf54e 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -4496,13 +4496,13 @@ paths: content: application/json: examples: - Invalid request: + Not available in this API version: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: conversation_id is required + - code: intercom_version_invalid + message: Requested resource is not available in current API version schema: "$ref": "#/components/schemas/error" '401': @@ -4517,8 +4517,81 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token not authorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" + '403': + description: Forbidden + content: + application/json: + examples: + Fin Agent API not enabled: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: api_plan_restricted + message: Fin Agent API is not enabled for your app. + Wrong credentials for the Fin Agent API: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: forbidden + message: Use your workspace's Fin Agent API key to call the Fin Agent API + Response format not available: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: api_plan_restricted + message: The requested response format is not available. + schema: + "$ref": "#/components/schemas/error" + '422': + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + content: + application/json: + examples: + Conversation ID missing: + value: + errors: + conversation_id: Conversation ID is required + Conversation already exists: + value: + errors: + conversation_id: Fin session already exists for this conversation. Please use /reply to continue the conversation. + Message timestamp missing: + value: + errors: + message: timestamp_ms is required + Too many user attributes: + value: + errors: + user: Cannot update more than 10 attributes at once. Received 11 attributes. + Too many history items: + value: + errors: + conversation_metadata: Conversation history cannot contain more than 10 items + Invalid environment: + value: + errors: + environment: Invalid environment + schema: + type: object + properties: + errors: + type: object + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + example: + conversation_id: Conversation ID is required + additionalProperties: true requestBody: required: true content: @@ -4546,6 +4619,14 @@ paths: type: string description: The identifier of the environment to start the conversation in, if your Fin for Platforms workspace has environments. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment; an identifier that matches no environment is rejected. example: a1b2c3d4e5 + response_format: + type: string + enum: + - html + - markdown + default: html + description: The format of the `body` in Fin's replies. Defaults to `html`. Requesting `markdown` on a workspace where it is not enabled returns a 403 error. + example: html required: - conversation_id - message @@ -4694,13 +4775,13 @@ paths: content: application/json: examples: - Invalid request: + Not available in this API version: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: conversation_id is required + - code: intercom_version_invalid + message: Requested resource is not available in current API version schema: "$ref": "#/components/schemas/error" '401': @@ -4715,8 +4796,73 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token not authorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" + '403': + description: Forbidden + content: + application/json: + examples: + Fin Agent API not enabled: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: api_plan_restricted + message: Fin Agent API is not enabled for your app. + Wrong credentials for the Fin Agent API: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: forbidden + message: Use your workspace's Fin Agent API key to call the Fin Agent API + Response format not available: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: api_plan_restricted + message: The requested response format is not available. + schema: + "$ref": "#/components/schemas/error" + '422': + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + content: + application/json: + examples: + Conversation ID missing: + value: + errors: + conversation_id: Conversation ID is required + Conversation not found: + value: + errors: + conversation_id: Conversation not found for the given conversation_id + Message timestamp missing: + value: + errors: + message: timestamp_ms is required + Too many user attributes: + value: + errors: + user: Cannot update more than 10 attributes at once. Received 11 attributes. + schema: + type: object + properties: + errors: + type: object + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + example: + conversation_id: Conversation ID is required + additionalProperties: true requestBody: required: true content: @@ -4738,6 +4884,14 @@ paths: maxItems: 10 items: "$ref": "#/components/schemas/fin_agent_attachment" + response_format: + type: string + enum: + - html + - markdown + default: html + description: The format of the `body` in Fin's replies. Defaults to `html`. Requesting `markdown` on a workspace where it is not enabled returns a 403 error. + example: html required: - conversation_id - message @@ -4845,6 +4999,27 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + '403': + description: Forbidden + content: + application/json: + examples: + Fin Agent API not enabled: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: api_plan_restricted + message: Fin Agent API is not enabled for your app. + Wrong credentials for the Fin Agent API: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: forbidden + message: Use your workspace's Fin Agent API key to call the Fin Agent API + schema: + "$ref": "#/components/schemas/error" '422': description: | The rating could not be recorded. Common causes: no conversation exists for the given @@ -4939,7 +5114,7 @@ paths: The response is audience-matched to the supplied user: each live, API-triggerable procedure is checked against that user before being included, alongside the static - `reply` and `ask` actions. + `reply`, `ask`, and `escalate` actions. {% admonition type="warning" %} To request access to the Fin Agent API, go to **Settings > Integrations > Fin Agent API** in your workspace and tell us about your use case. Once access is granted, **Fin Agent API** appears under **Fin AI Agent > Deploy**. @@ -4952,22 +5127,223 @@ paths: examples: Successful response: value: - version: "2.17" - capabilities: - - type: procedure - id: '12345' - name: Reset password - description: Walk the user through resetting their password. - endpoint: /fin/procedures/12345/run - method: POST - - type: reply - description: Reply to an in-progress Fin conversation. - endpoint: /fin/reply - method: POST - - type: ask - description: Ask Fin a single, self-contained question. - endpoint: /fin/ask - method: POST + version: 2.17 + capabilities: + - name: run_procedure_reset_password_12345 + description: |- + <untrusted-content> + Walk the user through resetting their password. + </untrusted-content> + inputSchema: + type: object + properties: + conversation_id: + type: string + description: A unique external ID for the new conversation. Must not already exist for this workspace. + user: + type: object + description: The end user the action is performed for. + properties: + id: + type: string + description: The user's external ID. + name: + type: string + email: + type: string + attributes: + type: object + description: Custom user attributes (max 10). + required: + - id + message: + type: object + description: Optional trigger message posted before the procedure runs. + properties: + body: + type: string + author: + type: string + enum: + - user + - agent + - fin + required: + - body + conversation_metadata: + type: object + properties: + attributes: + type: object + required: + - conversation_id + - user + endpoint: /fin/procedures/12345/run + method: POST + - name: reply + description: Send a user reply into an existing Fin conversation and get Fin's next turn. Use this to continue any ongoing conversation — including one opened by a procedure run — whenever its status is `awaiting_user_reply`. + inputSchema: + type: object + properties: + conversation_id: + type: string + description: External ID of the existing conversation to reply to. + message: + type: object + properties: + author: + type: string + enum: + - user + - agent + - fin + body: + type: string + timestamp: + type: string + timestamp_ms: + type: string + required: + - author + - body + user: + type: object + description: The end user the action is performed for. + properties: + id: + type: string + description: The user's external ID. + name: + type: string + email: + type: string + attributes: + type: object + description: Custom user attributes (max 10). + required: + - id + attachments: + type: array + description: Optional attachments to include with the message. + response_format: + type: string + enum: + - html + - markdown + description: Response body format. Defaults to html. + required: + - conversation_id + - message + - user + endpoint: /fin/reply + method: POST + - name: ask + description: Ask Fin a single question and get one informational answer. Fin never escalates, disambiguates, or asks follow-up questions. Use for one-shot informational lookups. + inputSchema: + type: object + properties: + conversation_id: + type: string + description: External ID for the conversation. + message: + type: object + properties: + author: + type: string + enum: + - user + - agent + - fin + body: + type: string + timestamp: + type: string + timestamp_ms: + type: string + required: + - author + - body + user: + type: object + description: The end user the action is performed for. + properties: + id: + type: string + description: The user's external ID. + name: + type: string + email: + type: string + attributes: + type: object + description: Custom user attributes (max 10). + required: + - id + conversation_metadata: + type: object + properties: + history: + type: array + attributes: + type: object + attachments: + type: array + description: Optional attachments to include with the message. + response_format: + type: string + enum: + - html + - markdown + description: Response body format. Defaults to html. + required: + - conversation_id + - message + - user + endpoint: /fin/ask + method: POST + - name: escalate + description: Hand off to a human team. Summarises the conversation into a new human-facing support conversation routed to the inbox, leaving this one untouched, and notifies you when the handoff completes. Use when the user asks for a human or when you decide Fin can't resolve the request. + inputSchema: + type: object + description: Escalate an existing conversation (conversation_id) or a new one (user) — not both. + oneOf: + - properties: + conversation_id: + type: string + description: External ID of the conversation to escalate. + context: + type: string + maxLength: 10000 + description: Background for the teammate who picks up the handoff. Never shown to the end user. + required: + - conversation_id + additionalProperties: false + - properties: + user: + type: object + description: The end user the action is performed for. + properties: + id: + type: string + description: The user's external ID. + name: + type: string + email: + type: string + attributes: + type: object + description: Custom user attributes (max 10). + required: + - id + context: + type: string + maxLength: 10000 + description: Background for the teammate who picks up the handoff. Never shown to the end user. + required: + - user + additionalProperties: false + endpoint: /fin/escalate + method: POST schema: type: object properties: @@ -4977,26 +5353,23 @@ paths: example: "2.17" capabilities: type: array - description: The list of capabilities available to this user. + description: The list of capabilities available to this user, as tool definitions. items: type: object properties: - type: - type: string - description: The kind of capability — `procedure` for a runnable procedure, or a static action such as `reply`, `ask`, or `escalate`. - example: procedure - id: - type: string - description: The procedure ID. Present only when `type` is `procedure`. - example: '12345' name: type: string - description: The procedure name. Present only when `type` is `procedure`. - example: Reset password + description: The capability name. Procedures are named `run_procedure_<title>_<id>`; the static actions are named `reply`, `ask`, and `escalate`. + example: run_procedure_reset_password_12345 description: type: string - description: A human-readable description of the capability. - example: Walk the user through resetting their password. + nullable: true + description: A description of the capability. For a procedure, the text is wrapped in `<untrusted-content>` tags, and is null when the procedure has no description. + example: Reply to an in-progress Fin conversation. + inputSchema: + type: object + description: A JSON Schema describing the request body to send to the capability's endpoint. + additionalProperties: true endpoint: type: string description: The endpoint path to call to use this capability. @@ -5005,18 +5378,20 @@ paths: type: string description: The HTTP method to use. example: POST + errors: + "$ref": "#/components/schemas/fin_agent_attribute_errors" '400': description: Bad Request content: application/json: examples: - Too many attributes: + Not available in this API version: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: Cannot update more than 10 attributes at once. + - code: intercom_version_invalid + message: Requested resource is not available in current API version schema: "$ref": "#/components/schemas/error" '401': @@ -5031,8 +5406,54 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token not authorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" + '403': + description: Forbidden + content: + application/json: + examples: + Fin Agent API not enabled: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: api_plan_restricted + message: Fin Agent API is not enabled for your app. + Wrong credentials for the Fin Agent API: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: forbidden + message: Use your workspace's Fin Agent API key to call the Fin Agent API + schema: + "$ref": "#/components/schemas/error" + '422': + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + content: + application/json: + examples: + Too many user attributes: + value: + errors: + user: Cannot update more than 10 attributes at once. Received 11 attributes. + schema: + type: object + properties: + errors: + type: object + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + example: + conversation_id: Conversation ID is required + additionalProperties: true requestBody: required: true content: @@ -5145,43 +5566,102 @@ paths: content: application/json: examples: - Conversation ID missing: + Not available in this API version: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: External Conversation ID is required - User ID missing: + - code: intercom_version_invalid + message: Requested resource is not available in current API version + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: User ID is required - Too many history items: + - code: unauthorized + message: Access Token Invalid + Token not authorized: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: Conversation history cannot contain more than 10 items + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" - '401': - description: Unauthorized + '403': + description: Forbidden content: application/json: examples: - Unauthorized: + Fin Agent API not enabled: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: unauthorized - message: Access Token Invalid + - code: api_plan_restricted + message: Fin Agent API is not enabled for your app. + Wrong credentials for the Fin Agent API: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: forbidden + message: Use your workspace's Fin Agent API key to call the Fin Agent API + Response format not available: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: api_plan_restricted + message: The requested response format is not available. schema: "$ref": "#/components/schemas/error" + '422': + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + content: + application/json: + examples: + Conversation ID missing: + value: + errors: + conversation_id: Conversation ID is required + Conversation already exists: + value: + errors: + conversation_id: Fin session already exists for this conversation. Please use /reply to continue the conversation. + Message timestamp missing: + value: + errors: + message: timestamp_ms is required + Too many user attributes: + value: + errors: + user: Cannot update more than 10 attributes at once. Received 11 attributes. + Too many history items: + value: + errors: + conversation_metadata: Conversation history cannot contain more than 10 items + Invalid environment: + value: + errors: + environment: Invalid environment + schema: + type: object + properties: + errors: + type: object + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + example: + conversation_id: Conversation ID is required + additionalProperties: true requestBody: required: true content: @@ -5209,6 +5689,14 @@ paths: type: string description: The identifier of the environment to start the conversation in, if your Fin for Platforms workspace has environments. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment; an identifier that matches no environment is rejected. example: a1b2c3d4e5 + response_format: + type: string + enum: + - html + - markdown + default: html + description: The format of the `body` in Fin's replies. Defaults to `html`. Requesting `markdown` on a workspace where it is not enabled returns a 403 error. + example: html required: - conversation_id - message @@ -5350,57 +5838,103 @@ paths: content: application/json: examples: - Procedure not found: + Not available in this API version: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: Procedure not found - Procedure not live: + - code: intercom_version_invalid + message: Requested resource is not available in current API version + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: Procedure is not live - Procedure has no API trigger: + - code: unauthorized + message: Access Token Invalid + Token not authorized: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: Procedure does not have an API trigger - No Fin profile: + - code: token_unauthorized + message: Not authorized to access resource + schema: + "$ref": "#/components/schemas/error" + '403': + description: Forbidden + content: + application/json: + examples: + Fin Agent API not enabled: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: No Fin profile is configured to handle this conversation. Configure a Fin profile and retry. - Conversation already exists: + - code: api_plan_restricted + message: Fin Agent API is not enabled for your app. + Wrong credentials for the Fin Agent API: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: Fin session already exists for this conversation. Please use /reply to continue the conversation. + - code: forbidden + message: Use your workspace's Fin Agent API key to call the Fin Agent API schema: "$ref": "#/components/schemas/error" - '401': - description: Unauthorized + '422': + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. content: application/json: examples: - Unauthorized: + Conversation ID missing: value: - type: error.list - request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: unauthorized - message: Access Token Invalid + conversation_id: Conversation ID is required + Procedure not found: + value: + errors: + procedure_id: Procedure not found + Procedure not live: + value: + errors: + procedure_id: Procedure is not live + Procedure not available on the Fin Agent API channel: + value: + errors: + procedure_id: Procedure is not available on the Fin Agent API channel + Procedure not available for this user: + value: + errors: + procedure_id: Procedure is not available for this user + No Fin profile: + value: + errors: + base: No Fin profile is configured to handle this conversation. Configure a Fin profile and retry. + Conversation already exists: + value: + errors: + conversation_id: Fin session already exists for this conversation. Please use /reply to continue the conversation. + Invalid environment: + value: + errors: + environment: Invalid environment schema: - "$ref": "#/components/schemas/error" + type: object + properties: + errors: + type: object + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + example: + conversation_id: Conversation ID is required + additionalProperties: true requestBody: required: true content: @@ -5415,7 +5949,23 @@ paths: user: "$ref": "#/components/schemas/fin_agent_user" message: - "$ref": "#/components/schemas/fin_agent_message" + type: object + description: Optional message posted to the conversation before the procedure runs. Only `body` is required. + properties: + body: + type: string + description: The body of the message. + example: Starting your refund request. + author: + type: string + enum: + - user + - agent + - fin + description: The author of the message. + example: agent + required: + - body conversation_metadata: type: object description: Metadata about the conversation. Only attributes are accepted (no history). @@ -5518,6 +6068,7 @@ paths: sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' New conversation: value: + conversation_id: escalate-1a2b3c4d5e6f7a8b intercom_conversation_id: '987654321' status: escalated schema: @@ -5525,7 +6076,7 @@ paths: properties: conversation_id: type: string - description: The external ID of the conversation. Returned when you escalate an existing conversation by `conversation_id` (echoed back). When you escalate a `user`, a new conversation is created and only `intercom_conversation_id` is returned. + description: The external ID of the conversation. When you escalate an existing conversation by `conversation_id`, this echoes the ID you sent. When you escalate a `user`, a new conversation is created and Fin generates this ID for it. example: ext-123 intercom_conversation_id: type: string @@ -5547,20 +6098,13 @@ paths: content: application/json: examples: - Neither identifier provided: + Not available in this API version: value: type: error.list request_id: b68959ea-6328-4f70-83cb-e7913dba1542 errors: - - code: parameter_invalid - message: Either conversation_id or user must be provided - Conversation not found: - value: - type: error.list - request_id: b68959ea-6328-4f70-83cb-e7913dba1542 - errors: - - code: parameter_invalid - message: Conversation not found + - code: intercom_version_invalid + message: Requested resource is not available in current API version schema: "$ref": "#/components/schemas/error" '401': @@ -5575,8 +6119,74 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token not authorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: token_unauthorized + message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" + '403': + description: Forbidden + content: + application/json: + examples: + Fin Agent API not enabled: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: api_plan_restricted + message: Fin Agent API is not enabled for your app. + Wrong credentials for the Fin Agent API: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: forbidden + message: Use your workspace's Fin Agent API key to call the Fin Agent API + schema: + "$ref": "#/components/schemas/error" + '422': + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + content: + application/json: + examples: + Neither identifier provided: + value: + errors: + base: Either conversation_id or user must be provided + Both identifiers provided: + value: + errors: + base: Provide either conversation_id or user, not both + Conversation not found: + value: + errors: + conversation_id: Conversation not found for the given conversation_id + User not supported on Fin for Platforms: + value: + errors: + user: user is not supported for Fin for platforms; only escalating an existing conversation with conversation_id is. + Context too long: + value: + errors: + context: context must be 10000 characters or fewer + Deprecated message field: + value: + errors: + message: message is no longer supported; provide context instead + schema: + type: object + properties: + errors: + type: object + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + example: + conversation_id: Conversation ID is required + additionalProperties: true requestBody: required: true content: @@ -26085,6 +26695,20 @@ paths: embedded_rules: [] schema: "$ref": "#/components/schemas/workflow_export" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" '404': description: Workflow not found content: @@ -26096,21 +26720,21 @@ paths: request_id: b3c8c472-8478-4f10-a29e-a23dbf921c46 errors: - code: not_found - message: Workflow not found + message: 'Workflow not found with id: 12345' schema: "$ref": "#/components/schemas/error" - '403': - description: Workflow export is not available for this app + '503': + description: Workflow export is currently disabled content: application/json: examples: - Feature not available: + Workflow export disabled: value: type: error.list request_id: d92f7e84-5c31-4a2b-b8e6-9f4c3d2a1b0e errors: - - code: api_plan_restricted - message: Workflow export is not available for this app + - code: service_unavailable + message: Workflow export is currently disabled schema: "$ref": "#/components/schemas/error" components: @@ -37248,18 +37872,18 @@ components: The timestamp when the message was created. Used to deduplicate messages sent within a 5 minute window. Ideally should include milliseconds for higher precision. + Send either `timestamp` or `timestamp_ms`. If you send both, `timestamp_ms` is used. example: '2025-01-24T10:01:20.000Z' timestamp_ms: type: string format: date-time description: | The timestamp when the message was created, with millisecond precision. - Only present in webhook event responses (fin_replied). + Accepted in place of `timestamp` when you send a message, and also present in webhook event responses (fin_replied). example: '2025-01-24T10:01:20.456Z' required: - author - body - - timestamp fin_agent_user: title: Fin Agent User type: object From d8ea9c97b57b96f7517d8a73407b320768d62814 Mon Sep 17 00:00:00 2001 From: Cathal Ging <cathal.ging@intercom.io> Date: Wed, 21 Oct 2026 13:20:00 +0100 Subject: [PATCH 4/8] Correct Fin, AI Content and data connector docs details Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> --- descriptions/0/api.intercom.io.yaml | 164 +++++++++++++----------- descriptions/2.17/api.intercom.io.yaml | 167 ++++++++++++++----------- 2 files changed, 190 insertions(+), 141 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index fcf007f7..d5bb399d 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -804,7 +804,6 @@ paths: in: query schema: type: integer - minimum: 1 maximum: 150 default: 50 description: The number of results to return per page. Maximum 150. @@ -815,7 +814,7 @@ paths: description: | You can retrieve a list of all content import sources for a workspace. - Requires the `read_write_ai_content` OAuth scope. + OAuth tokens must have the `read_write_ai_content` scope. responses: '200': description: successful @@ -916,7 +915,7 @@ paths: description: | You can create a new content import source by sending a POST request to this endpoint. - Requires the `read_write_ai_content` OAuth scope. + OAuth tokens must have the `read_write_ai_content` scope. responses: '200': description: successful @@ -1018,7 +1017,7 @@ paths: description: | You can delete a content import source by making a DELETE request this endpoint. This will also delete all external pages that were imported from this source. - Requires the `read_write_ai_content` OAuth scope. + OAuth tokens must have the `read_write_ai_content` scope. parameters: - name: Intercom-Version in: header @@ -1070,7 +1069,7 @@ paths: description: | You can retrieve a content import source. - Requires the `read_write_ai_content` OAuth scope. + OAuth tokens must have the `read_write_ai_content` scope. parameters: - name: Intercom-Version in: header @@ -1145,7 +1144,7 @@ paths: description: | You can update an existing content import source. - Requires the `read_write_ai_content` OAuth scope. + OAuth tokens must have the `read_write_ai_content` scope. responses: '200': description: successful @@ -1253,13 +1252,12 @@ paths: type: integer minimum: 1 default: 1 - description: The page of results to fetch. Defaults to the first page. + description: The page of results to fetch. Defaults to the first page. Pages above 5001 are not supported. example: 1 - name: per_page in: query schema: type: integer - minimum: 1 maximum: 150 default: 50 description: The number of results to return per page. Maximum 150. @@ -1270,7 +1268,7 @@ paths: description: | You can retrieve a list of all external pages for a workspace. - Requires the `read_write_ai_content` OAuth scope. + OAuth tokens must have the `read_write_ai_content` scope. responses: '200': description: successful @@ -1401,7 +1399,7 @@ paths: description: | You can create a new external page by sending a POST request to this endpoint. If an external page already exists with the specified source_id and external_id, it will be updated instead. - Requires the `read_write_ai_content` OAuth scope. + OAuth tokens must have the `read_write_ai_content` scope. responses: '200': description: successful @@ -1534,7 +1532,7 @@ paths: description: | Sending a DELETE request for an external page will remove it from the content library UI and from being used for AI answers. - Requires the `read_write_ai_content` OAuth scope. + OAuth tokens must have the `read_write_ai_content` scope. responses: '200': description: successful @@ -1614,7 +1612,7 @@ paths: description: | You can retrieve an external page. - Requires the `read_write_ai_content` OAuth scope. + OAuth tokens must have the `read_write_ai_content` scope. responses: '200': description: successful @@ -1694,7 +1692,7 @@ paths: description: | You can update an existing external page (if it was created via the API). - Requires the `read_write_ai_content` OAuth scope. + OAuth tokens must have the `read_write_ai_content` scope. responses: '200': description: successful @@ -19471,7 +19469,7 @@ paths: description: | Returns a paginated list of all data connectors for the workspace, ordered by most recently updated first. Data connectors allow workflows and AI agents to make HTTP requests to external APIs. - Requires the `read_workflow_connector_execution_result` or `read_write_data_connectors` OAuth scope. + OAuth tokens must have the `read_workflow_connector_execution_result` or `read_write_data_connectors` scope. responses: '200': description: successful @@ -19497,7 +19495,7 @@ paths: execution_results_url: "/data_connectors/12345/execution_results" pages: type: pages - per_page: 20 + per_page: 1 next: starting_after: WzE3Njg5MTg5MzUuMCwxMjM0NSxudWxsXQ== schema: @@ -19550,7 +19548,7 @@ paths: description: | Create a new data connector. The connector is created in `draft` state. Configure its URL, headers, data inputs, and other settings, then set it to `live` when ready. - Requires the `read_write_data_connectors` OAuth scope. + OAuth tokens must have the `read_write_data_connectors` scope. responses: '201': description: Data connector created @@ -19563,6 +19561,7 @@ paths: id: '125' name: Get Order Status description: Looks up order status from an external service + internal_description: Looks up order status from an external service state: draft url: "https://api.example.com/orders/{{order_id}}/status" headers: @@ -19762,7 +19761,7 @@ paths: The response includes configuration, data inputs, response fields, and object mappings. - Requires the `read_workflow_connector_execution_result` or `read_write_data_connectors` OAuth scope. + OAuth tokens must have the `read_workflow_connector_execution_result` or `read_write_data_connectors` scope. responses: '200': description: Data connector found @@ -19792,6 +19791,7 @@ paths: return transform(inputs['data']) language: python + client_function_timeout_ms: 30000 data_inputs: - name: conversation_id type: string @@ -19808,6 +19808,7 @@ paths: customer_authentication: false bypass_authentication: false enforce_auth: true + validate_missing_attributes: true created_by_admin_id: '456' updated_by_admin_id: '456' created_at: '2025-11-15T09:30:00Z' @@ -19884,7 +19885,7 @@ paths: description: | Delete an existing data connector. The connector must be in `draft` state and must not be in use by any workflows or AI agents. - Requires the `read_write_data_connectors` OAuth scope. + OAuth tokens must have the `read_write_data_connectors` scope. responses: '200': description: Data connector deleted @@ -19974,7 +19975,7 @@ paths: description: | Update an existing data connector. Only provided fields are changed. Set `state` to `live` or `draft` to change the connector's state. - Requires the `read_write_data_connectors` OAuth scope. + OAuth tokens must have the `read_write_data_connectors` scope. requestBody: content: application/json: @@ -20032,6 +20033,8 @@ paths: - leads execution_type: server_side configuration_response_type: test_response_type + data_transformation_type: full_access + client_function_timeout_ms: 30000 data_inputs: - name: conversation_id type: string @@ -20052,6 +20055,27 @@ paths: execution_results_url: "/data_connectors/12345/execution_results" schema: "$ref": "#/components/schemas/data_connector_detail" + '400': + description: Invalid parameter + content: + application/json: + examples: + Unpermitted property in headers: + value: + type: error.list + request_id: b4a45e2c-7a8d-4f3e-9c1a-2d5e8f7a6b3c + errors: + - code: parameter_invalid + message: "found unpermitted parameter: :description" + Audiences is not an array: + value: + type: error.list + request_id: f1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b + errors: + - code: parameter_invalid + message: "found unpermitted parameter: :audiences" + schema: + "$ref": "#/components/schemas/error" '404': description: Data connector not found content: @@ -20260,7 +20284,7 @@ paths: Request/response bodies are excluded by default. Use `include_bodies=true` to include them. - Requires the `read_workflow_connector_execution_result` or `read_write_data_connectors` OAuth scope. + OAuth tokens must have the `read_workflow_connector_execution_result` or `read_write_data_connectors` scope. responses: '200': description: successful @@ -20294,7 +20318,7 @@ paths: created_at: '2026-02-10T17:45:15Z' pages: type: pages - per_page: 10 + per_page: 2 next: starting_after: WzE3NzA3NDU1MTUuMCw5OTAwMCxudWxsXQ== schema: @@ -20389,9 +20413,9 @@ paths: operationId: showDataConnectorExecutionResult description: | Retrieve details for a specific data connector execution result. - Always includes request/response bodies and the sanitised request URL. + Includes the request/response bodies and sanitised request URL when they were recorded. - Requires the `read_workflow_connector_execution_result` or `read_write_data_connectors` OAuth scope. + OAuth tokens must have the `read_workflow_connector_execution_result` or `read_write_data_connectors` scope. responses: '200': description: successful @@ -29231,13 +29255,13 @@ paths: properties: name: type: string - description: The capability name. Procedures are named `run_procedure_<title>_<id>`; the static actions are named `reply`, `ask`, and `escalate`. + description: The capability name. Procedures are named `run_procedure_<title_slug>_<id>`, or `run_procedure_<id>` when the title is blank; the static actions are named `reply`, `ask`, and `escalate`. example: run_procedure_reset_password_12345 description: type: string nullable: true description: A description of the capability. For a procedure, the text is wrapped in `<untrusted-content>` tags, and is null when the procedure has no description. - example: Reply to an in-progress Fin conversation. + example: Send a user reply into an existing Fin conversation and get Fin's next turn. Use this to continue any ongoing conversation — including one opened by a procedure run — whenever its status is `awaiting_user_reply`. inputSchema: type: object description: A JSON Schema describing the request body to send to the capability's endpoint. @@ -29309,7 +29333,7 @@ paths: schema: "$ref": "#/components/schemas/error" '422': - description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. Values are usually strings. When a required field inside an object, such as `user.id`, is missing or invalid, the error is a nested object keyed by the inner field. content: application/json: examples: @@ -29322,9 +29346,9 @@ paths: properties: errors: type: object - description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. example: - conversation_id: Conversation ID is required + user: Cannot update more than 10 attributes at once. Received 11 attributes. additionalProperties: true requestBody: required: true @@ -29497,7 +29521,7 @@ paths: schema: "$ref": "#/components/schemas/error" '422': - description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. Values are usually strings. When a required field inside an object, such as `user.id`, is missing or invalid, the error is a nested object keyed by the inner field. content: application/json: examples: @@ -29521,7 +29545,7 @@ paths: value: errors: conversation_metadata: Conversation history cannot contain more than 10 items - Invalid environment: + Invalid environment on a Fin for Platforms workspace: value: errors: environment: Invalid environment @@ -29530,7 +29554,7 @@ paths: properties: errors: type: object - description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. example: conversation_id: Conversation ID is required additionalProperties: true @@ -29559,7 +29583,7 @@ paths: "$ref": "#/components/schemas/fin_agent_attachment" environment: type: string - description: The identifier of the environment to start the conversation in, if your Fin for Platforms workspace has environments. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment; an identifier that matches no environment is rejected. + description: The identifier of the environment to start the conversation in. Only Fin for Platforms workspaces with environments use it; other workspaces ignore it. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment. On a Fin for Platforms workspace, an identifier that matches no environment returns a 422 error. example: a1b2c3d4e5 response_format: type: string @@ -29753,7 +29777,7 @@ paths: schema: "$ref": "#/components/schemas/error" '422': - description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. Values are usually strings. When a required field inside an object, such as `user.id`, is missing or invalid, the error is a nested object keyed by the inner field. content: application/json: examples: @@ -29778,7 +29802,7 @@ paths: properties: errors: type: object - description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. example: conversation_id: Conversation ID is required additionalProperties: true @@ -29998,7 +30022,7 @@ paths: schema: "$ref": "#/components/schemas/error" '422': - description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. Values are usually strings. When a required field inside an object, such as `user.id`, is missing or invalid, the error is a nested object keyed by the inner field. content: application/json: examples: @@ -30030,7 +30054,7 @@ paths: value: errors: conversation_id: Fin session already exists for this conversation. Please use /reply to continue the conversation. - Invalid environment: + Invalid environment on a Fin for Platforms workspace: value: errors: environment: Invalid environment @@ -30039,7 +30063,7 @@ paths: properties: errors: type: object - description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. example: conversation_id: Conversation ID is required additionalProperties: true @@ -30070,7 +30094,7 @@ paths: - user - agent - fin - description: The author of the message. + description: Accepted but has no effect. The trigger message is always posted as an operator message. example: agent required: - body @@ -30088,7 +30112,7 @@ paths: order_id: '98765' environment: type: string - description: The identifier of the environment to start the conversation in, if your Fin for Platforms workspace has environments. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment; an identifier that matches no environment is rejected. + description: The identifier of the environment to start the conversation in. Only Fin for Platforms workspaces with environments use it; other workspaces ignore it. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment. On a Fin for Platforms workspace, an identifier that matches no environment returns a 422 error. example: a1b2c3d4e5 required: - conversation_id @@ -30258,7 +30282,7 @@ paths: schema: "$ref": "#/components/schemas/error" '422': - description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. Values are usually strings. When a required field inside an object, such as `user.id`, is missing or invalid, the error is a nested object keyed by the inner field. content: application/json: examples: @@ -30291,9 +30315,9 @@ paths: properties: errors: type: object - description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. example: - conversation_id: Conversation ID is required + conversation_id: Conversation not found for the given conversation_id additionalProperties: true requestBody: required: true @@ -30671,7 +30695,7 @@ paths: schema: "$ref": "#/components/schemas/error" '422': - description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. Values are usually strings. When a required field inside an object, such as `user.id`, is missing or invalid, the error is a nested object keyed by the inner field. content: application/json: examples: @@ -30695,7 +30719,7 @@ paths: value: errors: conversation_metadata: Conversation history cannot contain more than 10 items - Invalid environment: + Invalid environment on a Fin for Platforms workspace: value: errors: environment: Invalid environment @@ -30704,7 +30728,7 @@ paths: properties: errors: type: object - description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. example: conversation_id: Conversation ID is required additionalProperties: true @@ -30733,7 +30757,7 @@ paths: "$ref": "#/components/schemas/fin_agent_conversation_metadata" environment: type: string - description: The identifier of the environment to start the conversation in, if your Fin for Platforms workspace has environments. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment; an identifier that matches no environment is rejected. + description: The identifier of the environment to start the conversation in. Only Fin for Platforms workspaces with environments use it; other workspaces ignore it. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment. On a Fin for Platforms workspace, an identifier that matches no environment returns a 422 error. example: a1b2c3d4e5 response_format: type: string @@ -38393,7 +38417,7 @@ components: url: type: string description: The URL of the content import source. It must be an http or https - URL on a publicly reachable domain. + URL whose host is a valid public domain name. example: https://help.example.com audience_ids: nullable: true @@ -40376,7 +40400,7 @@ components: example: Looks up order status from an external service internal_description: type: string - description: The internal description of the data connector. + description: The internal description of the data connector. If omitted while `description` is sent, it is set to the same value as `description`. http_method: type: string description: The HTTP method used when calling the external API. @@ -40472,7 +40496,7 @@ components: example: false enforce_auth: type: boolean - description: Whether authentication is enforced for this connector. + description: Whether authentication is enforced. On workspaces where this is supported, it takes precedence over `customer_authentication` and `bypass_authentication` when sent together, and setting it to false disables OTP. validate_missing_attributes: type: boolean description: Whether to validate that all required data inputs have values before executing. @@ -40548,7 +40572,7 @@ components: example: Updated description internal_description: type: string - description: The internal description of the data connector. + description: The internal description of the data connector. If omitted while `description` is sent, it is set to the same value as `description`. state: type: string description: The desired state of the connector. @@ -40650,7 +40674,7 @@ components: example: false enforce_auth: type: boolean - description: Whether authentication is enforced for this connector. + description: Whether authentication is enforced. On workspaces where this is supported, it takes precedence over `customer_authentication` and `bypass_authentication` when sent together, and setting it to false disables OTP. validate_missing_attributes: type: boolean description: Whether to validate missing attributes before execution. @@ -40791,7 +40815,7 @@ components: x-tags: - Data Connectors description: | - Full detail view of a data connector, returned by `GET /data_connectors/{id}`. + Full detail view of a data connector, returned by `GET /data_connectors/{id}`, `POST /data_connectors`, and `PATCH /data_connectors/{id}`. Includes configuration, data inputs, response fields, and object mappings. properties: type: @@ -40877,7 +40901,6 @@ components: - leads execution_type: type: string - nullable: true description: How the connector executes. enum: - server_side @@ -40885,7 +40908,6 @@ components: example: server_side configuration_response_type: type: string - nullable: true description: The expected response format from the connector. enum: - test_response_type @@ -40893,7 +40915,6 @@ components: example: test_response_type data_transformation_type: type: string - nullable: true description: The type of data transformation applied to the response. enum: - full_access @@ -40901,10 +40922,9 @@ components: - code_block_transformation transform_code_block: type: object - nullable: true description: | - The code block used to transform the connector's response when `data_transformation_type` is - `code_block_transformation`. Omitted if the connector has no transform code block configured. + The code block used to transform the connector's response. Present only when `data_transformation_type` is + `code_block_transformation` and a code block exists; otherwise omitted. example: code: | def transform(response): @@ -40915,7 +40935,7 @@ components: properties: code: type: string - description: The source code of the transform code block. The API response body is available as `inputs['data']`, and the code must end with a top-level `return` of the transformed value. + description: The source code of the transform code block. The API response body is available as `inputs['data']`. example: | def transform(response): return {"status": response["order_status"]} @@ -41139,7 +41159,7 @@ components: error_message: type: string nullable: true - description: A human-readable error message. Query parameters, userinfo, and fragments in URLs are redacted. + description: A human-readable error message. Only URLs inside the message are redacted (query parameters, userinfo, and fragments); the rest of the message is returned as is. example: Connection refused execution_time_ms: type: integer @@ -41180,7 +41200,7 @@ components: request_url: type: string nullable: true - description: The request URL. Query parameters, userinfo, and fragments are redacted. + description: The request URL. Query parameters, userinfo, and fragments are redacted. For some hosts that put credentials in the path, the path is removed too. A suffix such as ` [query params redacted]` or ` [credentials redacted]` is appended when anything is redacted, and a URL that cannot be parsed becomes `[invalid URL redacted]`. example: https://api.example.com/webhook request_body: type: string @@ -42938,7 +42958,9 @@ components: source. Must be unique for the source. example: '5678' tags: - "$ref": "#/components/schemas/tags" + description: The tags applied to the external page. + allOf: + - "$ref": "#/components/schemas/tags" created_at: type: integer format: date-time @@ -43016,14 +43038,14 @@ components: - user - agent - fin - description: The author that created the message. + description: The author that created the message. In `conversation_metadata.history`, only `user` and `agent` are accepted. example: user body: type: string description: | The body of the message. Accepts both plain text and HTML format. - When sending a message to Fin, this should contain the user's message. - Fin's response will be returned as HTML. + For the message you send to Fin, this is the user's message. For an `agent` item in `conversation_metadata.history`, it is the agent's message. + Fin's response is returned in the format set by `response_format` (HTML by default). example: How can I see my account details? timestamp: type: string @@ -43032,14 +43054,15 @@ components: The timestamp when the message was created. Used to deduplicate messages sent within a 5 minute window. Ideally should include milliseconds for higher precision. - Send either `timestamp` or `timestamp_ms`. If you send both, `timestamp_ms` is used. + Send `timestamp` or `timestamp_ms`; at least one is required. If you send both, `timestamp_ms` is used. + On the top-level `message`, sending neither fails with a 422 error (`message: timestamp_ms is required`). In `conversation_metadata.history`, an item with neither causes the whole history to be ignored. example: '2025-01-24T10:01:20.000Z' timestamp_ms: type: string format: date-time description: | The timestamp when the message was created, with millisecond precision. - Accepted in place of `timestamp` when you send a message, and also present in event responses (fin_replied). + Accepted in place of `timestamp` when you send a message, and also present in event responses (fin_replied). At least one of `timestamp` or `timestamp_ms` is required. example: '2025-01-24T10:01:20.456Z' required: - author @@ -43128,6 +43151,7 @@ components: An array of previous messages in the conversation before Fin is initialized. This data provides context to Fin and helps generate a better answer. Limit to the last 10 messages. + Only `user` and `agent` authors are accepted. If any item is invalid, for example it has no `timestamp` or `timestamp_ms`, or has another author, the whole history is ignored. maxItems: 10 items: "$ref": "#/components/schemas/fin_agent_message" @@ -46076,12 +46100,12 @@ components: type: integer format: date-time nullable: true - description: The time when the tag was applied to the object. Only present when the tag is returned as part of a tagging operation on a contact, conversation, ticket, article, internal article, or content snippet. + description: The time when the tag was applied to the object. Only present when the tag is returned as part of a tagging operation on a contact, conversation, ticket, article, internal article, or content snippet, or when it is returned as part of an external page. example: 1663597223 applied_by: type: object nullable: true - description: The admin who applied the tag. Only present when the tag is returned as part of a tagging operation on a contact, conversation, ticket, article, internal article, or content snippet. + description: The admin who applied the tag. Only present when the tag is returned as part of a tagging operation on a contact, conversation, ticket, article, internal article, or content snippet, or when it is returned as part of an external page. allOf: - "$ref": "#/components/schemas/reference" tag_basic: @@ -47738,7 +47762,7 @@ components: url: type: string description: The URL of the content import source. It must be an http or https - URL on a publicly reachable domain. This may only be different from the + URL whose host is a valid public domain name. This may only be different from the existing value if the sync behavior is API. example: https://help.example.com audience_ids: diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index c6ebf54e..11f10ef0 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -1531,7 +1531,6 @@ paths: in: query schema: type: integer - minimum: 1 maximum: 150 default: 50 description: The number of results to return per page. Maximum 150. @@ -1542,7 +1541,7 @@ paths: description: | You can retrieve a list of all content import sources for a workspace. - Requires the `read_write_ai_content` OAuth scope. + OAuth tokens must have the `read_write_ai_content` scope. responses: '200': description: successful @@ -1643,7 +1642,7 @@ paths: description: | You can create a new content import source by sending a POST request to this endpoint. - Requires the `read_write_ai_content` OAuth scope. + OAuth tokens must have the `read_write_ai_content` scope. responses: '200': description: successful @@ -1745,7 +1744,7 @@ paths: description: | You can delete a content import source by making a DELETE request this endpoint. This will also delete all external pages that were imported from this source. - Requires the `read_write_ai_content` OAuth scope. + OAuth tokens must have the `read_write_ai_content` scope. parameters: - name: Intercom-Version in: header @@ -1797,7 +1796,7 @@ paths: description: | You can retrieve a content import source. - Requires the `read_write_ai_content` OAuth scope. + OAuth tokens must have the `read_write_ai_content` scope. parameters: - name: Intercom-Version in: header @@ -1872,7 +1871,7 @@ paths: description: | You can update an existing content import source. - Requires the `read_write_ai_content` OAuth scope. + OAuth tokens must have the `read_write_ai_content` scope. responses: '200': description: successful @@ -1980,13 +1979,12 @@ paths: type: integer minimum: 1 default: 1 - description: The page of results to fetch. Defaults to the first page. + description: The page of results to fetch. Defaults to the first page. Pages above 5001 are not supported. example: 1 - name: per_page in: query schema: type: integer - minimum: 1 maximum: 150 default: 50 description: The number of results to return per page. Maximum 150. @@ -1997,7 +1995,7 @@ paths: description: | You can retrieve a list of all external pages for a workspace. - Requires the `read_write_ai_content` OAuth scope. + OAuth tokens must have the `read_write_ai_content` scope. responses: '200': description: successful @@ -2128,7 +2126,7 @@ paths: description: | You can create a new external page by sending a POST request to this endpoint. If an external page already exists with the specified source_id and external_id, it will be updated instead. - Requires the `read_write_ai_content` OAuth scope. + OAuth tokens must have the `read_write_ai_content` scope. responses: '200': description: successful @@ -2269,7 +2267,7 @@ paths: description: | Sending a DELETE request for an external page will remove it from the content library UI and from being used for AI answers. - Requires the `read_write_ai_content` OAuth scope. + OAuth tokens must have the `read_write_ai_content` scope. responses: '200': description: successful @@ -2347,7 +2345,7 @@ paths: description: | You can retrieve an external page. - Requires the `read_write_ai_content` OAuth scope. + OAuth tokens must have the `read_write_ai_content` scope. responses: '200': description: successful @@ -2425,7 +2423,7 @@ paths: description: | You can update an existing external page (if it was created via the API). - Requires the `read_write_ai_content` OAuth scope. + OAuth tokens must have the `read_write_ai_content` scope. responses: '200': description: successful @@ -4555,7 +4553,7 @@ paths: schema: "$ref": "#/components/schemas/error" '422': - description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. Values are usually strings. When a required field inside an object, such as `user.id`, is missing or invalid, the error is a nested object keyed by the inner field. content: application/json: examples: @@ -4579,7 +4577,7 @@ paths: value: errors: conversation_metadata: Conversation history cannot contain more than 10 items - Invalid environment: + Invalid environment on a Fin for Platforms workspace: value: errors: environment: Invalid environment @@ -4588,7 +4586,7 @@ paths: properties: errors: type: object - description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. example: conversation_id: Conversation ID is required additionalProperties: true @@ -4617,7 +4615,7 @@ paths: "$ref": "#/components/schemas/fin_agent_conversation_metadata" environment: type: string - description: The identifier of the environment to start the conversation in, if your Fin for Platforms workspace has environments. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment; an identifier that matches no environment is rejected. + description: The identifier of the environment to start the conversation in. Only Fin for Platforms workspaces with environments use it; other workspaces ignore it. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment. On a Fin for Platforms workspace, an identifier that matches no environment returns a 422 error. example: a1b2c3d4e5 response_format: type: string @@ -4834,7 +4832,7 @@ paths: schema: "$ref": "#/components/schemas/error" '422': - description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. Values are usually strings. When a required field inside an object, such as `user.id`, is missing or invalid, the error is a nested object keyed by the inner field. content: application/json: examples: @@ -4859,7 +4857,7 @@ paths: properties: errors: type: object - description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. example: conversation_id: Conversation ID is required additionalProperties: true @@ -5127,7 +5125,7 @@ paths: examples: Successful response: value: - version: 2.17 + version: "2.17" capabilities: - name: run_procedure_reset_password_12345 description: |- @@ -5359,13 +5357,13 @@ paths: properties: name: type: string - description: The capability name. Procedures are named `run_procedure_<title>_<id>`; the static actions are named `reply`, `ask`, and `escalate`. + description: The capability name. Procedures are named `run_procedure_<title_slug>_<id>`, or `run_procedure_<id>` when the title is blank; the static actions are named `reply`, `ask`, and `escalate`. example: run_procedure_reset_password_12345 description: type: string nullable: true description: A description of the capability. For a procedure, the text is wrapped in `<untrusted-content>` tags, and is null when the procedure has no description. - example: Reply to an in-progress Fin conversation. + example: Send a user reply into an existing Fin conversation and get Fin's next turn. Use this to continue any ongoing conversation — including one opened by a procedure run — whenever its status is `awaiting_user_reply`. inputSchema: type: object description: A JSON Schema describing the request body to send to the capability's endpoint. @@ -5437,7 +5435,7 @@ paths: schema: "$ref": "#/components/schemas/error" '422': - description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. Values are usually strings. When a required field inside an object, such as `user.id`, is missing or invalid, the error is a nested object keyed by the inner field. content: application/json: examples: @@ -5450,9 +5448,9 @@ paths: properties: errors: type: object - description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. example: - conversation_id: Conversation ID is required + user: Cannot update more than 10 attributes at once. Received 11 attributes. additionalProperties: true requestBody: required: true @@ -5625,7 +5623,7 @@ paths: schema: "$ref": "#/components/schemas/error" '422': - description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. Values are usually strings. When a required field inside an object, such as `user.id`, is missing or invalid, the error is a nested object keyed by the inner field. content: application/json: examples: @@ -5649,7 +5647,7 @@ paths: value: errors: conversation_metadata: Conversation history cannot contain more than 10 items - Invalid environment: + Invalid environment on a Fin for Platforms workspace: value: errors: environment: Invalid environment @@ -5658,7 +5656,7 @@ paths: properties: errors: type: object - description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. example: conversation_id: Conversation ID is required additionalProperties: true @@ -5687,7 +5685,7 @@ paths: "$ref": "#/components/schemas/fin_agent_attachment" environment: type: string - description: The identifier of the environment to start the conversation in, if your Fin for Platforms workspace has environments. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment; an identifier that matches no environment is rejected. + description: The identifier of the environment to start the conversation in. Only Fin for Platforms workspaces with environments use it; other workspaces ignore it. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment. On a Fin for Platforms workspace, an identifier that matches no environment returns a 422 error. example: a1b2c3d4e5 response_format: type: string @@ -5890,7 +5888,7 @@ paths: schema: "$ref": "#/components/schemas/error" '422': - description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. Values are usually strings. When a required field inside an object, such as `user.id`, is missing or invalid, the error is a nested object keyed by the inner field. content: application/json: examples: @@ -5922,7 +5920,7 @@ paths: value: errors: conversation_id: Fin session already exists for this conversation. Please use /reply to continue the conversation. - Invalid environment: + Invalid environment on a Fin for Platforms workspace: value: errors: environment: Invalid environment @@ -5931,7 +5929,7 @@ paths: properties: errors: type: object - description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. example: conversation_id: Conversation ID is required additionalProperties: true @@ -5962,7 +5960,7 @@ paths: - user - agent - fin - description: The author of the message. + description: Accepted but has no effect. The trigger message is always posted as an operator message. example: agent required: - body @@ -5980,7 +5978,7 @@ paths: order_id: '98765' environment: type: string - description: The identifier of the environment to start the conversation in, if your Fin for Platforms workspace has environments. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment; an identifier that matches no environment is rejected. + description: The identifier of the environment to start the conversation in. Only Fin for Platforms workspaces with environments use it; other workspaces ignore it. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment. On a Fin for Platforms workspace, an identifier that matches no environment returns a 422 error. example: a1b2c3d4e5 required: - conversation_id @@ -6150,7 +6148,7 @@ paths: schema: "$ref": "#/components/schemas/error" '422': - description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. + description: The request could not be processed. The response body maps each field name to its error message, or uses `base` for request-level failures. Values are usually strings. When a required field inside an object, such as `user.id`, is missing or invalid, the error is a nested object keyed by the inner field. content: application/json: examples: @@ -6183,9 +6181,9 @@ paths: properties: errors: type: object - description: Validation messages keyed by the field they apply to, or `base` for request-level failures. A field inside an object, such as `message` or `user`, is reported as a nested object keyed by that field. + description: Validation messages keyed by the field they apply to, or `base` for request-level failures. example: - conversation_id: Conversation ID is required + conversation_id: Conversation not found for the given conversation_id additionalProperties: true requestBody: required: true @@ -19099,7 +19097,7 @@ paths: description: | Returns a paginated list of all data connectors for the workspace, ordered by most recently updated first. Data connectors allow workflows and AI agents to make HTTP requests to external APIs. - Requires the `read_workflow_connector_execution_result` or `read_write_data_connectors` OAuth scope. + OAuth tokens must have the `read_workflow_connector_execution_result` or `read_write_data_connectors` scope. responses: '200': description: successful @@ -19125,7 +19123,7 @@ paths: execution_results_url: "/data_connectors/12345/execution_results" pages: type: pages - per_page: 20 + per_page: 1 next: starting_after: WzE3Njg5MTg5MzUuMCwxMjM0NSxudWxsXQ== schema: @@ -19178,7 +19176,7 @@ paths: description: | Create a new data connector. The connector is created in `draft` state. Configure its URL, headers, data inputs, and other settings, then set it to `live` when ready. - Requires the `read_write_data_connectors` OAuth scope. + OAuth tokens must have the `read_write_data_connectors` scope. responses: '201': description: Data connector created @@ -19191,6 +19189,7 @@ paths: id: '125' name: Get Order Status description: Looks up order status from an external service + internal_description: Looks up order status from an external service state: draft url: "https://api.example.com/orders/{{order_id}}/status" headers: @@ -19362,7 +19361,7 @@ paths: The response includes configuration, data inputs, response fields, and object mappings. - Requires the `read_workflow_connector_execution_result` or `read_write_data_connectors` OAuth scope. + OAuth tokens must have the `read_workflow_connector_execution_result` or `read_write_data_connectors` scope. responses: '200': description: Data connector found @@ -19384,6 +19383,8 @@ paths: - leads execution_type: server_side configuration_response_type: test_response_type + data_transformation_type: full_access + client_function_timeout_ms: 30000 data_inputs: - name: conversation_id type: string @@ -19400,6 +19401,7 @@ paths: customer_authentication: false bypass_authentication: false enforce_auth: true + validate_missing_attributes: true created_by_admin_id: '456' updated_by_admin_id: '456' created_at: '2025-11-15T09:30:00Z' @@ -19476,7 +19478,7 @@ paths: description: | Delete an existing data connector. The connector must be in `draft` state and must not be in use by any workflows or AI agents. - Requires the `read_write_data_connectors` OAuth scope. + OAuth tokens must have the `read_write_data_connectors` scope. responses: '200': description: Data connector deleted @@ -19566,7 +19568,7 @@ paths: description: | Update an existing data connector. Only provided fields are changed. Set `state` to `live` or `draft` to change the connector's state. - Requires the `read_write_data_connectors` OAuth scope. + OAuth tokens must have the `read_write_data_connectors` scope. requestBody: content: application/json: @@ -19614,6 +19616,8 @@ paths: - leads execution_type: server_side configuration_response_type: test_response_type + data_transformation_type: full_access + client_function_timeout_ms: 30000 data_inputs: - name: conversation_id type: string @@ -19634,6 +19638,27 @@ paths: execution_results_url: "/data_connectors/12345/execution_results" schema: "$ref": "#/components/schemas/data_connector_detail" + '400': + description: Invalid parameter + content: + application/json: + examples: + Unpermitted property in headers: + value: + type: error.list + request_id: b4a45e2c-7a8d-4f3e-9c1a-2d5e8f7a6b3c + errors: + - code: parameter_invalid + message: "found unpermitted parameter: :description" + Audiences is not an array: + value: + type: error.list + request_id: f1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b + errors: + - code: parameter_invalid + message: "found unpermitted parameter: :audiences" + schema: + "$ref": "#/components/schemas/error" '404': description: Data connector not found content: @@ -19800,7 +19825,7 @@ paths: Request/response bodies are excluded by default. Use `include_bodies=true` to include them. - Requires the `read_workflow_connector_execution_result` or `read_write_data_connectors` OAuth scope. + OAuth tokens must have the `read_workflow_connector_execution_result` or `read_write_data_connectors` scope. responses: '200': description: successful @@ -19834,7 +19859,7 @@ paths: created_at: '2026-02-10T17:45:15Z' pages: type: pages - per_page: 10 + per_page: 2 next: starting_after: WzE3NzA3NDU1MTUuMCw5OTAwMCxudWxsXQ== schema: @@ -19929,9 +19954,9 @@ paths: operationId: showDataConnectorExecutionResult description: | Retrieve details for a specific data connector execution result. - Always includes request/response bodies and the sanitised request URL. + Includes the request/response bodies and sanitised request URL when they were recorded. - Requires the `read_workflow_connector_execution_result` or `read_write_data_connectors` OAuth scope. + OAuth tokens must have the `read_workflow_connector_execution_result` or `read_write_data_connectors` scope. responses: '200': description: successful @@ -33936,7 +33961,7 @@ components: url: type: string description: The URL of the content import source. It must be an http or https - URL on a publicly reachable domain. + URL whose host is a valid public domain name. example: https://help.example.com audience_ids: nullable: true @@ -35886,7 +35911,7 @@ components: example: Looks up order status from an external service internal_description: type: string - description: The internal description of the data connector. + description: The internal description of the data connector. If omitted while `description` is sent, it is set to the same value as `description`. http_method: type: string description: The HTTP method used when calling the external API. @@ -35982,7 +36007,7 @@ components: example: false enforce_auth: type: boolean - description: Whether authentication is enforced for this connector. + description: Whether authentication is enforced. On workspaces where this is supported, it takes precedence over `customer_authentication` and `bypass_authentication` when sent together, and setting it to false disables OTP. validate_missing_attributes: type: boolean description: Whether to validate that all required data inputs have values before executing. @@ -36020,7 +36045,7 @@ components: example: Updated description internal_description: type: string - description: The internal description of the data connector. + description: The internal description of the data connector. If omitted while `description` is sent, it is set to the same value as `description`. state: type: string description: The desired state of the connector. @@ -36122,7 +36147,7 @@ components: example: false enforce_auth: type: boolean - description: Whether authentication is enforced for this connector. + description: Whether authentication is enforced. On workspaces where this is supported, it takes precedence over `customer_authentication` and `bypass_authentication` when sent together, and setting it to false disables OTP. validate_missing_attributes: type: boolean description: Whether to validate missing attributes before execution. @@ -36225,7 +36250,7 @@ components: x-tags: - Data Connectors description: | - Full detail view of a data connector, returned by `GET /data_connectors/{id}`. + Full detail view of a data connector, returned by `GET /data_connectors/{id}`, `POST /data_connectors`, and `PATCH /data_connectors/{id}`. Includes configuration, data inputs, response fields, and object mappings. properties: type: @@ -36311,7 +36336,6 @@ components: - leads execution_type: type: string - nullable: true description: How the connector executes. enum: - server_side @@ -36319,7 +36343,6 @@ components: example: server_side configuration_response_type: type: string - nullable: true description: The expected response format from the connector. enum: - test_response_type @@ -36327,7 +36350,6 @@ components: example: test_response_type data_transformation_type: type: string - nullable: true description: The type of data transformation applied to the response. enum: - full_access @@ -36335,10 +36357,9 @@ components: - code_block_transformation transform_code_block: type: object - nullable: true description: | - The code block used to transform the connector's response when `data_transformation_type` is - `code_block_transformation`. Omitted if the connector has no transform code block configured. + The code block used to transform the connector's response. Present only when `data_transformation_type` is + `code_block_transformation` and a code block exists; otherwise omitted. example: code: | def transform(response): @@ -36349,7 +36370,7 @@ components: properties: code: type: string - description: The source code of the transform code block. The API response body is available as `inputs['data']`, and the code must end with a top-level `return` of the transformed value. + description: The source code of the transform code block. The API response body is available as `inputs['data']`. example: | def transform(response): return {"status": response["order_status"]} @@ -36573,7 +36594,7 @@ components: error_message: type: string nullable: true - description: A human-readable error message. Query parameters, userinfo, and fragments in URLs are redacted. + description: A human-readable error message. Only URLs inside the message are redacted (query parameters, userinfo, and fragments); the rest of the message is returned as is. example: Connection refused execution_time_ms: type: integer @@ -36614,7 +36635,7 @@ components: request_url: type: string nullable: true - description: The request URL. Query parameters, userinfo, and fragments are redacted. + description: The request URL. Query parameters, userinfo, and fragments are redacted. For some hosts that put credentials in the path, the path is removed too. A suffix such as ` [query params redacted]` or ` [credentials redacted]` is appended when anything is redacted, and a URL that cannot be parsed becomes `[invalid URL redacted]`. example: https://api.example.com/webhook request_body: type: string @@ -37804,7 +37825,9 @@ components: description: The time when the external page was last ingested. example: 1672928610 tags: - "$ref": "#/components/schemas/tags" + description: The tags applied to the external page. + allOf: + - "$ref": "#/components/schemas/tags" required: - id - type @@ -37856,14 +37879,14 @@ components: - user - agent - fin - description: The author that created the message. + description: The author that created the message. In `conversation_metadata.history`, only `user` and `agent` are accepted. example: user body: type: string description: | The body of the message. Accepts both plain text and HTML format. - When sending a message to Fin, this should contain the user's message. - Fin's response will be returned as HTML. + For the message you send to Fin, this is the user's message. For an `agent` item in `conversation_metadata.history`, it is the agent's message. + Fin's response is returned in the format set by `response_format` (HTML by default). example: How can I see my account details? timestamp: type: string @@ -37872,14 +37895,15 @@ components: The timestamp when the message was created. Used to deduplicate messages sent within a 5 minute window. Ideally should include milliseconds for higher precision. - Send either `timestamp` or `timestamp_ms`. If you send both, `timestamp_ms` is used. + Send `timestamp` or `timestamp_ms`; at least one is required. If you send both, `timestamp_ms` is used. + On the top-level `message`, sending neither fails with a 422 error (`message: timestamp_ms is required`). In `conversation_metadata.history`, an item with neither causes the whole history to be ignored. example: '2025-01-24T10:01:20.000Z' timestamp_ms: type: string format: date-time description: | The timestamp when the message was created, with millisecond precision. - Accepted in place of `timestamp` when you send a message, and also present in webhook event responses (fin_replied). + Accepted in place of `timestamp` when you send a message, and also present in webhook event responses (fin_replied). At least one of `timestamp` or `timestamp_ms` is required. example: '2025-01-24T10:01:20.456Z' required: - author @@ -37968,6 +37992,7 @@ components: An array of previous messages in the conversation before Fin is initialized. This data provides context to Fin and helps generate a better answer. Limit to the last 10 messages. + Only `user` and `agent` authors are accepted. If any item is invalid, for example it has no `timestamp` or `timestamp_ms`, or has another author, the whole history is ignored. maxItems: 10 items: "$ref": "#/components/schemas/fin_agent_message" @@ -40472,12 +40497,12 @@ components: type: integer format: date-time nullable: true - description: The time when the tag was applied to the object. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket. + description: The time when the tag was applied to the object. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket, or when it is returned as part of an external page. example: 1663597223 applied_by: type: object nullable: true - description: The admin who applied the tag. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket. + description: The admin who applied the tag. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket, or when it is returned as part of an external page. allOf: - "$ref": "#/components/schemas/reference" tag_basic: @@ -41915,7 +41940,7 @@ components: url: type: string description: The URL of the content import source. It must be an http or https - URL on a publicly reachable domain. This may only be different from the + URL whose host is a valid public domain name. This may only be different from the existing value if the sync behavior is API. example: https://help.example.com audience_ids: From 23014ddff1e593bd8b1b776c0cb837ee03521ce5 Mon Sep 17 00:00:00 2001 From: Cathal Ging <cathal.ging@intercom.io> Date: Wed, 21 Oct 2026 15:12:15 +0100 Subject: [PATCH 5/8] Say that Fin Agent API escalation closes the original conversation Also fix the content import source type description and the update request title. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> --- descriptions/0/api.intercom.io.yaml | 18 +++++++++--------- descriptions/2.17/api.intercom.io.yaml | 18 +++++++++--------- 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index d5bb399d..cc0925d6 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -30158,8 +30158,8 @@ paths: - `conversation_id` — escalate an existing agent conversation, including one started with `/fin/ask`. On the Intercom Helpdesk, Fin by default summarises the conversation and opens a new Helpdesk conversation that carries the summary as an internal note. - Escalation does not change the original agent conversation's assignment or open/closed - state. Configure an escalation Operator Workflow to change this default. + Configure an escalation Operator Workflow to change this default. Escalation closes the + original agent conversation if it is open. - `user` — escalate on behalf of a user with no prior agent conversation. On the Intercom Helpdesk, a new Helpdesk conversation is created for the teammate. Not supported on Fin for Platforms — see below. @@ -30176,13 +30176,13 @@ paths: On Fin for Platforms, `conversation_id` is required — `user` is not supported and is rejected, because there is no Intercom Helpdesk in which to create a conversation. There is no Intercom inbox either, so an escalation that no workflow handles does not open a - Helpdesk conversation for a teammate. `context` is not surfaced, and the conversation is - left open for your platform to hand off and continue driving. + Helpdesk conversation for a teammate. `context` is not surfaced. The conversation is closed, + as on the Intercom Helpdesk, and your platform hands the user off to a human. You are notified over the existing webhook or SSE channel with an `escalated` status - followed by `complete`. The `complete` status signals that Fin is done; it does not close - the conversation. On the Intercom Helpdesk, the new human conversation remains open; on - Fin for Platforms, the conversation remains open for whoever handles it on your platform. + followed by `complete`. The `complete` status signals that Fin is done. By then the + original agent conversation is closed; on the Intercom Helpdesk, the new human + conversation remains open. {% admonition type="warning" %} To request access to the Fin Agent API, go to **Settings > Integrations > Fin Agent API** in your workspace and tell us about your use case. Once access is granted, **Fin Agent API** appears under **Fin AI Agent > Deploy**. @@ -35878,7 +35878,7 @@ components: properties: type: type: string - description: Always external_page + description: Always content_import_source enum: - content_import_source default: content_import_source @@ -47737,7 +47737,7 @@ components: nullable: true description: The custom attributes which are set for the contact update_content_import_source_request: - title: Create Content Import Source Payload + title: Update Content Import Source Payload type: object description: You can modify a Content Import Source of your Fin Content Library. nullable: false diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 11f10ef0..6494734f 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -6024,8 +6024,8 @@ paths: - `conversation_id` — escalate an existing agent conversation, including one started with `/fin/ask`. On the Intercom Helpdesk, Fin by default summarises the conversation and opens a new Helpdesk conversation that carries the summary as an internal note. - Escalation does not change the original agent conversation's assignment or open/closed - state. Configure an escalation Operator Workflow to change this default. + Configure an escalation Operator Workflow to change this default. Escalation closes the + original agent conversation if it is open. - `user` — escalate on behalf of a user with no prior agent conversation. On the Intercom Helpdesk, a new Helpdesk conversation is created for the teammate. Not supported on Fin for Platforms — see below. @@ -6042,13 +6042,13 @@ paths: On Fin for Platforms, `conversation_id` is required — `user` is not supported and is rejected, because there is no Intercom Helpdesk in which to create a conversation. There is no Intercom inbox either, so an escalation that no workflow handles does not open a - Helpdesk conversation for a teammate. `context` is not surfaced, and the conversation is - left open for your platform to hand off and continue driving. + Helpdesk conversation for a teammate. `context` is not surfaced. The conversation is closed, + as on the Intercom Helpdesk, and your platform hands the user off to a human. You are notified over the existing webhook or SSE channel with an `escalated` status - followed by `complete`. The `complete` status signals that Fin is done; it does not close - the conversation. On the Intercom Helpdesk, the new human conversation remains open; on - Fin for Platforms, the conversation remains open for whoever handles it on your platform. + followed by `complete`. The `complete` status signals that Fin is done. By then the + original agent conversation is closed; on the Intercom Helpdesk, the new human + conversation remains open. {% admonition type="warning" %} To request access to the Fin Agent API, go to **Settings > Integrations > Fin Agent API** in your workspace and tell us about your use case. Once access is granted, **Fin Agent API** appears under **Fin AI Agent > Deploy**. @@ -31394,7 +31394,7 @@ components: properties: type: type: string - description: Always external_page + description: Always content_import_source enum: - content_import_source default: content_import_source @@ -41915,7 +41915,7 @@ components: nullable: true description: The custom attributes which are set for the contact update_content_import_source_request: - title: Create Content Import Source Payload + title: Update Content Import Source Payload type: object description: You can modify a Content Import Source of your Fin Content Library. nullable: false From a51f75869bfd5c78487d4c05073c401202f0d2f2 Mon Sep 17 00:00:00 2001 From: Cathal Ging <cathal.ging@intercom.io> Date: Thu, 22 Oct 2026 11:07:22 +0100 Subject: [PATCH 6/8] Say an escalation workflow may still act on the conversation after complete Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> --- descriptions/0/api.intercom.io.yaml | 5 +++-- descriptions/2.17/api.intercom.io.yaml | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index cc0925d6..3be14adc 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -30181,8 +30181,9 @@ paths: You are notified over the existing webhook or SSE channel with an `escalated` status followed by `complete`. The `complete` status signals that Fin is done. By then the - original agent conversation is closed; on the Intercom Helpdesk, the new human - conversation remains open. + original agent conversation has been closed, though an escalation Operator Workflow + may still act on it afterwards. On the Intercom Helpdesk, the new human conversation + remains open. {% admonition type="warning" %} To request access to the Fin Agent API, go to **Settings > Integrations > Fin Agent API** in your workspace and tell us about your use case. Once access is granted, **Fin Agent API** appears under **Fin AI Agent > Deploy**. diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 6494734f..57cc6ebc 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -6047,8 +6047,9 @@ paths: You are notified over the existing webhook or SSE channel with an `escalated` status followed by `complete`. The `complete` status signals that Fin is done. By then the - original agent conversation is closed; on the Intercom Helpdesk, the new human - conversation remains open. + original agent conversation has been closed, though an escalation Operator Workflow + may still act on it afterwards. On the Intercom Helpdesk, the new human conversation + remains open. {% admonition type="warning" %} To request access to the Fin Agent API, go to **Settings > Integrations > Fin Agent API** in your workspace and tell us about your use case. Once access is granted, **Fin Agent API** appears under **Fin AI Agent > Deploy**. From f5611384cd70cc105377d61367454560d88c1910 Mon Sep 17 00:00:00 2001 From: Cathal Ging <cathal.ging@intercom.io> Date: Thu, 22 Oct 2026 15:39:56 +0100 Subject: [PATCH 7/8] Address review: internal_description, environment, transform return, markdown format, page limit Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> --- descriptions/0/api.intercom.io.yaml | 31 ++++++++++++++++++-------- descriptions/2.17/api.intercom.io.yaml | 31 ++++++++++++++++++-------- 2 files changed, 44 insertions(+), 18 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 9fd838fd..fac032da 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -1252,7 +1252,7 @@ paths: type: integer minimum: 1 default: 1 - description: The page of results to fetch. Defaults to the first page. Pages above 5001 are not supported. + description: The page of results to fetch. Defaults to the first page. `page` multiplied by `per_page` cannot exceed 10,000; beyond that the API returns a 400 `bad_request` error with the message `page limit reached, please use scroll API`. example: 1 - name: per_page in: query @@ -1384,6 +1384,13 @@ paths: errors: - code: parameter_invalid message: Page size must be less than or equal to 150 + Page limit exceeded: + value: + type: error.list + request_id: d2a8f6c1-5b3e-4a79-8e0d-7c41f9b2a6e3 + errors: + - code: bad_request + message: page limit reached, please use scroll API schema: "$ref": "#/components/schemas/error" post: @@ -20001,7 +20008,7 @@ paths: id: '125' name: Get Order Status description: Looks up order status from an external service - internal_description: Looks up order status from an external service + internal_description: '' state: draft url: "https://api.example.com/orders/{{order_id}}/status" headers: @@ -30019,7 +30026,7 @@ paths: "$ref": "#/components/schemas/fin_agent_attachment" environment: type: string - description: The identifier of the environment to start the conversation in. Only Fin for Platforms workspaces with environments use it; other workspaces ignore it. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment. On a Fin for Platforms workspace, an identifier that matches no environment returns a 422 error. + description: The identifier of the environment to start the conversation in. Only Fin for Platforms workspaces use it; other workspaces ignore it. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment. On a Fin for Platforms workspace, an identifier that matches no environment returns a 422 error. example: a1b2c3d4e5 response_format: type: string @@ -30534,7 +30541,7 @@ paths: order_id: '98765' environment: type: string - description: The identifier of the environment to start the conversation in. Only Fin for Platforms workspaces with environments use it; other workspaces ignore it. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment. On a Fin for Platforms workspace, an identifier that matches no environment returns a 422 error. + description: The identifier of the environment to start the conversation in. Only Fin for Platforms workspaces use it; other workspaces ignore it. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment. On a Fin for Platforms workspace, an identifier that matches no environment returns a 422 error. example: a1b2c3d4e5 required: - conversation_id @@ -31165,7 +31172,7 @@ paths: "$ref": "#/components/schemas/fin_agent_conversation_metadata" environment: type: string - description: The identifier of the environment to start the conversation in. Only Fin for Platforms workspaces with environments use it; other workspaces ignore it. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment. On a Fin for Platforms workspace, an identifier that matches no environment returns a 422 error. + description: The identifier of the environment to start the conversation in. Only Fin for Platforms workspaces use it; other workspaces ignore it. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment. On a Fin for Platforms workspace, an identifier that matches no environment returns a 422 error. example: a1b2c3d4e5 response_format: type: string @@ -40852,7 +40859,7 @@ components: example: Looks up order status from an external service internal_description: type: string - description: The internal description of the data connector. If omitted while `description` is sent, it is set to the same value as `description`. + description: The internal description of the data connector. If omitted, it is an empty string. http_method: type: string description: The HTTP method used when calling the external API. @@ -41024,7 +41031,7 @@ components: example: Updated description internal_description: type: string - description: The internal description of the data connector. If omitted while `description` is sent, it is set to the same value as `description`. + description: The internal description of the data connector. If omitted, it keeps its current value. state: type: string description: The desired state of the connector. @@ -41387,7 +41394,7 @@ components: properties: code: type: string - description: The source code of the transform code block. The API response body is available as `inputs['data']`. + description: The source code of the transform code block. The API response body is available as `inputs['data']`. The code must `return` the transformed value. example: | def transform(response): return {"status": response["order_status"]} @@ -43748,8 +43755,14 @@ components: example: fin body: type: string - description: The HTML body of Fin's response. + description: The body of Fin's response, in the format given by `format` (HTML by default). example: <p>You can see your account details by clicking on the <em>Account</em> tab in the top right corner of the screen.</p> + format: + type: string + enum: + - html + - markdown + description: Present only when the request set `response_format` to `markdown`. `markdown` when Fin converted the reply to Markdown, or `html` if it could not convert the reply and sent HTML instead. When absent, `body` is HTML. timestamp_ms: type: string format: date-time diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 4749cb5a..5664bb1f 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -1979,7 +1979,7 @@ paths: type: integer minimum: 1 default: 1 - description: The page of results to fetch. Defaults to the first page. Pages above 5001 are not supported. + description: The page of results to fetch. Defaults to the first page. `page` multiplied by `per_page` cannot exceed 10,000; beyond that the API returns a 400 `bad_request` error with the message `page limit reached, please use scroll API`. example: 1 - name: per_page in: query @@ -2111,6 +2111,13 @@ paths: errors: - code: parameter_invalid message: Page size must be less than or equal to 150 + Page limit exceeded: + value: + type: error.list + request_id: d2a8f6c1-5b3e-4a79-8e0d-7c41f9b2a6e3 + errors: + - code: bad_request + message: page limit reached, please use scroll API schema: "$ref": "#/components/schemas/error" post: @@ -5045,7 +5052,7 @@ paths: "$ref": "#/components/schemas/fin_agent_conversation_metadata" environment: type: string - description: The identifier of the environment to start the conversation in. Only Fin for Platforms workspaces with environments use it; other workspaces ignore it. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment. On a Fin for Platforms workspace, an identifier that matches no environment returns a 422 error. + description: The identifier of the environment to start the conversation in. Only Fin for Platforms workspaces use it; other workspaces ignore it. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment. On a Fin for Platforms workspace, an identifier that matches no environment returns a 422 error. example: a1b2c3d4e5 response_format: type: string @@ -6101,7 +6108,7 @@ paths: "$ref": "#/components/schemas/fin_agent_attachment" environment: type: string - description: The identifier of the environment to start the conversation in. Only Fin for Platforms workspaces with environments use it; other workspaces ignore it. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment. On a Fin for Platforms workspace, an identifier that matches no environment returns a 422 error. + description: The identifier of the environment to start the conversation in. Only Fin for Platforms workspaces use it; other workspaces ignore it. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment. On a Fin for Platforms workspace, an identifier that matches no environment returns a 422 error. example: a1b2c3d4e5 response_format: type: string @@ -6387,7 +6394,7 @@ paths: order_id: '98765' environment: type: string - description: The identifier of the environment to start the conversation in. Only Fin for Platforms workspaces with environments use it; other workspaces ignore it. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment. On a Fin for Platforms workspace, an identifier that matches no environment returns a 422 error. + description: The identifier of the environment to start the conversation in. Only Fin for Platforms workspaces use it; other workspaces ignore it. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment. On a Fin for Platforms workspace, an identifier that matches no environment returns a 422 error. example: a1b2c3d4e5 required: - conversation_id @@ -19700,7 +19707,7 @@ paths: id: '125' name: Get Order Status description: Looks up order status from an external service - internal_description: Looks up order status from an external service + internal_description: '' state: draft url: "https://api.example.com/orders/{{order_id}}/status" headers: @@ -36468,7 +36475,7 @@ components: example: Looks up order status from an external service internal_description: type: string - description: The internal description of the data connector. If omitted while `description` is sent, it is set to the same value as `description`. + description: The internal description of the data connector. If omitted, it is an empty string. http_method: type: string description: The HTTP method used when calling the external API. @@ -36602,7 +36609,7 @@ components: example: Updated description internal_description: type: string - description: The internal description of the data connector. If omitted while `description` is sent, it is set to the same value as `description`. + description: The internal description of the data connector. If omitted, it keeps its current value. state: type: string description: The desired state of the connector. @@ -36927,7 +36934,7 @@ components: properties: code: type: string - description: The source code of the transform code block. The API response body is available as `inputs['data']`. + description: The source code of the transform code block. The API response body is available as `inputs['data']`. The code must `return` the transformed value. example: | def transform(response): return {"status": response["order_status"]} @@ -38693,8 +38700,14 @@ components: example: fin body: type: string - description: The HTML body of Fin's response. + description: The body of Fin's response, in the format given by `format` (HTML by default). example: <p>You can see your account details by clicking on the <em>Account</em> tab in the top right corner of the screen.</p> + format: + type: string + enum: + - html + - markdown + description: Present only when the request set `response_format` to `markdown`. `markdown` when Fin converted the reply to Markdown, or `html` if it could not convert the reply and sent HTML instead. When absent, `body` is HTML. timestamp_ms: type: string format: date-time From 7cea9ee5698a9a347b57f93a39b06ab8591114a5 Mon Sep 17 00:00:00 2001 From: Cathal Ging <cathal.ging@intercom.io> Date: Thu, 22 Oct 2026 16:08:38 +0100 Subject: [PATCH 8/8] Correct escalation, status, paging and data connector wording found in pre-review Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> --- descriptions/0/api.intercom.io.yaml | 68 ++++++++++++++++++-------- descriptions/2.17/api.intercom.io.yaml | 41 +++++++++------- 2 files changed, 71 insertions(+), 38 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index fac032da..8cd5d0cd 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -804,6 +804,7 @@ paths: in: query schema: type: integer + minimum: 1 maximum: 150 default: 50 description: The number of results to return per page. Maximum 150. @@ -1252,12 +1253,13 @@ paths: type: integer minimum: 1 default: 1 - description: The page of results to fetch. Defaults to the first page. `page` multiplied by `per_page` cannot exceed 10,000; beyond that the API returns a 400 `bad_request` error with the message `page limit reached, please use scroll API`. + description: The page of results to fetch. Defaults to the first page. `page` cannot exceed 5,001, and `page` multiplied by `per_page` cannot exceed 10,000. Past 5,001 the API returns a 400 `parameter_invalid` error; past 10,000 results it returns a 400 `bad_request` error with the message `page limit reached, please use scroll API`. example: 1 - name: per_page in: query schema: type: integer + minimum: 1 maximum: 150 default: 50 description: The number of results to return per page. Maximum 150. @@ -1488,13 +1490,21 @@ paths: schema: "$ref": "#/components/schemas/error" '404': - description: Unknown audience IDs + description: Content import source or audience not found content: application/json: examples: + Content import source not found: + value: + type: error.list + request_id: 58c2f0b9-7e14-4a3d-a6c8-1d9b3e5f7a02 + errors: + - code: content_import_source_not_found + message: Content Import Source not found Unknown audience IDs: value: type: error.list + request_id: e9a30c47-1b6d-4d52-8f0a-7c5e2b9d1a36 errors: - code: parameter_invalid message: 'audience_ids contains unknown audience IDs: 999' @@ -1781,13 +1791,28 @@ paths: schema: "$ref": "#/components/schemas/error" '404': - description: Unknown audience IDs + description: External page, content import source or audience not found content: application/json: examples: + External page not found: + value: + type: error.list + request_id: d41b7e92-6a03-4f8c-91e5-3c2a8b0f6d74 + errors: + - code: not_found + message: Resource Not Found + Content import source not found: + value: + type: error.list + request_id: 58c2f0b9-7e14-4a3d-a6c8-1d9b3e5f7a02 + errors: + - code: content_import_source_not_found + message: Content Import Source not found Unknown audience IDs: value: type: error.list + request_id: e9a30c47-1b6d-4d52-8f0a-7c5e2b9d1a36 errors: - code: parameter_invalid message: 'audience_ids contains unknown audience IDs: 999' @@ -20860,7 +20885,7 @@ paths: operationId: showDataConnectorExecutionResult description: | Retrieve details for a specific data connector execution result. - Includes the request/response bodies and sanitised request URL when they were recorded. + Includes the request/response bodies and sanitised request URL when they are available. OAuth tokens must have the `read_workflow_connector_execution_result` or `read_write_data_connectors` scope. responses: @@ -29705,7 +29730,7 @@ paths: properties: name: type: string - description: The capability name. Procedures are named `run_procedure_<title_slug>_<id>`, or `run_procedure_<id>` when the title is blank; the static actions are named `reply`, `ask`, and `escalate`. + description: The capability name. Procedures are named `run_procedure_<title_slug>_<id>`, with the slug cut to 80 characters, or `run_procedure_<id>` when the title gives no usable slug (for example a blank or non-Latin title); the static actions are named `reply`, `ask`, and `escalate`. example: run_procedure_reset_password_12345 description: type: string @@ -29891,7 +29916,7 @@ paths: - resolved - complete description: | - Fin's current status in the conversation workflow. + Fin's status when the request was accepted. Always `thinking`; later statuses arrive as events. example: thinking created_at_ms: type: string @@ -30140,7 +30165,7 @@ paths: - resolved - complete description: | - Fin's current status in the conversation workflow. + Fin's status when the request was accepted. Always `thinking`; later statuses arrive as events. example: thinking created_at_ms: type: string @@ -30385,7 +30410,7 @@ paths: - resolved - complete description: | - Fin's current status in the conversation workflow. + Fin's status when the request was accepted. Always `thinking`; later statuses arrive as events. example: thinking created_at_ms: type: string @@ -30589,9 +30614,10 @@ paths: and opens a new Helpdesk conversation that carries the summary as an internal note. Configure an escalation Operator Workflow to change this default. Escalation closes the original agent conversation if it is open. - - `user` — escalate on behalf of a user with no prior agent conversation. On the Intercom - Helpdesk, a new Helpdesk conversation is created for the teammate. Not supported on Fin - for Platforms — see below. + - `user` — escalate on behalf of a user with no prior agent conversation. Fin creates an + agent conversation for the escalation and closes it once the handoff completes. On the + Intercom Helpdesk, the teammate works in a separate new Helpdesk conversation. Not + supported on Fin for Platforms — see below. In both cases, pass the optional `context` to give the receiving teammate background your orchestrating agent has and Fin does not. On the Intercom Helpdesk, it appears above the @@ -30610,9 +30636,10 @@ paths: You are notified via webhooks with an `escalated` status followed by `complete`. The `complete` status signals that Fin is done. By then the - original agent conversation has been closed, though an escalation Operator Workflow - may still act on it afterwards. On the Intercom Helpdesk, the new human conversation - remains open. + original agent conversation has been closed. An escalation Operator Workflow may act + on it afterwards, but it is closed again once the workflow's first steps have run, so + only steps that run later (for example after a wait) can reopen it. On the Intercom + Helpdesk, the new human conversation remains open. {% admonition type="warning" %} To request access to the Fin Agent API, go to **Settings > Integrations > Fin Agent API** in your workspace and tell us about your use case. Once access is granted, **Fin Agent API** appears under **Fin AI Agent > Deploy**. @@ -30637,11 +30664,11 @@ paths: properties: conversation_id: type: string - description: The external ID of the conversation. When you escalate an existing conversation by `conversation_id`, this echoes the ID you sent. When you escalate a `user`, a new conversation is created and Fin generates this ID for it. + description: The external ID of the conversation. When you escalate an existing conversation by `conversation_id`, this echoes the ID you sent. When you escalate a `user`, Fin creates an agent conversation for the escalation and generates this ID for it. example: ext-123 intercom_conversation_id: type: string - description: The internal Intercom conversation ID. Returned when a new conversation was created for the escalation. + description: The internal Intercom ID of the agent conversation created for the escalation. Returned only when escalating on behalf of a `user`. Fin closes this conversation once the handoff completes; the teammate works in a separate Helpdesk conversation. example: '987654321' status: type: string @@ -31037,7 +31064,7 @@ paths: - resolved - complete description: | - Fin's current status in the conversation workflow. + Fin's status when the request was accepted. Always `thinking`; later statuses arrive as events. example: thinking created_at_ms: type: string @@ -41031,7 +41058,7 @@ components: example: Updated description internal_description: type: string - description: The internal description of the data connector. If omitted, it keeps its current value. + description: The internal description of the data connector. If omitted, it keeps its current value, unless the connector has no internal description yet, in which case it is set to the connector's `description`. state: type: string description: The desired state of the connector. @@ -41618,7 +41645,7 @@ components: error_message: type: string nullable: true - description: A human-readable error message. Only URLs inside the message are redacted (query parameters, userinfo, and fragments); the rest of the message is returned as is. + description: A human-readable error message. Any http or https URLs in it are redacted the same way as `request_url`; the rest of the message is returned as is. example: Connection refused execution_time_ms: type: integer @@ -48196,7 +48223,8 @@ components: url: type: string description: The URL of the external page. This will be used by Fin to link - end users to the page it based its answer on. + end users to the page it based its answer on. If omitted, the page's + existing URL is removed. example: https://help.example.com/en/articles/1234-getting-started ai_agent_availability: type: boolean diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 5664bb1f..f5c8148c 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -1531,6 +1531,7 @@ paths: in: query schema: type: integer + minimum: 1 maximum: 150 default: 50 description: The number of results to return per page. Maximum 150. @@ -1979,12 +1980,13 @@ paths: type: integer minimum: 1 default: 1 - description: The page of results to fetch. Defaults to the first page. `page` multiplied by `per_page` cannot exceed 10,000; beyond that the API returns a 400 `bad_request` error with the message `page limit reached, please use scroll API`. + description: The page of results to fetch. Defaults to the first page. `page` cannot exceed 5,001, and `page` multiplied by `per_page` cannot exceed 10,000. Past 5,001 the API returns a 400 `parameter_invalid` error; past 10,000 results it returns a 400 `bad_request` error with the message `page limit reached, please use scroll API`. example: 1 - name: per_page in: query schema: type: integer + minimum: 1 maximum: 150 default: 50 description: The number of results to return per page. Maximum 150. @@ -4917,7 +4919,7 @@ paths: - resolved - complete description: | - Fin's current status in the conversation workflow. + Fin's status when the request was accepted. Always `thinking`; later statuses arrive as events. example: thinking created_at_ms: type: string @@ -5189,7 +5191,7 @@ paths: - resolved - complete description: | - Fin's current status in the conversation workflow. + Fin's status when the request was accepted. Always `thinking`; later statuses arrive as events. example: thinking created_at_ms: type: string @@ -5787,7 +5789,7 @@ paths: properties: name: type: string - description: The capability name. Procedures are named `run_procedure_<title_slug>_<id>`, or `run_procedure_<id>` when the title is blank; the static actions are named `reply`, `ask`, and `escalate`. + description: The capability name. Procedures are named `run_procedure_<title_slug>_<id>`, with the slug cut to 80 characters, or `run_procedure_<id>` when the title gives no usable slug (for example a blank or non-Latin title); the static actions are named `reply`, `ask`, and `escalate`. example: run_procedure_reset_password_12345 description: type: string @@ -5973,7 +5975,7 @@ paths: - resolved - complete description: | - Fin's current status in the conversation workflow. + Fin's status when the request was accepted. Always `thinking`; later statuses arrive as events. example: thinking created_at_ms: type: string @@ -6238,7 +6240,7 @@ paths: - resolved - complete description: | - Fin's current status in the conversation workflow. + Fin's status when the request was accepted. Always `thinking`; later statuses arrive as events. example: thinking created_at_ms: type: string @@ -6442,9 +6444,10 @@ paths: and opens a new Helpdesk conversation that carries the summary as an internal note. Configure an escalation Operator Workflow to change this default. Escalation closes the original agent conversation if it is open. - - `user` — escalate on behalf of a user with no prior agent conversation. On the Intercom - Helpdesk, a new Helpdesk conversation is created for the teammate. Not supported on Fin - for Platforms — see below. + - `user` — escalate on behalf of a user with no prior agent conversation. Fin creates an + agent conversation for the escalation and closes it once the handoff completes. On the + Intercom Helpdesk, the teammate works in a separate new Helpdesk conversation. Not + supported on Fin for Platforms — see below. In both cases, pass the optional `context` to give the receiving teammate background your orchestrating agent has and Fin does not. On the Intercom Helpdesk, it appears above the @@ -6463,9 +6466,10 @@ paths: You are notified via webhooks with an `escalated` status followed by `complete`. The `complete` status signals that Fin is done. By then the - original agent conversation has been closed, though an escalation Operator Workflow - may still act on it afterwards. On the Intercom Helpdesk, the new human conversation - remains open. + original agent conversation has been closed. An escalation Operator Workflow may act + on it afterwards, but it is closed again once the workflow's first steps have run, so + only steps that run later (for example after a wait) can reopen it. On the Intercom + Helpdesk, the new human conversation remains open. {% admonition type="warning" %} To request access to the Fin Agent API, go to **Settings > Integrations > Fin Agent API** in your workspace and tell us about your use case. Once access is granted, **Fin Agent API** appears under **Fin AI Agent > Deploy**. @@ -6490,11 +6494,11 @@ paths: properties: conversation_id: type: string - description: The external ID of the conversation. When you escalate an existing conversation by `conversation_id`, this echoes the ID you sent. When you escalate a `user`, a new conversation is created and Fin generates this ID for it. + description: The external ID of the conversation. When you escalate an existing conversation by `conversation_id`, this echoes the ID you sent. When you escalate a `user`, Fin creates an agent conversation for the escalation and generates this ID for it. example: ext-123 intercom_conversation_id: type: string - description: The internal Intercom conversation ID. Returned when a new conversation was created for the escalation. + description: The internal Intercom ID of the agent conversation created for the escalation. Returned only when escalating on behalf of a `user`. Fin closes this conversation once the handoff completes; the teammate works in a separate Helpdesk conversation. example: '987654321' status: type: string @@ -20472,7 +20476,7 @@ paths: operationId: showDataConnectorExecutionResult description: | Retrieve details for a specific data connector execution result. - Includes the request/response bodies and sanitised request URL when they were recorded. + Includes the request/response bodies and sanitised request URL when they are available. OAuth tokens must have the `read_workflow_connector_execution_result` or `read_write_data_connectors` scope. responses: @@ -36609,7 +36613,7 @@ components: example: Updated description internal_description: type: string - description: The internal description of the data connector. If omitted, it keeps its current value. + description: The internal description of the data connector. If omitted, it keeps its current value, unless the connector has no internal description yet, in which case it is set to the connector's `description`. state: type: string description: The desired state of the connector. @@ -37158,7 +37162,7 @@ components: error_message: type: string nullable: true - description: A human-readable error message. Only URLs inside the message are redacted (query parameters, userinfo, and fragments); the rest of the message is returned as is. + description: A human-readable error message. Any http or https URLs in it are redacted the same way as `request_url`; the rest of the message is returned as is. example: Connection refused execution_time_ms: type: integer @@ -42555,7 +42559,8 @@ components: url: type: string description: The URL of the external page. This will be used by Fin to link - end users to the page it based its answer on. + end users to the page it based its answer on. If omitted, the page's + existing URL is removed. example: https://help.example.com/en/articles/1234-getting-started ai_agent_availability: type: boolean