local universe

System Roles

Roles define sets of permissions that can be assigned to system members. Each system has an @everyone role by default, and you can create additional roles to manage access.

The system role model

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the role.

  • Name
    system_id
    Type
    string
    Description

    The ID of the system this role belongs to.

  • Name
    name
    Type
    string
    Description

    The name of the role.

  • Name
    color
    Type
    integer
    Description

    Integer representation of the role color (hex).

  • Name
    hoist
    Type
    boolean
    Description

    Whether this role is displayed separately in the member list.

  • Name
    icon
    Type
    string?
    Description

    URL to the role icon.

  • Name
    unicode_emoji
    Type
    string?
    Description

    Unicode emoji for the role.

  • Name
    position
    Type
    integer
    Description

    Position of the role in the hierarchy (higher = more authority).

  • Name
    permissions
    Type
    string
    Description

    Permission bitfield serialized as a string. See Permissions.

  • Name
    managed
    Type
    boolean
    Description

    Whether this role is managed by an integration.

  • Name
    mentionable
    Type
    boolean
    Description

    Whether this role can be mentioned by anyone.

  • Name
    flags
    Type
    integer
    Description

    Role flags bitfield. See role flags below.

  • Name
    created_at
    Type
    timestamp
    Description

    When the role was created.

  • Name
    updated_at
    Type
    timestamp?
    Description

    When the role was last updated.

Role flags

ValueNameDescription
1IN_PROMPTRole is included in AI prompt context
GET/v1/systems/:systemId/roles

List roles

Returns all roles in a system.

Request

GET
/v1/systems/1344387816333352652/roles
curl https://api.localuniverse.io/v1/systems/1344387816333352652/roles \
  -H "Authorization: Bearer {token}"
POST/v1/systems/:systemId/roles

Create a role

Optional attributes

  • Name
    name
    Type
    string
    Description

    Name of the role. Defaults to "new role".

  • Name
    permissions
    Type
    string
    Description

    Permission bitfield as a string.

  • Name
    color
    Type
    integer
    Description

    Role color as an integer.

  • Name
    hoist
    Type
    boolean
    Description

    Whether to display separately in the member list.

  • Name
    mentionable
    Type
    boolean
    Description

    Whether the role is mentionable.

Request

POST
/v1/systems/1344387816333352652/roles
curl -X POST https://api.localuniverse.io/v1/systems/1344387816333352652/roles \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Moderator", "color": 3447003, "permissions": "1071698660929"}'
PATCH/v1/systems/:systemId/roles

Update role positions

Batch update the positions of roles in the hierarchy. Send an array of objects with id and position.

Request

PATCH
/v1/systems/1344387816333352652/roles
curl -X PATCH https://api.localuniverse.io/v1/systems/1344387816333352652/roles \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '[{"id": "role1", "position": 1}, {"id": "role2", "position": 2}]'
GET/v1/systems/:systemId/roles/:roleId

Get a role

Retrieve a single role by its ID.

Request

GET
/v1/systems/1344387816333352652/roles/1344387816333355555
curl https://api.localuniverse.io/v1/systems/1344387816333352652/roles/1344387816333355555 \
  -H "Authorization: Bearer {token}"
PATCH/v1/systems/:systemId/roles/:roleId

Update a role

Optional attributes

  • Name
    name
    Type
    string
    Description

    New name for the role.

  • Name
    permissions
    Type
    string
    Description

    Updated permission bitfield.

  • Name
    color
    Type
    integer
    Description

    New color.

  • Name
    hoist
    Type
    boolean
    Description

    Whether to hoist the role.

  • Name
    mentionable
    Type
    boolean
    Description

    Whether the role is mentionable.

Request

PATCH
/v1/systems/1344387816333352652/roles/1344387816333355555
curl -X PATCH https://api.localuniverse.io/v1/systems/1344387816333352652/roles/1344387816333355555 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Senior Mod", "color": 15844367}'
DELETE/v1/systems/:systemId/roles/:roleId

Delete a role

Permanently delete a role from the system.

Request

DELETE
/v1/systems/1344387816333352652/roles/1344387816333355555
curl -X DELETE https://api.localuniverse.io/v1/systems/1344387816333352652/roles/1344387816333355555 \
  -H "Authorization: Bearer {token}"

Was this page helpful?