Vertesia Quota API

openapi: 3.2.0
info:
  title: Vertesia Quota 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: Quota
paths:
  /quota/standing:
    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: GetQuotaStanding
      tags:
      - Quota
      summary: Get quota standing
      description: 'The calling tenant''s quota standing: effective API rate limits and current usage, workflow-admission active slots, and the LLM limiter posture.


        **Required permissions:** `account:member`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:member
      parameters: []
      responses:
        '200':
          description: The caller's quota standing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaStandingResponse'
        '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:
      - account:member
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/quota.ts
        className: QuotaResource
        methodName: getStanding
  /quota/tier:
    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: GetQuotaTier
      tags:
      - Quota
      summary: Get quota tier
      description: 'The calling account''s effective quota tier: explicit account `quota_tier`, else its account_type-derived tier, else the deployment base tier when the account tier cannot be resolved. A lightweight lookup other services use to resolve a tenant tier without a direct account-store dependency.


        **Required permissions:** `account:member`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:member
      parameters: []
      responses:
        '200':
          description: The calling account's effective quota tier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaTierResponse'
        '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:
      - account:member
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/quota.ts
        className: QuotaResource
        methodName: getTier
components:
  schemas:
    QuotaStandingResource:
      type: object
      properties:
        resource:
          type: string
        name:
          type: string
        burst:
          $ref: '#/components/schemas/QuotaStandingWindow'
        quota:
          $ref: '#/components/schemas/QuotaStandingWindow'
      required:
      - resource
      - name
      - burst
      - quota
      additionalProperties: false
    QuotaStandingResponse:
      type: object
      properties:
        tenant_id:
          type: string
        available:
          type: boolean
          description: False when the limiter store (Redis) was unavailable, so `api`/`admission` are empty because standing could not be read — NOT because there are no limits. Limiters fail open in this case.
        base_tier:
          type: string
          description: Deployment base tier (env QUOTA_BASE_TIER); `default` = the static limits stand.
        effective_tier:
          $ref: '#/components/schemas/QuotaEffectiveTier'
          description: 'Tier used to compute the API limits below: explicit account `quota_tier`, else account_type derived tier, else `base_tier` when the account tier could not be resolved.'
        api:
          type: array
          items:
            $ref: '#/components/schemas/QuotaStandingResource'
          description: Per-resource API rate-limit standing (effective limits + current usage).
        admission:
          type: object
          properties:
            classes:
              type: array
              items:
                $ref: '#/components/schemas/QuotaStandingAdmissionClass'
            note:
              type: string
          required:
          - classes
          - note
          additionalProperties: false
          description: 'Workflow admission: per-tenant active slots per probed class. The budget itself is global and discovered (AIMD), not a per-tenant number — this is occupancy, not a limit.'
        llm:
          type: object
          properties:
            note:
              type: string
          required:
          - note
          additionalProperties: false
          description: The LLM interaction limiter is shared per environment/model, not per tenant.
      required:
      - tenant_id
      - available
      - base_tier
      - effective_tier
      - api
      - admission
      - llm
      additionalProperties: false
    QuotaStandingAdmissionClass:
      type: object
      properties:
        class:
          type: string
          description: Workflow class (e.g. ExecuteConversationWorkflow).
        tenant_active:
          type: number
          description: This tenant's currently active (leased) slots for the class.
      required:
      - class
      - tenant_active
      additionalProperties: false
    QuotaEffectiveTier:
      type: string
      description: Effective quota tier name after account-level overrides and account-type derivation. Code-defined tier names are currently `QuotaTier`, but this remains a string because deployments can introduce quota tiers through configuration.
    QuotaStandingWindow:
      type: object
      properties:
        limit:
          type: number
          description: Effective limit for this window (after effective account tier + per-tenant override).
        used:
          type: number
          description: Requests used in the current window.
        remaining:
          type: number
          description: Requests remaining (max(0, limit - used)).
        window_ms:
          type: number
      required:
      - limit
      - used
      - remaining
      - window_ms
      additionalProperties: false
      description: A caller's own quota standing (GET /api/v1/quota/standing) — "where am I". API rate limits are genuinely per-tenant; workflow admission and the LLM limiter are global/discovered, so they are reported as posture, not per-tenant numbers.
    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
    QuotaTierResponse:
      type: object
      properties:
        tier:
          $ref: '#/components/schemas/QuotaEffectiveTier'
      required:
      - tier
      additionalProperties: false
      description: 'Lightweight per-account quota tier for the calling account — served by `GET /api/v1/quota/tier`. A cheap, cacheable read that lets another service (e.g. zeno-server''s API rate limiter) resolve the caller''s tier through studio-server instead of reaching into the account store directly. `tier` is the SAME value  {@link  QuotaStandingResponse.effective_tier }  reports: the account''s explicit `quota_tier`, else its account_type-derived tier, else the deployment base tier when the account tier cannot be resolved.'
  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