A named permission set you assign to people in the workspace.
You may only grant permissions you hold yourself — a role that would exceed your own grant is refused. On update this is judged on the delta, so permissions the role already had can be carried forward.
The four built-in roles (owner, manager, regular, client) report editable: false: they accept a change to initialScreen and nothing else, and they cannot be deleted.
List Roles
List roles. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 3 fields. Ordered by name unless you pass sort.
Required scope: roles:read
query Parameters
sortField to sort by. Prefix with - for descending (-createdAt); a createdAt:desc / createdAt:asc suffix works too, but never both markers at once. Default: name.
cursorOpaque cursor for the next page (the envelope nextCursor).
limitItems per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow nextCursor instead of assuming one page held everything.
includeTotalWhen true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination.
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
name[eq]Filter where name equals.
name[contains]Filter where name contains.
name[startsWith]Filter where name starts with.
editable[eq]Filter where editable equals.
createdAt[gt]Filter where createdAt is greater than.
createdAt[gte]Filter where createdAt is greater than or equal to.
createdAt[lt]Filter where createdAt is less than.
createdAt[lte]Filter where createdAt is less than or equal to.
List Roles › Responses
OK
The page of results.
totalTotal rows matching the query (across pages).
limithasMorenextCursorOpaque cursor for the next page; null on the last page.
Create Role
Create a Role. Server-assigned fields are ignored if sent.
Required scope: roles:write
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Create Role › Request Body
nameThe role's name, unique within the workspace. Cannot be owner, manager, regular or client — those four are built in.
permissionsThe permissions this role grants. Send names; an unknown name is rejected with 400, and omitting the field (or sending []) means the role grants nothing. You may only grant permissions you hold yourself; on update this is judged on the delta, so permissions the role already had can be carried forward untouched.
initialScreenThe screen members holding this role land on when they open the workspace.
Create Role › Responses
Created
idUnique identifier — an opaque string; never parse or generate one.
createdAtCreation timestamp.
nameThe role's name, unique within the workspace. Cannot be owner, manager, regular or client — those four are built in.
editableFalse for the four built-in roles (owner, manager, regular, client). Those cannot be renamed, re-permissioned or deleted — only initialScreen may change.
permissionsThe permissions this role grants. Send names; an unknown name is rejected with 400, and omitting the field (or sending []) means the role grants nothing. You may only grant permissions you hold yourself; on update this is judged on the delta, so permissions the role already had can be carried forward untouched.
initialScreenThe screen members holding this role land on when they open the workspace.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
The related Actor, present only when you pass ?expand=createdByActor.
Get Role
Retrieve a single Role by id.
Required scope: roles:read
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Role.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Get Role › Responses
OK
idUnique identifier — an opaque string; never parse or generate one.
createdAtCreation timestamp.
nameThe role's name, unique within the workspace. Cannot be owner, manager, regular or client — those four are built in.
editableFalse for the four built-in roles (owner, manager, regular, client). Those cannot be renamed, re-permissioned or deleted — only initialScreen may change.
permissionsThe permissions this role grants. Send names; an unknown name is rejected with 400, and omitting the field (or sending []) means the role grants nothing. You may only grant permissions you hold yourself; on update this is judged on the delta, so permissions the role already had can be carried forward untouched.
initialScreenThe screen members holding this role land on when they open the workspace.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
The related Actor, present only when you pass ?expand=createdByActor.
Delete Role
Permanently delete this Role. This cannot be undone. There are four possible outcomes. A built-in role is refused with 403. A role still held by an active member is refused with 409 — reassign them first. On success, anyone previously removed from the team who still held the role is moved to regular; if the workspace has no regular role, the delete is refused with 409 instead.
Required scope: roles:delete
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Role.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Delete Role › Responses
No Content
Update Role
Partially update a Role. Only the fields you send are changed.
Required scope: roles:write
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Role.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Update Role › Request Body
nameThe role's name, unique within the workspace. Cannot be owner, manager, regular or client — those four are built in.
permissionsThe permissions this role grants. Send names; an unknown name is rejected with 400, and omitting the field (or sending []) means the role grants nothing. You may only grant permissions you hold yourself; on update this is judged on the delta, so permissions the role already had can be carried forward untouched.
initialScreenThe screen members holding this role land on when they open the workspace.
expectedUpdatedAtOptional concurrency guard: the updatedAt you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh updatedAt.
Update Role › Responses
OK
idUnique identifier — an opaque string; never parse or generate one.
createdAtCreation timestamp.
nameThe role's name, unique within the workspace. Cannot be owner, manager, regular or client — those four are built in.
editableFalse for the four built-in roles (owner, manager, regular, client). Those cannot be renamed, re-permissioned or deleted — only initialScreen may change.
permissionsThe permissions this role grants. Send names; an unknown name is rejected with 400, and omitting the field (or sending []) means the role grants nothing. You may only grant permissions you hold yourself; on update this is judged on the delta, so permissions the role already had can be carried forward untouched.
initialScreenThe screen members holding this role land on when they open the workspace.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
The related Actor, present only when you pass ?expand=createdByActor.
Search Roles
Full-text ranked search across roles. Ranked by relevance; pages are capped at 200 results. Filterable by 3 fields.
Required scope: roles:read
query Parameters
qFull-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.
cursorOpaque cursor for the next page (the envelope nextCursor).
limitItems per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow nextCursor instead of assuming one page held everything.
includeTotalWhen true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination.
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
name[eq]Filter where name equals.
name[contains]Filter where name contains.
name[startsWith]Filter where name starts with.
editable[eq]Filter where editable equals.
createdAt[gt]Filter where createdAt is greater than.
createdAt[gte]Filter where createdAt is greater than or equal to.
createdAt[lt]Filter where createdAt is less than.
createdAt[lte]Filter where createdAt is less than or equal to.
Search Roles › Responses
OK
The page of results.
totalTotal rows matching the query (across pages).
limithasMorenextCursorOpaque cursor for the next page; null on the last page.