Available since FileRun 2026.3.0.
All the endpoints below require the admin scope, take POST requests and answer with JSON.
| Action | Target URL |
|---|---|
| Get role information | /api.php/Core/!admin/roles/info |
| Add a role | /api.php/Core/!admin/roles/add |
| Edit a role | /api.php/Core/!admin/roles/edit |
| Delete a role | /api.php/Core/!admin/roles/delete |
admin_type, admin_over and the other admin_* permissions). Sent by any other administrator, they are ignored.| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer | Yes | The role id |
The response carries the role in data, every value named the way the add and edit endpoints take it, so a role can be read, changed and sent back: id, system (1 for the predefined Guest role), owner, name, description, homefolder and the permissions listed below. The users_may_see and admin_over selections are returned in the form they are submitted in (-ALL-, or group:1|group:2|user:3).
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Unique among the roles of the same owner |
| description | string | No | |
| homefolder | string | No | The home folder assigned to the accounts holding the role. An absolute server path. Always use forward slashes as separators. |
| perms[...] | No | The permissions, see below. A permission left out is stored as 0. |
The response carries the id of the new role as data.rid.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer | Yes | The role id |
| name | string | No | |
| description | string | No | |
| homefolder | string | No | |
| perms[...] | No | The permissions, see below |
Only what is sent is written. A parameter or a permission left out leaves the role as it is, so one value can be changed without sending the whole role. A request which changes nothing is refused with "No changes were made!". Changing the home folder of a role updates the home folder of every account holding the role.
The predefined Guest role can be edited, with two limits: its name and description cannot be changed, and the permissions which are fixed for guest accounts keep their fixed values, whatever the request sends.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer | Yes | The role id |
A role assigned to at least one account cannot be deleted ("You cannot delete this role because it is assigned to 1 users."). The predefined Guest role cannot be deleted.
| Parameter | Type | Description |
|---|---|---|
| perms[admin_type] | string | simple, indep, or empty for no administrative permissions. Superuser only. |
| perms[admin_over] | string | -ALL-, or the groups the administrator manages, as group:1|group:2. Superuser only. |
| perms[admin_max_users] | integer | Superuser only. |
| perms[admin_max_guest_users] | integer | Empty for no limit. Superuser only. |
| perms[admin_homefolder_template] | string | Superuser only. |
| perms[admin_users] | boolean (1/0) | Superuser only. |
| perms[admin_roles] | boolean (1/0) | Superuser only. |
| perms[admin_notifications] | boolean (1/0) | Superuser only. |
| perms[admin_logs] | boolean (1/0) | Superuser only. |
| perms[admin_metadata] | boolean (1/0) | Superuser only. |
| perms[upload] | boolean (1/0) | |
| perms[upload_max_size] | integer | 0 for no limit |
| perms[upload_limit_types] | string | Comma delimited list of file extensions |
| perms[download] | boolean (1/0) | |
| perms[download_folders] | boolean (1/0) | |
| perms[edit_files] | boolean (1/0) | Since 2026.3.1 |
| perms[rename_move_delete] | boolean (1/0) | Since 2026.3.1. Named changes in 2026.3.0, which is still accepted as an alias. |
| perms[collections] | boolean (1/0) | Since 2026.3.1 |
| perms[starring] | boolean (1/0) | Since 2026.3.1 |
| perms[read_comments] | boolean (1/0) | |
| perms[write_comments] | boolean (1/0) | |
| perms[weblink] | boolean (1/0) | |
| perms[share] | boolean (1/0) | |
| perms[share_guests] | boolean (1/0) | |
| perms[metadata] | boolean (1/0) | |
| perms[write_metadata] | boolean (1/0) | Since 2026.3.1 |
| perms[file_history] | boolean (1/0) | |
| perms[change_auth] | boolean (1/0) | Whether the users may change their password and sign-in methods |
| perms[edit_profile] | boolean (1/0) | |
| perms[users_may_see] | string | -ALL-, or the groups and users the role may see, as group:1|group:2|user:3 |
| perms[space_quota_max] | integer | In MB. 0 for no quota. |