> ## Documentation Index
> Fetch the complete documentation index at: https://docs.matrices.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List roles



## OpenAPI

````yaml /openapi/platform.v1.json get /v1/roles
openapi: 3.0.3
info:
  description: Public platform API for catalog and proxied data-plane routes.
  title: Matrices Platform API
  version: v1
servers:
  - url: https://api.matrices.com
security: []
tags:
  - description: Authenticated bearer credential context.
    name: auth
    x-group: Auth
  - description: Write-only provider credentials with safe connection metadata.
    name: connections
    x-group: Connections
  - description: Materialized workspace principals and active agent counts.
    name: identities
    x-group: Identities
  - description: Remote MCP server registrations.
    name: toolsets
    x-group: Toolsets
  - description: Named allow-only agent tool permissions.
    name: roles
    x-group: Roles
  - description: Client-executed tool calls.
    name: tools
    x-group: Tools
  - description: Reusable agent behavior profiles.
    name: profiles
    x-group: Profiles
  - description: Workspace-owned agent identities.
    name: agents
    x-group: Agents
  - description: Immutable private image inputs.
    name: images
    x-group: Images
  - description: Public model catalog.
    name: models
    x-group: Models
  - description: Running agent threads.
    name: threads
    x-group: Threads
  - description: Agent schedules.
    name: schedules
    x-group: Schedules
  - description: Workspace append-only feeds.
    name: feeds
    x-group: Feeds
  - description: Agent subscriptions over workspace feeds.
    name: subscriptions
    x-group: Subscriptions
  - description: Agent-private and workspace-shared durable memory notes.
    name: memory
    x-group: Memory
  - description: Thread messages.
    name: messages
    x-group: Messages
  - description: Thread event log data.
    name: events
    x-group: Events
  - description: Runtime hook audit and wait resolution.
    name: hooks
    x-group: Hooks
paths:
  /v1/roles:
    get:
      tags:
        - roles
      summary: List roles
      operationId: ListRoles
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RolePage'
          description: Role page.
        '202':
          $ref: '#/components/responses/PendingOperation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '503':
          $ref: '#/components/responses/CatalogUnavailable'
      security:
        - APIKeyBearer: []
        - AgentLeaseBearer: []
