Vertesia Roles API

openapi: 3.2.0
info:
  title: Vertesia Roles API
  version: 1.6.0-dev.20261019.172735Z
  x-api-version: '20260803'
  description: The Vertesia API provides project-scoped access to interaction execution and content workflows. Use it to run interactions, inspect execution history, stream run progress, replay previous executions, and search content objects and collections. Authenticate requests with a bearer token, or use the official `@vertesia/client` package for typed access from Node.js applications.
  contact:
    name: Vertesia
    url: https://vertesiahq.com/
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  x-scalar-sdk-installation:
  - lang: Node
    description: 'Install the **Vertesia Client** from npm:'
    source: npm install @vertesia/client
servers:
- url: https://api.{region}.vertesia.io/api/v1
  description: Vertesia API
  variables:
    region:
      default: us1
      enum:
      - us1
      - eu1
      - jp1
      description: Regional API host label. `us1` is the global endpoint.
tags:
- name: Roles
  description: Role endpoints expose the built-in Vertesia role catalog and the permissions granted by each role.
paths:
  /iam/roles:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    get:
      operationId: ListRoles
      tags:
      - Roles
      summary: List built-in roles
      description: Lists every built-in role across all partitions (system, content, …) and the permissions each role grants.
      security:
      - bearerAuth: []
      - OAuth2: []
      parameters: []
      responses:
        '200':
          description: Built-in roles and permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleDefinitionArray'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions: []
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/iam/roles.ts
        className: RolesResource
        methodName: listRoles
  /iam/roles/system:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    get:
      operationId: ListSystemRoles
      tags:
      - Roles
      summary: List system roles
      description: Lists system-domain roles only. Permissions are `Permission` enum values — suited for client-side permission gating (button visibility, route guards). ABAC roles are excluded and must be consumed via the JWT `content_security` claim at the data layer.
      security:
      - bearerAuth: []
      - OAuth2: []
      parameters: []
      responses:
        '200':
          description: System roles and their permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemRoleDefinitionArray'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions: []
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/iam/roles.ts
        className: RolesResource
        methodName: listSystemRoles
