Roles
The
roles
namespace provides API methods to retrieve all or specific user roles. This page covers the following API methods:

Returns all roles. Requires site admin access.
Parameters
Schema
![]() page integer
Number of page to return (default: first page) |
![]() per_page integer
Maximum number of roles to return (supported: 15 , 25 , 50 , 100 ; default: 100 ) |
![]() expands string
Comma-separated list of expands to return. |
"page": {
"type": "integer",
"format": "int64",
"description": "Number of page (default: first page)."
},
"per_page": {
"type": "integer",
"format": "int64",
"enum": [
15,
25,
50,
100
],
"description": "Maximum number of items to return per page (default: 100)."
},
"expands": {
"type": "string",
"description": "Comma-separated list of expands to return."
}
This method supports the following expands so you can automatically include additional information for referenced objects:
users
GET /api/v1/roles
200 OK
{
"page": 1,
"prev_page": null,
"next_page": null,
"last_page": 1,
"per_page": 100,
"total": 4,
"result": [
{
"id": 1,
"name": "Read-only",
"permissions": 0,
"is_default": false,
"created_at": "..",
"created_by": 2,
"updated_at": null,
"updated_by": null
},
{
"id": 2,
"name": "Tester",
"permissions": ..,
"is_default": false,
"created_at": "..",
"created_by": 2,
"updated_at": null,
"updated_by": null
},
..
],
"expands": {
..
}
}
// Get first 100 roles
GET /api/v1/roles
// Get second result page (pagination)
GET /api/v1/roles?page=2
// Get roles and include user details
GET /api/v1/roles?expands=users

Returns a single role. Requires site admin access.
![]() role_id id required
ID of the role to return. |
Parameters
Schema
![]() expands string
Comma-separated list of expands to return. |
"expands": {
"type": "string",
"description": "Comma-separated list of expands to return."
}
This method supports the following expands so you can automatically include additional information for referenced objects:
users
GET /api/v1/roles/1
200 OK
{
"result": {
"id": 1,
"name": "Read-only",
"permissions": 0,
"is_default": false,
"created_at": "..",
"created_by": 2,
"updated_at": null,
"updated_by": null
},
"expands": {
..
}
}
// Get the role with ID 5
GET /api/v1/roles/5
// Get a role and include user details
GET /api/v1/roles/1?expands=users
Last modified 6mo ago