> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rootly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Problem Roles API

> List your organization's problem roles and assign or unassign them on a Rootly problem with the API.

Use these endpoints to list your organization's problem roles and assign them to users on a problem.

> [!NOTE]
>
> **Beta** — Problem Management is enabled per organization. If it isn't enabled for yours, every endpoint on this page returns `404`. Contact your account team to request access.

Call these endpoints with an [API key](https://docs.rootly.com/api-reference/overview.md#how-to-generate-an-api-key). OAuth 2.0 access tokens are denied whatever their scope, including `ir.all` and `all`.

## Overview

A **problem role**, such as Problem Manager, describes a responsibility on a [problem](https://docs.rootly.com/api-reference/problem-management/problems.md). Roles are defined once for your organization and assigned to users problem by problem:

| Operation | Endpoint |
| - | - |
| List problem roles | `GET /v1/problem_roles` |
| Read one problem role | `GET /v1/problem_roles/{id}` |
| List a problem's role assignments | `GET /v1/problems/{problem_id}/role_assignments` |
| Assign a role | `POST /v1/problems/{problem_id}/role_assignments` |
| Remove a role assignment | `DELETE /v1/problems/{problem_id}/role_assignments/{id}` |

Requests and responses use JSON:API with `Content-Type: application/vnd.api+json`. Roles use the `problem_roles` resource type and assignments use `problem_role_assignments`. The API reads roles but doesn't create or edit them.

Your role's **Problems** permissions control access: `read` to list roles and assignments, and `update` to assign roles and remove assignments. A user who already holds a role on a problem can also manage role assignments on that problem.

***

## Listing Problem Roles

`GET /v1/problem_roles` is paginated with `page[number]` and `page[size]`, and sorted by `position` by default.

| Filter | Matches |
| - | - |
| `filter[name]` | Role name |
| `filter[slug]` | Role slug |
| `filter[enabled]` | `true` for roles that can be assigned, `false` for disabled ones |

Each filter accepts one value or a comma-separated list, and also supports `[eq]`, `[not_eq]`, `[in]`, and `[not_in]`.

`sort` accepts `name`, `slug`, `position`, `enabled`, `created_at`, and `updated_at`. Prefix with `-` for descending order.

```json theme={null}
{
  "data": [
    {
      "id": "PROBLEM_ROLE_ID",
      "type": "problem_roles",
      "attributes": {
        "name": "Problem Manager",
        "slug": "problem-manager",
        "summary": "Owns the problem through to resolution",
        "description": null,
        "position": 1,
        "enabled": true,
        "created_at": "2026-10-20T14:02:11.000-07:00",
        "updated_at": "2026-10-20T14:02:11.000-07:00"
      }
    }
  ]
}
```

***

## Assigning a Role

`POST /v1/problems/{problem_id}/role_assignments` assigns a role to a user on a problem. Both attributes are required.

```bash theme={null}
curl --request POST \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Bearer YOUR-API-KEY' \
--url https://api.rootly.com/v1/problems/PROBLEM_ID/role_assignments \
--data '{
  "data": {
    "type": "problem_role_assignments",
    "attributes": {
      "problem_role_id": "PROBLEM_ROLE_ID",
      "user_id": 1234
    }
  }
}'
```

**problem\_role\_id** `string` *required*

The role to assign. It must be an enabled role in your organization.

**user\_id** `integer` *required*

The user to assign. They must be a member of your organization.

The response is `201` with the new assignment. The assigned user is notified and starts following the problem. A user can hold several roles on the same problem, but assigning the same role to the same user twice returns `422`.

The response includes the `problem_role` and the `user` it refers to. Either is `null` when the caller doesn't have permission to read it.

When a problem is created, its creator is assigned the **Problem Manager** role automatically if that role is enabled.

***

## Listing and Removing Assignments

`GET /v1/problems/{problem_id}/role_assignments` lists a problem's assignments, oldest first, paginated with `page[number]` and `page[size]`.

`DELETE /v1/problems/{problem_id}/role_assignments/{id}` removes one assignment and returns it with `200`. An assignment ID from another problem returns `404`.

***

## Errors

| Status | When |
| - | - |
| `401` | The API key is missing or invalid |
| `404` | The role, problem, or assignment doesn't exist, the caller can't access it, or Problem Management isn't enabled. A caller who can't update the problem gets `404` when assigning or removing a role. |
| `422` | The role is disabled or from another organization, the user isn't a member, or the user already holds that role on the problem |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.