From 0afc5370dc44b3278d41c3452ff236ca57d29034 Mon Sep 17 00:00:00 2001 From: Ryadh Taher Date: Tue, 18 Aug 2026 22:22:44 +0100 Subject: [PATCH 1/2] Document writing team priority levels on the Preview update endpoint The update_team_members_request schema listed admin_ids alone and said the priority levels could not be set. They can now, so the request gains an optional admin_priority_level of the same shape the team response returns, and the description covers the rules a caller needs: which teammates a payload has to name, what happens to one it leaves out, and when a secondary member is refused. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index e27db92..35fade8 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -40695,11 +40695,15 @@ components: change one of them returns a 400 rather than being ignored, as does any field a team does not have. - On a team that balances assignment across its members, teammates already on the - team keep their current priority level and teammates being added join as primary - members. Priority levels cannot be set here, so `admin_priority_level` follows - from `admin_ids`: it is accepted when sent back unchanged and returns a 400 when - the request tries to change it. + On a team that balances assignment across its members, `admin_priority_level` + sets which teammates take work first. It is optional, and names only the + teammates whose level the request is setting: a teammate it leaves out keeps the + level they already have, and one joining the team without a level named becomes a + primary member. A level named for a teammate the request removes is ignored, so a + team read from the API can still be sent back whole with only `admin_ids` changed. + An id belonging to neither the team nor `admin_ids` is a mistake and returns a 400, + as does naming the same id at both levels. Only a team that balances assignment can + have secondary members, so naming one on any other team returns a 400. type: object title: Update Team Members Request Payload properties: @@ -40712,6 +40716,8 @@ components: example: - 493881 - 493882 + admin_priority_level: + "$ref": "#/components/schemas/admin_priority_level" required: - admin_ids update_ticket_request: From 3a49063be9f0638c17f1f9f17090783abc5c9185 Mon Sep 17 00:00:00 2001 From: Ryadh Taher Date: Thu, 20 Aug 2026 09:33:23 +0100 Subject: [PATCH 2/2] Answer the review and catch the spec up with what shipped - Qualify the duplicate-level clause: naming a teammate at both levels is refused unless the team really holds them at both, which a read reports and sending it back settles at a single level. - Give the request its own priority-level schema so the generated example is a body a caller can send, rather than one built from the response-side ids. - Say what a team that does not balance assignment does: secondary members are refused, primary ones are accepted but neither reported back nor used. - Back-port distribution_method and assignment_limit from 2.16, which Preview was missing even though the API returns them, so a caller can tell which kind of team they have. - Correct the read-only 400 example, which still named admin_ids alone, and add the two priority-level 400s the endpoint actually returns. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 107 +++++++++++++++++++++++----- 1 file changed, 88 insertions(+), 19 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 35fade8..3bcd5f4 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -21317,6 +21317,11 @@ paths: admin_ids: - 493881 - 493882 + admin_priority_level: + primary_admin_ids: + - 493881 + secondary_admin_ids: + - 493882 schema: "$ref": "#/components/schemas/update_team_members_request" responses: @@ -21333,6 +21338,13 @@ paths: admin_ids: - 493881 - 493882 + admin_priority_level: + primary_admin_ids: + - 493881 + secondary_admin_ids: + - 493882 + assignment_limit: 10 + distribution_method: load_balanced schema: "$ref": "#/components/schemas/team" '400': @@ -21353,8 +21365,24 @@ paths: request_id: 1c9d6f0b-7a24-4b8e-9f31-3e5a2c6b8d70 errors: - code: parameter_invalid - message: Only admin_ids can be updated on a team, but the request - changed name + message: Only admin_ids and admin_priority_level can be updated + on a team, but the request changed name + Priority level names someone off the team: + value: + type: error.list + request_id: 0d3a7e51-9c62-4b18-8f74-6a2e5c1b9d38 + errors: + - code: parameter_invalid + message: admin_priority_level names 814865, which is on neither + the team nor admin_ids + Priority level given twice: + value: + type: error.list + request_id: 7f4b2a90-1e58-4c63-9a07-3d6f8b2e5c14 + errors: + - code: parameter_invalid + message: admin_priority_level gives 493881 more than one priority + level schema: "$ref": "#/components/schemas/error" '403': @@ -26909,6 +26937,29 @@ components: - 814865 items: type: integer + admin_priority_level_request: + title: Admin Priority Level Request + type: object + nullable: true + description: The priority levels to set, naming only the teammates whose level + is being set + properties: + primary_admin_ids: + type: array + description: The ids of the teammates to make primary members of the team + nullable: true + example: + - 493881 + items: + type: integer + secondary_admin_ids: + type: array + description: The ids of the teammates to make secondary members of the team + nullable: true + example: + - 493882 + items: + type: integer admin_reply_conversation_request: title: Admin Reply type: object @@ -39334,6 +39385,16 @@ components: type: integer admin_priority_level: "$ref": "#/components/schemas/admin_priority_level" + assignment_limit: + type: integer + nullable: true + description: The assignment limit for the team. This field is only present when the team's distribution type is load balanced. + example: 10 + distribution_method: + type: string + nullable: true + description: Describes how assignments are distributed among the team members + example: "round_robin" team_list: title: Team List type: object @@ -40688,22 +40749,30 @@ components: the request completes, not a list of changes to apply. Any teammate currently on the team but absent from `admin_ids` is removed. - Membership is the only part of a team this endpoint writes, and the request is - read from the body: a parameter sent in the query string is rejected rather than - applied. A team read from the API can be sent back whole, since the other fields - of the representation are accepted as long as they are unchanged. Trying to - change one of them returns a 400 rather than being ignored, as does any field a - team does not have. - - On a team that balances assignment across its members, `admin_priority_level` - sets which teammates take work first. It is optional, and names only the - teammates whose level the request is setting: a teammate it leaves out keeps the - level they already have, and one joining the team without a level named becomes a - primary member. A level named for a teammate the request removes is ignored, so a - team read from the API can still be sent back whole with only `admin_ids` changed. - An id belonging to neither the team nor `admin_ids` is a mistake and returns a 400, - as does naming the same id at both levels. Only a team that balances assignment can - have secondary members, so naming one on any other team returns a 400. + The team's members and their priority levels are the only parts of a team this + endpoint writes, and the request is read from the body: a parameter sent in the + query string is rejected rather than applied. A team read from the API can be sent + back whole, since the other fields of the representation are accepted as long as + they are unchanged. Trying to change one of them returns a 400 rather than being + ignored, as does any field a team does not have. + + `admin_priority_level` sets which teammates take work first. It is optional, and + names only the teammates whose level the request is setting: a teammate it leaves + out keeps the level they already have, and one joining the team without a level + named becomes a primary member. A level named for a teammate the request removes is + ignored, so a team read from the API can still be sent back whole with only + `admin_ids` changed. + + Naming an id that is on neither the team nor `admin_ids` returns a 400. So does + naming the same id at both levels, unless the team really does hold that teammate + at both: a read reports that shape, and sending it back settles them at a single + level rather than being refused. + + Only a team whose `distribution_method` is `load_balanced` can have secondary + members, so `secondary_admin_ids` returns a 400 on any other team. + `primary_admin_ids` is accepted on every team, but a team that does not balance + assignment does not report `admin_priority_level` back and does not use the levels + to decide who work goes to. type: object title: Update Team Members Request Payload properties: @@ -40717,7 +40786,7 @@ components: - 493881 - 493882 admin_priority_level: - "$ref": "#/components/schemas/admin_priority_level" + "$ref": "#/components/schemas/admin_priority_level_request" required: - admin_ids update_ticket_request: