From c3a99a52d6c80eff96827384cd41592e2078e83a Mon Sep 17 00:00:00 2001 From: kilian-tennyson Date: Tue, 19 May 2026 10:32:58 +0100 Subject: [PATCH 1/5] Add GET /audiences/{id} to Preview OpenAPI spec Co-Authored-By: Claude Sonnet 4.6 (1M context) --- descriptions/0/api.intercom.io.yaml | 62 +++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index a4e2f13..aec3f5b 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -1815,6 +1815,68 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + "/audiences/{id}": + get: + summary: Retrieve an audience + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: id + in: path + required: true + description: The unique identifier of the audience to retrieve. + example: 123 + schema: + type: integer + tags: + - Audiences + operationId: getAudience + description: You can fetch the details of a single audience by ID. + responses: + '200': + description: Successful response + content: + application/json: + examples: + Successful response: + value: + type: audience + id: '123' + name: VIP Customers + created_at: 1717200000 + updated_at: 1717200000 + schema: + "$ref": "#/components/schemas/audience" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b1939528-98f0-4a63-a442-2cc9203fc8c7 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + '404': + description: Not found + content: + application/json: + examples: + Not found: + value: + type: error.list + request_id: b1939528-98f0-4a63-a442-2cc9203fc8c7 + errors: + - code: not_found + message: Resource Not Found + schema: + "$ref": "#/components/schemas/error" "/export/reporting_data/enqueue": post: summary: Enqueue a new reporting data export job From 787a42adb18b487f64e5d2f1c382101afb702d33 Mon Sep 17 00:00:00 2001 From: kilian-tennyson Date: Tue, 19 May 2026 16:34:31 +0100 Subject: [PATCH 2/5] Add DELETE /audiences/{id} operation to OpenAPI spec Co-Authored-By: Claude Sonnet 4.6 (1M context) --- descriptions/0/api.intercom.io.yaml | 49 +++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index aec3f5b..3a41828 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -1877,6 +1877,55 @@ paths: message: Resource Not Found schema: "$ref": "#/components/schemas/error" + delete: + summary: Delete an audience + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: id + in: path + required: true + description: The unique identifier of the audience to delete. + example: 123 + schema: + type: integer + tags: + - Audiences + operationId: deleteAudience + description: You can delete a single audience by its ID. + responses: + '204': + description: Audience deleted + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b1939528-98f0-4a63-a442-2cc9203fc8c7 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + '404': + description: Not found + content: + application/json: + examples: + Not found: + value: + type: error.list + request_id: b1939528-98f0-4a63-a442-2cc9203fc8c7 + errors: + - code: not_found + message: Resource Not Found + schema: + "$ref": "#/components/schemas/error" "/export/reporting_data/enqueue": post: summary: Enqueue a new reporting data export job From 7daa19d4dee430652b3ff2db8dfea5141a2f0476 Mon Sep 17 00:00:00 2001 From: kilian-tennyson Date: Tue, 26 May 2026 16:15:03 +0100 Subject: [PATCH 3/5] Add POST create, PUT update endpoints and fix audience schema MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add POST /audiences (create) with 201 response - Add PUT /audiences/{id} (update) with request body - Add create_audience_request and update_audience_request schemas - Add predicates, role_predicates, default_predicates to audience schema - Fix operationId: getAudience → retrieveAudience (matches convention) - Fix id param type: integer → string (API returns stringified IDs) - Update all examples to include predicate arrays --- descriptions/0/api.intercom.io.yaml | 312 +++++++++++++++++++++++++++- 1 file changed, 307 insertions(+), 5 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 3a41828..07794d3 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -1788,11 +1788,17 @@ paths: - type: audience id: '123' name: VIP Customers + predicates: [] + role_predicates: [] + default_predicates: [] created_at: 1717200000 updated_at: 1717200000 - type: audience id: '456' name: Enterprise Accounts + predicates: [] + role_predicates: [] + default_predicates: [] created_at: 1717200000 updated_at: 1717200000 total_count: 2 @@ -1815,6 +1821,84 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + post: + summary: Create an audience + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Audiences + operationId: createAudience + description: You can create a new audience by providing a name and optional targeting + predicates. + responses: + '201': + description: Audience created + content: + application/json: + examples: + Successful response: + value: + type: audience + id: '789' + name: Irish Users + predicates: + - attribute: geoip.country_code + type: string + comparison: eq + value: IE + role_predicates: [] + default_predicates: [] + created_at: 1717200000 + updated_at: 1717200000 + schema: + "$ref": "#/components/schemas/audience" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b1939528-98f0-4a63-a442-2cc9203fc8c7 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + '422': + description: Validation error + content: + application/json: + examples: + Validation error: + value: + type: error.list + request_id: b1939528-98f0-4a63-a442-2cc9203fc8c7 + errors: + - code: validation_error + message: Name is required + schema: + "$ref": "#/components/schemas/error" + requestBody: + required: true + content: + application/json: + schema: + "$ref": "#/components/schemas/create_audience_request" + examples: + successful: + summary: Successful response + value: + name: Irish Users + predicates: + - attribute: geoip.country_code + type: string + comparison: eq + value: IE "/audiences/{id}": get: summary: Retrieve an audience @@ -1827,12 +1911,12 @@ paths: in: path required: true description: The unique identifier of the audience to retrieve. - example: 123 + example: '123' schema: - type: integer + type: string tags: - Audiences - operationId: getAudience + operationId: retrieveAudience description: You can fetch the details of a single audience by ID. responses: '200': @@ -1845,6 +1929,9 @@ paths: type: audience id: '123' name: VIP Customers + predicates: [] + role_predicates: [] + default_predicates: [] created_at: 1717200000 updated_at: 1717200000 schema: @@ -1888,9 +1975,9 @@ paths: in: path required: true description: The unique identifier of the audience to delete. - example: 123 + example: '123' schema: - type: integer + type: string tags: - Audiences operationId: deleteAudience @@ -1926,6 +2013,105 @@ paths: message: Resource Not Found schema: "$ref": "#/components/schemas/error" + put: + summary: Update an audience + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: id + in: path + required: true + description: The unique identifier of the audience to update. + example: '123' + schema: + type: string + tags: + - Audiences + operationId: updateAudience + description: You can update an existing audience by changing its name or targeting + predicates. + responses: + '200': + description: Successful response + content: + application/json: + examples: + Successful response: + value: + type: audience + id: '123' + name: Premium Customers + predicates: + - attribute: name + type: string + comparison: eq + value: VIP + role_predicates: [] + default_predicates: [] + created_at: 1717200000 + updated_at: 1717200000 + schema: + "$ref": "#/components/schemas/audience" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b1939528-98f0-4a63-a442-2cc9203fc8c7 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + '404': + description: Not found + content: + application/json: + examples: + Not found: + value: + type: error.list + request_id: b1939528-98f0-4a63-a442-2cc9203fc8c7 + errors: + - code: not_found + message: Resource Not Found + schema: + "$ref": "#/components/schemas/error" + '422': + description: Validation error + content: + application/json: + examples: + Validation error: + value: + type: error.list + request_id: b1939528-98f0-4a63-a442-2cc9203fc8c7 + errors: + - code: validation_error + message: Name cannot be blank + schema: + "$ref": "#/components/schemas/error" + requestBody: + required: true + content: + application/json: + schema: + "$ref": "#/components/schemas/update_audience_request" + examples: + successful: + summary: Successful response + value: + name: Premium Customers + predicates: + - attribute: name + type: string + comparison: eq + value: VIP "/export/reporting_data/enqueue": post: summary: Enqueue a new reporting data export job @@ -19521,6 +19707,122 @@ components: type: integer description: The time the audience was last updated as a Unix timestamp. example: 1717200000 + predicates: + type: array + description: The predicates that define the audience targeting rules. + items: + type: object + properties: + attribute: + type: string + description: The attribute to target. + type: + type: string + description: The data type of the attribute. + comparison: + type: string + description: The comparison operator. + value: + type: string + description: The value to compare against. + example: [] + role_predicates: + type: array + description: The role-based predicates for the audience. + items: + type: object + properties: + attribute: + type: string + type: + type: string + comparison: + type: string + value: + type: string + example: [] + default_predicates: + type: array + description: The default predicates applied to the audience. + items: + type: object + properties: + attribute: + type: string + type: + type: string + comparison: + type: string + value: + type: string + example: [] + create_audience_request: + title: Create Audience Request + type: object + description: The request body for creating an audience. + required: + - name + properties: + name: + type: string + description: The name of the audience. + example: Irish Users + predicates: + type: array + description: The predicates that define audience targeting rules. + items: + type: object + properties: + attribute: + type: string + description: The attribute to target. + type: + type: string + description: The data type of the attribute. + comparison: + type: string + description: The comparison operator. + value: + type: string + description: The value to compare against. + update_audience_request: + title: Update Audience Request + type: object + description: The request body for updating an audience. At least one field must + be provided. + properties: + name: + type: string + description: The name of the audience. + example: Premium Customers + predicates: + type: array + description: The predicates that define audience targeting rules. + items: + type: object + properties: + attribute: + type: string + type: + type: string + comparison: + type: string + value: + type: string + role_predicates: + type: array + description: The role-based predicates for the audience. + items: + type: object + properties: + attribute: + type: string + type: + type: string + comparison: + type: string + value: + type: string audience_list: title: Audience List type: object From 3f7dc9ebe06951c5d1e4c6468f1f7b07ab20490e Mon Sep 17 00:00:00 2001 From: kilian-tennyson Date: Wed, 27 May 2026 09:42:28 +0100 Subject: [PATCH 4/5] Extract shared predicate schema and add readOnly to server fields - Define predicate component schema once under components/schemas - Replace 6 inline predicate definitions with $ref pointers - Add readOnly: true to id, created_at, updated_at in audience schema - Add descriptions and examples to all predicate properties Addresses Docly review findings 1-4 on PR #502. --- descriptions/0/api.intercom.io.yaml | 98 +++++++++-------------------- 1 file changed, 30 insertions(+), 68 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 07794d3..4bb2a93 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -19695,6 +19695,7 @@ components: type: string description: The unique identifier representing the audience. example: '123' + readOnly: true name: type: string description: The name of the audience. @@ -19703,58 +19704,29 @@ components: type: integer description: The time the audience was created as a Unix timestamp. example: 1717200000 + readOnly: true updated_at: type: integer description: The time the audience was last updated as a Unix timestamp. example: 1717200000 + readOnly: true predicates: type: array description: The predicates that define the audience targeting rules. items: - type: object - properties: - attribute: - type: string - description: The attribute to target. - type: - type: string - description: The data type of the attribute. - comparison: - type: string - description: The comparison operator. - value: - type: string - description: The value to compare against. + "$ref": "#/components/schemas/predicate" example: [] role_predicates: type: array description: The role-based predicates for the audience. items: - type: object - properties: - attribute: - type: string - type: - type: string - comparison: - type: string - value: - type: string + "$ref": "#/components/schemas/predicate" example: [] default_predicates: type: array description: The default predicates applied to the audience. items: - type: object - properties: - attribute: - type: string - type: - type: string - comparison: - type: string - value: - type: string + "$ref": "#/components/schemas/predicate" example: [] create_audience_request: title: Create Audience Request @@ -19771,20 +19743,7 @@ components: type: array description: The predicates that define audience targeting rules. items: - type: object - properties: - attribute: - type: string - description: The attribute to target. - type: - type: string - description: The data type of the attribute. - comparison: - type: string - description: The comparison operator. - value: - type: string - description: The value to compare against. + "$ref": "#/components/schemas/predicate" update_audience_request: title: Update Audience Request type: object @@ -19799,30 +19758,33 @@ components: type: array description: The predicates that define audience targeting rules. items: - type: object - properties: - attribute: - type: string - type: - type: string - comparison: - type: string - value: - type: string + "$ref": "#/components/schemas/predicate" role_predicates: type: array description: The role-based predicates for the audience. items: - type: object - properties: - attribute: - type: string - type: - type: string - comparison: - type: string - value: - type: string + "$ref": "#/components/schemas/predicate" + predicate: + title: Predicate + type: object + description: A targeting rule used to define audience membership criteria. + properties: + attribute: + type: string + description: The attribute to target. + example: custom_attributes.country + type: + type: string + description: The data type of the attribute. + example: string + comparison: + type: string + description: The comparison operator. + example: eq + value: + type: string + description: The value to compare against. + example: Ireland audience_list: title: Audience List type: object From 9d08b7bd82fb1806c1812e25cda1b41f24e1e345 Mon Sep 17 00:00:00 2001 From: kilian-tennyson Date: Wed, 27 May 2026 16:46:36 +0100 Subject: [PATCH 5/5] Align OpenAPI spec: remove default_predicates, add role_predicates to create - Remove default_predicates from all response examples and audience schema - Show default role_predicates values in create example - Add role_predicates to create_audience_request schema --- descriptions/0/api.intercom.io.yaml | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 4bb2a93..16d48c0 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -1790,7 +1790,6 @@ paths: name: VIP Customers predicates: [] role_predicates: [] - default_predicates: [] created_at: 1717200000 updated_at: 1717200000 - type: audience @@ -1798,7 +1797,6 @@ paths: name: Enterprise Accounts predicates: [] role_predicates: [] - default_predicates: [] created_at: 1717200000 updated_at: 1717200000 total_count: 2 @@ -1849,8 +1847,14 @@ paths: type: string comparison: eq value: IE - role_predicates: [] - default_predicates: [] + role_predicates: + - attribute: role + type: role + comparison: in + value: + - user_role + - contact_role + - visitor_role created_at: 1717200000 updated_at: 1717200000 schema: @@ -1931,7 +1935,6 @@ paths: name: VIP Customers predicates: [] role_predicates: [] - default_predicates: [] created_at: 1717200000 updated_at: 1717200000 schema: @@ -2049,7 +2052,6 @@ paths: comparison: eq value: VIP role_predicates: [] - default_predicates: [] created_at: 1717200000 updated_at: 1717200000 schema: @@ -19722,12 +19724,6 @@ components: items: "$ref": "#/components/schemas/predicate" example: [] - default_predicates: - type: array - description: The default predicates applied to the audience. - items: - "$ref": "#/components/schemas/predicate" - example: [] create_audience_request: title: Create Audience Request type: object @@ -19744,6 +19740,12 @@ components: description: The predicates that define audience targeting rules. items: "$ref": "#/components/schemas/predicate" + role_predicates: + type: array + description: The role-based predicates for the audience. When omitted, + defaults to targeting all end-user roles (user, contact, visitor). + items: + "$ref": "#/components/schemas/predicate" update_audience_request: title: Update Audience Request type: object