---
title: "List roles"
method: GET
path: "/roles"
tags: ["Roles and members"]
---

# List roles

`GET /roles`

## Request

- Base URL: `https://api.primitive.dev/v1`
- URL: `https://api.primitive.dev/v1/roles`
- Auth: HTTP bearer

Every role in the organization (built-in, template copies and custom roles), with how many members and groups hold each, the templates not yet copied, and whether roles can be assigned now. Any person (a session or OAuth token); API keys are refused.

## Response `200`

List roles

- object
  - `success` true, required
  - `data` ListRolesResult, required
    - `roles` object[], required
      - `id` string, required
      - `key` string, required
      - `kind` 'builtin' | 'template' | 'custom', required
      - `name` string, required
      - `description` string, nullable, required
      - `permissions` string[], required
      - `mail_scope` unknown, required
      - `version` number, required
      - `catalog_version` string, nullable, required
      - `predates_catalog` boolean, required
    - `templates` object[], required
      - `key` string, required
      - `name` string, required
      - `description` string, required
      - `permissions` string[], required
    - `assignment` object, required
      - `available` boolean, required
      - `reason` string, nullable, required

## Other responses

- `401`: Invalid or missing API key
- `403`: Authenticated caller lacks permission for the operation
- `404`: feature_disabled: the feature is not enabled for the organization; or not_found: the item the path names does not exist.
- `409`: conflict: the item changed while you edited it, or a member was removed and added back. Look again, then retry.
- `429`: Rate limit exceeded. The `ratelimit-*` headers describe the limiter that rejected this request, with its own limit and window, not the API budget that successful responses report. A limiter that reports only a wait sends `Retry-After` alone.

---

[API](https://skmtc.dev/primitive/apis/primitive-api.md) - [All operations](https://skmtc.dev/primitive/apis/primitive-api/llms.txt) - [OpenAPI document](https://skmtc.dev/primitive/apis/primitive-api/revisions/bce409c97acb?raw)