Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Brix Roles API
version: '1'
summary: 'Control plane for Brix digital signage: screens, content, playlists, schedules, casts and emergencies.'
description: 'Generated from the route table the API actually mounts
(`apps/api/routes.snapshot.json`), the description each route is required to
carry (`tests/contracts/route-registry.json`), and request/response schemas
(`apps/api/src/openapi/`). CI enforces all three, so this document cannot list a
route that does not exist or omit one that does.
**Schemas.** 447 operations carry request and response schemas
(`x-brix-schema: verified`). Each is checked in CI against the response the
real handler returns — a missing, mistyped or undeclared field fails the build.
The remaining operations are route-level only (`x-brix-schema: none`): their
path, method, permission and purpose are exact, but the shape of `data` is not
yet modelled, and we would rather say so than publish a schema that validates
against nothing. Objects are open: a new field is not a breaking change.
**Envelope.** Success bodies are `{ "data": … }`. Failures are
`{ "error": "", "message": "…" }`, plus `requestId` on a 5xx.
Many list routes page opt-in (see each operation): pass `?limit=` and
follow `nextCursor` via `?cursor=` until it is null.
**Authentication.** `Authorization: Bearer ` with an API key
(`ak_…`, created in the console under Settings → API & MCP) or a user session. An
API key carries a creator-chosen set of `resource.verb` permissions and may be
pinned to one location''s subtree; a key can never be granted a permission its
creator does not hold. The permission an operation needs is in
`x-brix-permission` and in its security requirement.
**Tenancy.** Every request resolves to one workspace. A resource belonging to
another tenant returns 404, never 403, so a response never confirms that an
account exists.
**Rate limits.** A 429 carries `Retry-After`; a 503 `database_busy` means retry
after the `Retry-After` interval.'
servers:
- url: https://api.brixsignage.com
description: Production
security:
- bearerAuth: []
tags:
- name: Roles
paths:
/v1/roles:
get:
operationId: listRoles
tags:
- Roles
summary: List roles
description: 'Returns the workspace''s roles, both built-in and custom, with the permissions each one carries.
**Notes.**
- Not paginated.'
x-brix-permission: permission-group.view
x-brix-schema: verified
x-brix-notes:
- Not paginated.
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Role'
required:
- data
'401':
description: Missing, expired or revoked bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: The token lacks the permission this operation needs (see `x-brix-permission`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
5XX:
description: Server error. The body carries a `requestId` to quote to support.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- bearerAuth:
- permission-group.view
post:
operationId: createRole
tags:
- Roles
summary: Create role
description: 'Creates a custom role. Provide `name` and `permissions`, a list of `resource.action` strings or `"all"`. You cannot create a role that holds permissions you do not hold yourself.
**Notes.**
- `permissions`, `features` and `scope` are stored as sent: the handler does not check their shape, so a malformed value is stored and read back as it was written.
- `builtIn` in the body is ignored.'
x-brix-permission: permission-group.create
x-brix-schema: verified
x-brix-notes:
- '`permissions`, `features` and `scope` are stored as sent: the handler does not check their shape, so a malformed value is stored and read back as it was written.'
- '`builtIn` in the body is ignored.'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Required on create.
color:
type: string
description:
type: string
permissions:
description: You must hold every permission you grant, workspace-wide. Default `[]`.
anyOf:
- type: string
const: all
- type: array
items:
type: string
features:
description: Default `[]`.
anyOf:
- type: string
const: all
- type: array
items:
type: string
scope:
description: 'Default `{ "kind": "workspace" }`.'
oneOf:
- type: object
properties:
kind:
type: string
const: workspace
required:
- kind
- type: object
properties:
kind:
type: string
const: org-units
orgUnitIds:
type: array
items:
type: string
description: The locations (and their subtrees) where the role applies.
required:
- kind
- orgUnitIds
character:
anyOf:
- type: string
- type: 'null'
viewTier:
description: The default console view for people with this role. `null` = the workspace default. Any other value is a 422.
anyOf:
- type: string
enum:
- simple
- team
- enterprise
- type: 'null'
contentScope:
description: What content people with this role see (`all` / `shared`); `null` = the workspace default. Changing it needs the role's permissions workspace-wide (403). Ignored on the built-in Owner.
anyOf:
- type: string
enum:
- all
- shared
- type: 'null'
required:
- name
example:
name: Store manager
permissions:
- screen.view
- screen.cast
- media.view
- media.create
responses:
'201':
description: Success.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Role'
required:
- data
'401':
description: Missing, expired or revoked bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: '`permissions` holds a permission you do not hold workspace-wide.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: '`name` missing.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
5XX:
description: Server error. The body carries a `requestId` to quote to support.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- bearerAuth:
- permission-group.create
/v1/roles/{id}:
delete:
operationId: deleteRole
tags:
- Roles
summary: Delete role
description: Soft-deletes a custom role. The role can later be restored. Refuses the request while anyone is still assigned to the role.
x-brix-permission: permission-group.delete
x-brix-schema: verified
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Role id.
example: role_5e6f7a8b9c0d1e2f
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
deleted:
type: boolean
const: true
required:
- id
- deleted
required:
- data
'401':
description: Missing, expired or revoked bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: The token lacks the permission this operation needs (see `x-brix-permission`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No such role in this workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: '`protected` (a built-in role), `last_owner_role`, or `in_use` (people still hold the role).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
5XX:
description: Server error. The body carries a `requestId` to quote to support.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- bearerAuth:
- permission-group.delete
get:
operationId: getRole
tags:
- Roles
summary: Get role
description: Returns one role with its full list of permissions.
x-brix-permission: permission-group.view
x-brix-schema: verified
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Role id.
example: role_5e6f7a8b9c0d1e2f
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Role'
required:
- data
'401':
description: Missing, expired or revoked bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: The token lacks the permission this operation needs (see `x-brix-permission`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No such role in this workspace (or it is deleted).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
5XX:
description: Server error. The body carries a `requestId` to quote to support.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- bearerAuth:
- permission-group.view
patch:
operationId: updateRole
tags:
- Roles
summary: Update role
description: 'Updates a role. The same rule as creating a role applies: you cannot add or remove a permission you do not hold yourself. Only a signed-in account owner can take full ownership away from a role that people hold; an API key cannot. On a built-in role, only the name, color and description change; its permissions, features and scope stay fixed.
**Notes.**
- `permissions`, `features` and `scope` are stored as sent: the handler does not check their shape, so a malformed value is stored and read back as it was written.
- `builtIn` in the body is ignored.
- On the built-in Owner role, `permissions`, `features` and `scope` are ignored without an error; only `name`, `color`, `description`, `character` and `viewTier` change. The other built-in roles edit like custom roles, except that `permissions` cannot be `"all"` (422).'
x-brix-permission: permission-group.edit
x-brix-schema: verified
x-brix-notes:
- '`permissions`, `features` and `scope` are stored as sent: the handler does not check their shape, so a malformed value is stored and read back as it was written.'
- '`builtIn` in the body is ignored.'
- On the built-in Owner role, `permissions`, `features` and `scope` are ignored without an error; only `name`, `color`, `description`, `character` and `viewTier` change. The other built-in roles edit like custom roles, except that `permissions` cannot be `"all"` (422).
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Role id.
example: role_5e6f7a8b9c0d1e2f
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Required on create.
color:
type: string
description:
type: string
permissions:
description: You must hold every permission you grant, workspace-wide. Default `[]`.
anyOf:
- type: string
const: all
- type: array
items:
type: string
features:
description: Default `[]`.
anyOf:
- type: string
const: all
- type: array
items:
type: string
scope:
description: 'Default `{ "kind": "workspace" }`.'
oneOf:
- type: object
properties:
kind:
type: string
const: workspace
required:
- kind
- type: object
properties:
kind:
type: string
const: org-units
orgUnitIds:
type: array
items:
type: string
description: The locations (and their subtrees) where the role applies.
required:
- kind
- orgUnitIds
character:
anyOf:
- type: string
- type: 'null'
viewTier:
description: The default console view for people with this role. `null` = the workspace default. Any other value is a 422.
anyOf:
- type: string
enum:
- simple
- team
- enterprise
- type: 'null'
contentScope:
description: What content people with this role see (`all` / `shared`); `null` = the workspace default. Changing it needs the role's permissions workspace-wide (403). Ignored on the built-in Owner.
anyOf:
- type: string
enum:
- all
- shared
- type: 'null'
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Role'
required:
- data
'401':
description: Missing, expired or revoked bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: 'You would add or remove a permission you do not hold workspace-wide, or change `scope` of a role whose permissions you do not hold workspace-wide; `owner_required`: the change takes full ownership away from a role people hold, and the caller is not a signed-in owner (an API key never is).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No such role in this workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: '`last_owner_role`: this is the only role with full ownership.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: '`permissions: "all"` on a built-in role other than Owner.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
5XX:
description: Server error. The body carries a `requestId` to quote to support.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- bearerAuth:
- permission-group.edit
/v1/roles/{id}/restore:
post:
operationId: restoreRole
tags:
- Roles
summary: Restore deleted role
description: 'Restores a previously deleted custom role. Requires the same permission needed to delete a role.
**Notes.**
- Answers the whole restored role, not the `{ id, restored }` acknowledgement other restores use.'
x-brix-permission: permission-group.delete
x-brix-schema: verified
x-brix-notes:
- Answers the whole restored role, not the `{ id, restored }` acknowledgement other restores use.
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Role id.
example: role_5e6f7a8b9c0d1e2f
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Role'
required:
- data
'401':
description: Missing, expired or revoked bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: The token lacks the permission this operation needs (see `x-brix-permission`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No such role in this workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: '`not_deleted`: the role is not deleted.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
5XX:
description: Server error. The body carries a `requestId` to quote to support.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- bearerAuth:
- permission-group.delete
components:
schemas:
Error:
type: object
properties:
error:
type: string
description: 'Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, …'
message:
description: Human-readable explanation. Safe to show an operator.
type: string
requestId:
description: 'Present on 5xx: quote it to support.'
type: string
required:
- error
additionalProperties: {}
description: Error envelope returned by every failing request.
Role:
type: object
properties:
id:
type: string
name:
type: string
color:
anyOf:
- type: string
- type: 'null'
description: Display style for the role chip.
description:
type: string
description: Empty string when not set.
builtIn:
type: boolean
description: A role that every workspace starts with (Owner, Admin, Finance, Content Manager, Approver, Local Manager, Installer, Viewer). It cannot be deleted. The Owner role's permissions, features and scope cannot be changed; the other built-in roles can be edited.
permissions:
anyOf:
- type: string
const: all
- type: array
items:
type: string
description: '`resource.action` permissions, or `"all"` (every permission, now and later).'
features:
anyOf:
- type: string
const: all
- type: array
items:
type: string
description: Feature keys the role unlocks, or `"all"`.
scope:
oneOf:
- type: object
properties:
kind:
type: string
const: workspace
required:
- kind
- type: object
properties:
kind:
type: string
const: org-units
orgUnitIds:
type: array
items:
type: string
description: The locations (and their subtrees) where the role applies.
required:
- kind
- orgUnitIds
description: 'Where the role applies: the whole workspace, or only the listed locations.'
character:
anyOf:
- type: string
- type: 'null'
description: A decorative label. Not used for access.
viewTier:
anyOf:
- type: string
enum:
- simple
- team
- enterprise
- type: 'null'
description: The console view people with this role open in, unless they choose their own. `null` = the workspace default. Not used for access.
contentScope:
anyOf:
- type: string
enum:
- all
- shared
- type: 'null'
description: 'What content people with this role see: `all`, or `shared` (only content shared with them plus their own locations'' content). `null` = the workspace default (`all`). A person''s own setting replaces it.'
memberCount:
type: integer
description: Role assignments that use this role (one per person per location).
createdAt:
type: string
description: ISO-8601 timestamp (UTC).
updatedAt:
type: string
description: ISO-8601 timestamp (UTC).
required:
- id
- name
- color
- description
- builtIn
- permissions
- features
- scope
- character
- viewTier
- contentScope
- memberCount
- createdAt
- updatedAt
description: A named set of permissions assigned to people at locations.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: An API key (`ak_…`) or a user session token. API keys carry `resource.verb` permissions.