Roles

Role management endpoints.

Base path: /api/v1/roles

---

List Roles

GET /api/v1/roles

Required permission: roles:read

Query parameters

Parameter	Type	Default	Description
page	int	1	Page number
per_page	int	20	Items per page
name	string	—	Filter by name (case-insensitive)
description	string	—	Filter by description (case-insensitive)
permission_ids	string	—	Filter by permission ids

Response 200 OK

{
  "data": [
    {
      "id": "uuid",
      "name": "admin",
      "description": "Full access to everything",
      "permissions": [
        {
          "id": "uuid",
          "name": "users:read",
          "description": "View users",
          "created_at": "2026-01-01T00:00:00Z",
          "updated_at": null
        }
      ],
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": null
    }
  ],
  "pagination": {
    "total": 4,
    "page": 1,
    "per_page": 20,
    "pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

---

Create Role

POST /api/v1/roles

Required permission: roles:create

Request body

{
  "name": "editor",
  "description": "Can manage content",
  "permission_ids": [
    "uuid-of-permission-1",
    "uuid-of-permission-2"
  ]
}

Field	Type	Required	Constraints
name	string	✅	2–50 characters
description	string	❌	Max 255 characters
permission_ids	UUID array	❌	Must exist in DB

Response 201 Created — full RoleResponse object.

Errors

Status	Description
400	One or more permissions not found
409	Role name already exists

---

Get Role

GET /api/v1/roles/{id}

Required permission: roles:read

Response 200 OK — full RoleResponse object.

Errors

Status	Description
404	Role not found

---

Update Role

PATCH /api/v1/roles/{id}

Required permission: roles:update

Request body — all fields optional

{
  "name": "senior-editor",
  "description": "Updated description",
  "permission_ids": ["uuid-1", "uuid-2"]
}

Warning

If permission_ids is provided, it replaces all existing permission assignments for the role.

Response 200 OK — updated RoleResponse object.

---

Add Permissions

Adds permissions to a role without affecting existing ones.

POST /api/v1/roles/{id}/permissions

Required permission: roles:update

Request body

{
  "permission_ids": ["uuid-1", "uuid-2"]
}

Response 200 OK — updated RoleResponse object.

Errors

Status	Description
400	One or more permissions not found
404	Role not found

---

Remove Permissions

Removes specific permissions from a role.

DELETE /api/v1/roles/{id}/permissions

Required permission: roles:update

Request body

{
  "permission_ids": ["uuid-1", "uuid-2"]
}

Response 200 OK — updated RoleResponse object.

---

Delete Role

Soft-deletes a role.

DELETE /api/v1/roles/{id}

Required permission: roles:delete

Response 204 No Content

Errors

Status	Description
404	Role not found