components:
  schemas:
    RoleDefinitionArray:
      type: array
      items:
        $ref: '#/components/schemas/RoleDefinition'
    RoleDefinition:
      type: object
      properties:
        name:
          type: string
        permissions:
          type: array
          items:
            type: string
        domain:
          $ref: '#/components/schemas/RoleDomain'
      required:
      - name
      - permissions
      - domain
      additionalProperties: false
      description: 'Wire shape of a role returned by the IAM `/roles` endpoint.


        Permissions are typed `string[]` because role names span multiple partitions (system, content, future tasks/etc.) and each partition has its own vocabulary. For the tightly-typed system-only view (with `permissions: Permission[]`) use `SystemRoleDefinition` and the `/roles/system` endpoint.


        NOTE: this interface is intentionally non-generic. The OpenAPI generator doesn''t handle TypeScript generics cleanly in array response types and produces a degenerate `RoleDefinitionArray` schema. Keeping the wire shapes concrete avoids that. `SystemRoleDefinition` extends and narrows `permissions` to `Permission[]`.'
    Permission:
      type: string
      enum:
      - account:user:read
      - account:user:manage
      - account:group:read
      - account:group:manage
      - account:membership:read
      - account:membership:manage
      - account:api_key:read
      - account:api_key:manage
      - account:billing:status_read
      - account:billing:portal_create
      - schedule:delegate
      - interaction:read
      - interaction:write
      - interaction:delete
      - interaction:execute
      - run:read
      - run:write
      - environment:admin
      - app:manage
      - project:admin
      - project:integration_read
      - project:settings_write
      - api_key:create
      - api_key:read
      - api_key:secret_read
      - api_key:update
      - api_key:delete
      - account:read
      - account:write
      - account:admin
      - account:billing
      - billing:read
      - audit:read
      - account:member
      - content:read
      - content:read_all
      - content:write
      - content:delete
      - content:admin
      - content:superadmin
      - workflow:read
      - workflow:run
      - workflow:admin
      - workflow:superadmin
      - agent_run:read
      - task:read
      - task:manage
      - iam:impersonate
      - studio:access
    RoleDomain:
      type: string
      enum:
      - system
      - content
      - agent_runs
      - shared_content
      - tasks
      description: Logical grouping of roles by the service area that owns them. One domain may declare roles applicable to multiple scopes (e.g. the `content` domain owns roles applicable to both `document` and `collection` scopes, while `agent_runs` owns the `agent_run` scope). The `system` domain owns the built-in foundational roles (currently exposed as `SystemRoles`) — registered first so domain partitions cannot shadow them.
    SystemRoleDefinitionArray:
      type: array
      items:
        $ref: '#/components/schemas/SystemRoleDefinition'
    SystemRoleDefinition:
      type: object
      properties:
        name:
          type: string
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
        domain:
          $ref: '#/components/schemas/RoleDomain'
      required:
      - name
      - permissions
      - domain
      additionalProperties: false
      description: 'Tightly-typed view of a system-domain role: permissions are central `Permission` enum values. Returned by `client.iam.roles.listSystem()` and by the server''s `/roles/system` endpoint.'
    ErrorResponse:
      type: object
      description: Standard JSON error response returned by the server error handler.
      properties:
        error:
          type: string
          description: HTTP status text or normalized error type.
        status:
          type: integer
          format: int32
          minimum: 400
          maximum: 599
          description: HTTP status code. Client errors use a 4xx status code; server errors use 500.
          example: 400
        message:
          type: string
          description: Human-readable error message.
        details:
          type: string
          description: Optional additional error details.
        errorCode:
          type: string
          description: Machine-readable code for the specific failure, present when the error carries one, so clients can branch on it without parsing `message`.
          example: account_api_key_creation_disabled
      required:
      - error
      - status
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://cloud.us1.vertesia.io/oauth/authorize
          tokenUrl: https://sts.vertesia.io/oauth/token
          x-scalar-security-query:
            resource: https://api.us1.vertesia.io/api/v1
          x-scalar-security-body:
            resource: https://api.us1.vertesia.io/api/v1
          scopes:
            openid: ''
            profile: ''
            offline_access: ''
            interaction:read: ''
            interaction:write: ''
            interaction:delete: ''
            interaction:execute: ''
            run:read: ''
            run:write: ''
            environment:admin: ''
            app:manage: ''
            project:admin: ''
            project:integration_read: ''
            project:settings_write: ''
            api_key:read: ''
            account:read: ''
            account:write: ''
            account:admin: ''
            audit:read: ''
            account:member: ''
            content:read: ''
            content:read_all: ''
            content:write: ''
            content:delete: ''
            content:admin: ''
            content:superadmin: ''
            workflow:read: ''
            workflow:run: ''
            workflow:admin: ''
            workflow:superadmin: ''
            agent_run:read: ''
            task:read: ''
            task:manage: ''
x-tagGroups:
- name: Authentication
  tags:
  - Token Service
- name: GenAI
  tags:
  - Environments
  - Prompt Templates
  - Interactions
  - Interaction Runs
  - Agent Runs
- name: Content
  tags:
  - Content Object Types
  - Objects
  - Collections
  - Files
  - Rendering
  - Bulk Operations
  - Commands
- name: Data Store
  tags:
  - Data
- name: Workflow
  tags:
  - Processes
  - Tasks
  - Workflow Definitions
  - Workflow Rules
  - Workflow Runs
- name: Administration
  tags:
  - Accounts
  - Projects
  - Audit Trail
  - Costs
- name: Access Control
  tags:
  - Users
  - User Groups
  - Roles
  - Access Control Entries
  - API Keys
- name: Apps & Integrations
  tags:
  - Apps
  - OAuth Providers
  - OAuth Clients
  - OAuth Grants
  - Remote MCP Connections