components:
  parameters:
    Limit:
      in: query
      name: limit
      required: false
      schema:
        maximum: 200
        minimum: 1
        type: integer
    Cursor:
      in: query
      name: cursor
      required: false
      schema:
        type: string
  schemas:
    RolePage:
      properties:
        nextCursor:
          type: string
        roles:
          items:
            $ref: '#/components/schemas/Role'
          type: array
      required:
        - roles
      type: object
    Role:
      properties:
        allow:
          items:
            $ref: '#/components/schemas/RolePermission'
          maxItems: 32
          type: array
        createdAt:
          format: date-time
          type: string
        deny:
          description: >-
            Bare built-in tool patterns removed from this role's broader allows.
            Each pattern must select at least one current built-in tool;
            external namespaces are not deniable in v1.
          items:
            $ref: '#/components/schemas/ToolPermission'
          maxItems: 32
          type: array
        description:
          maxLength: 1024
          type: string
        id:
          type: string
        name:
          maxLength: 128
          type: string
        updatedAt:
          format: date-time
          type: string
        version:
          format: int64
          type: integer
        workspaceId:
          type: string
      required:
        - id
        - workspaceId
        - name
        - description
        - allow
        - deny
        - version
        - createdAt
        - updatedAt
      type: object
    OperationResponse:
      additionalProperties: false
      properties:
        operation:
          $ref: '#/components/schemas/Operation'
      required:
        - operation
      type: object
    ErrorResponse:
      properties:
        attemptsRemaining:
          type: integer
        code:
          type: string
        error:
          type: string
        message:
          type: string
        retryAfterSeconds:
          type: integer
      required:
        - error
        - message
      type: object
    RolePermission:
      oneOf:
        - $ref: '#/components/schemas/ToolPermission'
        - additionalProperties: false
          properties:
            tool:
              $ref: '#/components/schemas/ToolPermission'
            where:
              items:
                $ref: '#/components/schemas/PermissionMatchCondition'
              maxItems: 8
              type: array
          required:
            - tool
          type: object
    ToolPermission:
      maxLength: 176
      pattern: >-
        ^tool:(\*|(builtin|managed|workspace):(\*|[a-z0-9][a-z0-9_-]{0,31}\.\*|[a-z0-9][a-z0-9_-]{0,31}\.[A-Za-z0-9][A-Za-z0-9_.-]{0,127}))$
      type: string
    Operation:
      additionalProperties: false
      properties:
        action:
          type: string
        agentId:
          type: string
        createdAt:
          format: date-time
          type: string
        expiresAt:
          format: date-time
          type: string
        id:
          type: string
        resolvedAt:
          format: date-time
          type: string
        resolvedBy:
          $ref: '#/components/schemas/Principal'
        result:
          $ref: '#/components/schemas/OperationResult'
        state:
          $ref: '#/components/schemas/OperationState'
      required:
        - id
        - agentId
        - action
        - state
        - createdAt
        - expiresAt
      type: object
    PermissionMatchCondition:
      oneOf:
        - additionalProperties: false
          properties:
            op:
              enum:
                - eq
                - neq
              type: string
            path:
              type: string
            quantifier:
              $ref: '#/components/schemas/MatchQuantifier'
            value:
              $ref: '#/components/schemas/PermissionEqValue'
          required:
            - path
            - op
            - value
          type: object
        - additionalProperties: false
          properties:
            op:
              enum:
                - prefix
                - not_prefix
                - suffix
                - not_suffix
                - contains
                - not_contains
              type: string
            path:
              type: string
            quantifier:
              $ref: '#/components/schemas/MatchQuantifier'
            value:
              type: string
          required:
            - path
            - op
            - value
          type: object
        - additionalProperties: false
          properties:
            op:
              enum:
                - in
                - not_in
              type: string
            path:
              type: string
            quantifier:
              $ref: '#/components/schemas/MatchQuantifier'
            value:
              items:
                $ref: '#/components/schemas/PermissionScalar'
              minItems: 1
              type: array
          required:
            - path
            - op
            - value
          type: object
        - additionalProperties: false
          properties:
            op:
              enum:
                - exists
                - absent
              type: string
            path:
              type: string
          required:
            - path
            - op
          type: object
    Principal:
      properties:
        id:
          type: string
        identity:
          $ref: '#/components/schemas/Identity'
        origin:
          $ref: '#/components/schemas/Origin'
        type:
          enum:
            - user
            - api_key
            - agent
            - schedule
            - trigger
            - subscription
          type: string
      required:
        - type
        - id
      type: object
    OperationResult:
      additionalProperties: false
      properties:
        body: {}
        status:
          maximum: 599
          minimum: 100
          type: integer
      required:
        - status
      type: object
    OperationState:
      enum:
        - pending
        - denied
        - expired
        - executing
        - executed
        - failed
      type: string
    MatchQuantifier:
      enum:
        - any
        - all
      type: string
    PermissionEqValue:
      oneOf:
        - $ref: '#/components/schemas/PermissionScalar'
        - items:
            $ref: '#/components/schemas/PermissionScalar'
          type: array
    PermissionScalar:
      oneOf:
        - type: string
        - type: number
        - type: boolean
    Identity:
      description: >-
        Provenance identity. Surrounding whitespace is trimmed on input; values
        may contain at most 512 UTF-8 bytes and no Unicode control characters.
      type: string
    Origin:
      additionalProperties: false
      description: >-
        Caller-asserted external event metadata. Only trigger principals may
        assert it; every other principal is rejected.
      properties:
        channelId:
          description: Provider channel identifier, limited to 512 UTF-8 bytes.
          type: string
        messageId:
          description: Provider message identifier, limited to 512 UTF-8 bytes.
          type: string
        provider:
          $ref: '#/components/schemas/OriginProvider'
        senderId:
          description: Provider sender identifier, limited to 512 UTF-8 bytes.
          type: string
        tenantId:
          description: Provider tenant identifier, limited to 512 UTF-8 bytes.
          type: string
        threadId:
          description: Provider thread identifier, limited to 512 UTF-8 bytes.
          type: string
      required:
        - provider
        - tenantId
        - senderId
      type: object
    OriginProvider:
      description: >-
        Caller-asserted external event provider. This value carries no
        authority.
      enum:
        - slack
      type: string
  responses:
    PendingOperation:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OperationResponse'
      description: >-
        Request parked for workspace approval. Poll the returned operation
        handle for a terminal result.
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Invalid request.
    CatalogUnavailable:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Platform catalog database is not configured or unavailable.
  securitySchemes:
    APIKeyBearer:
      scheme: bearer
      type: http
    AgentLeaseBearer:
      description: >-
        Short-lived agent lease bearer installed in a sandbox provider HTTP
        boundary. Requests run as the owning agent and are checked against live
        agent permissions.
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.