<!-- https://developers.silktide.com/v1/platform/roles/list-roles | Platform / Roles -->

# List the account's roles

`GET /v1/roles`

Returns the account's roles. Every account starts with two: Everyone
(`roleId` `1`), which every user is in and which cannot be deleted, and
Account administrators (`2`). The roles the account made follow them.

`sort` is not the same as in results queries: write `displayName:desc`, not
`displayName:d`. Anything after the colon other than `desc` sorts ascending.

## Request

### Query parameters

- `search` (string, optional): Only roles whose name or description contains this text, ignoring case.
- `sort` (string, optional): A field to sort by, such as `displayName`, then `:desc` for descending: `displayName:desc`. Left out, oldest first.
- `limit` (integer, optional, at least 1): At most this many roles.
- `perPage` (integer, optional, at least 1): Return a page of this many roles. Left out, every role.
- `page` (integer, optional, at least 1): With `perPage`, the page to return, from `1`. Defaults to `1`.

## Response

Status `200`.

- `roles` (list of objects, required): The roles. Never empty: every account has Everyone.
  - `roleId` (integer, required, at least 1): The role's id. Its assignee id is `g:` and this, such as `g:2`.
  - `displayName` (string, required): The role's name.
  - `icon` (string, required): A [Font Awesome](https://fontawesome.com/icons) icon class, such as `fas fa-globe`. Empty when it has none.
  - `colorScheme` (string, required): The color Silktide shows the role in. Empty when it has none. One of: `sky`, `emerald`, `amber`, `rose`, `orange`, `violet`, `indigo`, `cyan`, `fuchsia`, `slate`.
  - `description` (string, required): What the role is for. Can be empty.
  - `created` (integer, required): When the role was created.

## Errors

| Status | Type | When |
| --- | --- | --- |
| 401 | `NotLoggedIn` | No API key was sent, or it is not a key for this region. |
| 429 | `TooManyRequests` | Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats. |
| 503 | - | Silktide is busy. Retry after the number of seconds in the `Retry-After` header. |

## Access

- Permission: any user of the account
- Plan feature: none
- Edition: Silktide 4 and Silktide 5
- Cost: free
- Stability: stable, since 1.0.0

## Example: The built-in roles and one of the account's own

```bash
curl "https://api.eu.silktide.com/v1/roles" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY"
```

Response:

```json
{
  "roles": [
    {
      "roleId": 1,
      "displayName": "Everyone",
      "icon": "fas fa-globe",
      "colorScheme": "sky",
      "description": "All users in this Account.",
      "created": 1790216526
    },
    {
      "roleId": 2,
      "displayName": "Account administrators",
      "icon": "fas fa-crown",
      "colorScheme": "amber",
      "description": "People with total control of this account",
      "created": 1790216526
    },
    {
      "roleId": 3,
      "displayName": "Web editors",
      "icon": "fas fa-pen",
      "colorScheme": "violet",
      "description": "Fix issues on the public websites",
      "created": 1791431526
    }
  ]
}
```