`get_roles_by_id`

Read-only

Calls GET /api/roles/{id} as the signed-in person · REST reference

Get one role

Same read scope as GET /api/roles: a role of an organization in the caller's org tree, or a role of no organization for platform staff, and 404 — the same 404 as a role that does not exist — for any other role. Unlike the list route, this one does NOT filter archived roles — an ARCHIVED role is returned normally. Same Role model projection as the list route, with ISO-8601 timestamps.

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": "get_roles_by_id",
    "arguments": {
      "id": "11111111-1111-4111-8111-111111111111"
    }
  }
}

Result

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

The role, in the success envelope.

json

{
  "data": {
    "createdAt": "2026-01-15T12:00:00Z",
    "groupCount": 1,
    "id": "11111111-1111-4111-8111-111111111111",
    "isSystem": true,
    "metadata": {},
    "name": "string",
    "permissions": [
      "string"
    ],
    "status": "ACTIVE",
    "createdBy": "11111111-1111-4111-8111-111111111111",
    "description": "string",
    "updatedAt": "2026-01-15T12:00:00Z"
  },
  "success": true
}

Fields

Field	Type	Description
`data`	object
`data.createdAt`	string (date-time)
`data.createdBy`	string (uuid) \| null
`data.description`	string \| null
`data.groupCount`	integer
`data.id`	string (uuid)
`data.isSystem`	boolean
`data.metadata`	object
`data.name`	string
`data.permissions`	array of string
`data.status`	"ACTIVE" \| "INACTIVE" \| "ARCHIVED"
`data.updatedAt`	string (date-time) \| null
`success`	true

When it fails

A failed call returns isError: true with the API's message as text.

400: id is not a UUID. details is an express-validator ARRAY here.
403: Authenticated, but the caller holds none of the required permissions.
404: No such role. Carries code: ROLE_NOT_FOUND.

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": "get_roles_by_id",
  "description": "GET /api/roles/{id} — Same read scope as `GET /api/roles`: a role of an organization in the caller's org tree, or a role of no organization for platform staff, and 404 — the same 404 as a role that does not exist — for any other role. Unlike the list route, this one does NOT filter archived roles — an ARCHIVED role is returned normally. Same `Role` model projection as the list route, with ISO-8601 timestamps.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      }
    },
    "required": [
      "id"
    ]
  },
  "annotations": {
    "readOnlyHint": true,
    "openWorldHint": false
  }
}