`delete_groups_by_id`

Changes data · you confirm first Idempotent

Calls DELETE /api/groups/{id} as the signed-in person · REST reference

Archive (soft-delete) a group

Requires execute:DeleteGroupCommand; platform staff bypass that gate, everyone else must belong to the group's org (403 GROUP_DELETE_DENIED). Referential integrity is preserved — Group.archive() is an alias of delete(), which asks the DAL for a soft delete; the node is flagged, never removed. A group with a non-zero memberCount is refused 409 GROUP_HAS_MEMBERS, saying how many members to remove first. The 200 body reports status: ARCHIVED as a literal — it is not read back from the DAL, and Group.delete() never sets the model's own status.

Arguments

Argument	Type		Description
`id`path	string (uuid)	required

Example call

A client sends this over the MCP session; Claude and other agents build it for you. The values are placeholders — the shape is real.

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_groups_by_id",
    "arguments": {
      "id": "11111111-1111-4111-8111-111111111111"
    }
  }
}

Confirmation

The client shows the person the exact request and waits. Nothing runs until they tick Make this change. See Reading and changing.

Result

On success (HTTP 200) the tool returns one text item holding the API's JSON, pretty-printed.

Archival confirmation, in the success envelope.

json

{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "status": "ARCHIVED"
  },
  "message": "Group archived successfully",
  "success": true
}

Fields

Field	Type	Description
`data`	object
`data.id`	string (uuid)
`data.status`	"ARCHIVED"	Hard-coded by the handler, not read back from the DAL.
`message`	"Group archived successfully"
`success`	true

When it fails

A failed call returns isError: true with the API's message as text. A change the person declines, or lets time out, also comes back this way and nothing changes.

400: id is not a UUID. details is an express-validator ARRAY.
403: Missing execute:DeleteGroupCommand, or the caller does not belong to the group's org (code: GROUP_DELETE_DENIED).
404: No such group. Carries code: GROUP_NOT_FOUND.
409: The group still has members (code: GROUP_HAS_MEMBERS), or it is its organization's OWNER or MEMBER group, which exist for as long as the organization does (the DAL's sentence, no code).

What the model is shown

This is the tool exactly as the server lists it in tools/list. The description starts with the REST call it makes.

json

{
  "name": "delete_groups_by_id",
  "description": "DELETE /api/groups/{id} — Requires `execute:DeleteGroupCommand`; platform staff bypass that gate, everyone else must belong to the group's org (403 `GROUP_DELETE_DENIED`). Referential integrity is preserved — `Group.archive()` is an alias of `delete()`, which asks the DAL for a soft delete; the node is flagged, never removed. A group with a non-zero `memberCount` is refused 409 `GROUP_HAS_MEMBERS`, saying how many members to remove first. The 200 body reports `status: ARCHIVED` as a literal — it is not read back from the DAL, and `Group.delete()` never sets the model's own status.\n\nThis changes data. The person is asked to confirm it before it runs, and nothing happens if they decline.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      }
    },
    "required": [
      "id"
    ]
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": true,
    "openWorldHint": false
  }
}