Role Resource

A role defines a set of permissions and visual styling that can be assigned to members within a space. Roles support gradient colors via color_from, color_via, and color_to fields.

Role Object

Field	Type	Description
`id`	`string`	The role's UUID (v7, time-ordered)
`space_id`	`string`	The UUID of the space this role belongs to
`name`	`string`	The name of the role
`color_from`	`integer?`	Gradient start color (decimal RGB)
`color_via`	`integer?`	Gradient midpoint color (decimal RGB)
`color_to`	`integer?`	Gradient end color (decimal RGB)
`flags`	`integer`	Role flags bitfield
`permissions`	`integer`	Permission bitfield (see Enums)
`hoisted`	`boolean`	Whether the role is displayed separately in the member list
`position`	`integer`	Sorting position in the role hierarchy
`created_at`	`ISO 8601`	When the role was created
`updated_at`	`ISO 8601`	When the role was last updated
`deleted_at`	`string?`	ISO 8601 soft-delete timestamp

Example

{
  "id": "019cf96a-8e6a-7f5b-c07b-5d6e7f809102",
  "space_id": "019cf96a-4a2e-7b1d-9e3f-1a2b3c4d5e6f",
  "name": "Moderator",
  "color_from": 5793266,
  "color_via": null,
  "color_to": 5793266,
  "flags": 0,
  "permissions": 1230,
  "hoisted": true,
  "position": 1,
  "created_at": "2025-11-01T10:10:00.000Z",
  "updated_at": "2026-02-10T08:45:00.000Z",
  "deleted_at": null
}