From 7323d01b49469fb8c93453fe94384abb79b0ac89 Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Tue, 25 Aug 2026 12:11:07 +0100 Subject: [PATCH 1/3] Document DELETE /admins/remove for Preview The endpoint has shipped and been callable for a long time (app/controllers/api/v3/admins_controller.rb#remove in intercom/intercom) but was never added to the spec. Adds the path, parameters, and coded error responses actually returned by the controller. No behaviour change. --- descriptions/0/api.intercom.io.yaml | 155 ++++++++++++++++++++++++++++ 1 file changed, 155 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index a49d7dd..be42dc1 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -623,6 +623,161 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + "/admins/remove": + delete: + summary: Remove an admin + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: admin_id + in: query + required: true + description: The unique identifier of the admin to remove. + example: 123 + schema: + type: integer + - name: reassign_messages_admin_id + in: query + required: false + description: The unique identifier of a human admin to reassign the removed + admin's auto-message ownership to. + example: 456 + schema: + type: integer + - name: reassign_owner_admin_id + in: query + required: false + description: The unique identifier of a human admin to reassign the removed + admin's ownership (of users and leads) to. + example: 456 + schema: + type: integer + - name: reassign_articles_author_id + in: query + required: false + description: The unique identifier of a human admin to reassign the removed + admin's article authorship to. + example: 456 + schema: + type: integer + - name: reassign_conversations_admin_id + in: query + required: false + description: The unique identifier of a human admin with Inbox access to + reassign the removed admin's conversation replies to. Pass `0` to leave + conversations unassigned. + example: 456 + schema: + type: integer + - name: reassign_replies_teams + in: query + required: false + description: A list of teams and the admin each team's conversation replies + should be reassigned to. + schema: + type: array + items: + type: object + properties: + team_id: + type: integer + assignee_id: + type: integer + tags: + - Admins + operationId: removeAdmin + description: |- + You can remove a single admin (teammate) from your workspace. + + This removes the admin's access to the workspace and reassigns their + work — auto-messages, ownership, article authorship, and conversation + replies — to the admins named by the `reassign_*` parameters. + responses: + '200': + description: Successful response + content: + application/json: + examples: + Successful response: + value: + id: '123' + object: admin + removed: 'true' + schema: + type: object + properties: + id: + type: string + description: The unique identifier of the removed admin. + object: + type: string + enum: [admin] + removed: + type: string + description: Whether the admin was removed. Returned as the + string `"true"`. + enum: ['true'] + '404': + description: Admin not found + content: + application/json: + examples: + Admin not found: + value: + type: error.list + request_id: efcd0531-798b-4c22-bccd-68877ed7faa4 + errors: + - code: admin_not_found + message: "Admin for admin_id not found" + schema: + "$ref": "#/components/schemas/error" + '405': + description: Method Not Allowed. Returned when `admin_id`, or one of + the `reassign_*_admin_id` parameters, refers to a bot or a team rather + than a human admin. + content: + application/json: + examples: + Method Not Allowed: + value: + type: error.list + errors: + - code: action_forbidden + message: "This method is not allowed for this type of Admin + for admin_id" + schema: + "$ref": "#/components/schemas/error" + '403': + description: Forbidden. Returned when `reassign_conversations_admin_id` + refers to an admin without Inbox access for the workspace. + content: + application/json: + examples: + Forbidden: + value: + type: error.list + errors: + - code: action_forbidden + message: "The admin for reassign_conversations_admin_id does + not have Inbox access permissions" + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: e76b2df0-2413-4215-8a5a-b5f6ebd4e642 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" "/ai/content_import_sources": get: summary: List content import sources From 721e2ca8d2c0f4a4cec040f981b0cb66c5b5956d Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Tue, 25 Aug 2026 14:36:26 +0100 Subject: [PATCH 2/3] Address review: state required scope, add missing examples --- descriptions/0/api.intercom.io.yaml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index be42dc1..b610dcb 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -683,13 +683,16 @@ paths: properties: team_id: type: integer + example: 789 assignee_id: type: integer + example: 456 tags: - Admins operationId: removeAdmin description: |- You can remove a single admin (teammate) from your workspace. + Requires the `remove_admins` OAuth scope. This removes the admin's access to the workspace and reassigns their work — auto-messages, ownership, article authorship, and conversation @@ -711,14 +714,17 @@ paths: id: type: string description: The unique identifier of the removed admin. + example: '123' object: type: string enum: [admin] + example: admin removed: type: string description: Whether the admin was removed. Returned as the string `"true"`. enum: ['true'] + example: 'true' '404': description: Admin not found content: From e434ae3deb193e8502fe37b1f4ea86ca1946f5bd Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Wed, 26 Aug 2026 15:45:35 +0100 Subject: [PATCH 3/3] Mark reassign_* params required on DELETE /admins/remove MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review feedback on #633: the controller rejects a nil for every reassignment param, so `required: false` advertised a call shape that returns 404. The pre-flight checks at app/controllers/api/v3/admins_controller.rb:72-75 run before Permissions::Delete and reject all four. reassign_replies_teams stays optional — it has no pre-flight check. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index b610dcb..6e9ca59 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -640,7 +640,7 @@ paths: type: integer - name: reassign_messages_admin_id in: query - required: false + required: true description: The unique identifier of a human admin to reassign the removed admin's auto-message ownership to. example: 456 @@ -648,7 +648,7 @@ paths: type: integer - name: reassign_owner_admin_id in: query - required: false + required: true description: The unique identifier of a human admin to reassign the removed admin's ownership (of users and leads) to. example: 456 @@ -656,7 +656,7 @@ paths: type: integer - name: reassign_articles_author_id in: query - required: false + required: true description: The unique identifier of a human admin to reassign the removed admin's article authorship to. example: 456 @@ -664,7 +664,7 @@ paths: type: integer - name: reassign_conversations_admin_id in: query - required: false + required: true description: The unique identifier of a human admin with Inbox access to reassign the removed admin's conversation replies to. Pass `0` to leave conversations unassigned.