openapi: 3.1.2
info:
  title: Mystro Platform API
  version: 0.1.0-draft.3
  description: >-
    PROPOSED CONTRACT — not a live service. Your product. Powered by agents.
    Dedicated tenant/environment cells; customer applications retain identity
    and business authorization. All mutation requests require Idempotency-Key.
    Canonical request replay lasts 7 days; metadata tombstones 90 days prevent
    recreation. Actor + method + path + tenant + environment scope keys. Changed
    payload returns 409. Secret-bearing replay returns metadata only. Lists
    default 50/max100 opaque cursor items. /v1 changes additive; breaking
    changes use /v2. No automatic external write retries. This document is the
    only maintained platform API source.

    View: public; maximum lifecycle stage: proposed.
x-default-rate-limits:
  cell_requests_per_second: 60
  cell_request_burst: 120
  cell_open_sse_streams: 128
  actor_open_sse_streams: 16
servers:
  - url: https://api.mystro.invalid
    description: Reserved documentation placeholder; service not available.
security:
  - ServiceKey: []
tags:
  - name: tenants
  - name: tenant_id
  - name: environments
  - name: environment
  - name: production-request
  - name: api-keys
  - name: key_id
  - name: rotate
  - name: revoke
  - name: users
  - name: user_id
  - name: service-actors
  - name: service_actor_id
  - name: actor-sessions
  - name: workspaces
  - name: workspace_id
  - name: agents
  - name: agent_id
  - name: revisions
  - name: revision_id
  - name: model-profiles
  - name: model_profile_id
  - name: connections
  - name: connection_id
  - name: tools
  - name: tool_id
  - name: conversations
  - name: conversation_id
  - name: runs
  - name: run_id
  - name: cancel
  - name: events
  - name: stream
  - name: approvals
  - name: approval_id
  - name: decision
  - name: files
  - name: file_id
  - name: download
  - name: webhook-endpoints
  - name: webhook_endpoint_id
  - name: rotate-secret
  - name: webhook-deliveries
  - name: webhook_delivery_id
  - name: replay
  - name: usage
  - name: records
  - name: quotas
  - name: settings
  - name: audit
  - name: deletion_job_id
  - name: jwks.json
  - name: Console
  - name: Operations
  - name: start
  - name: callback
  - name: schedules
  - name: schedule_id
  - name: memory
  - name: memory_id
paths:
  /v1/tenants:
    get:
      operationId: listTenants
      summary: List authorized tenants
      tags:
        - tenants
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - tenants:read
      security:
        - ServiceKey: []
      description: List authorized tenants
      parameters:
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Tenant"
                  next_cursor:
                    type:
                      - string
                      - "null"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - items
                  - next_cursor
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}:
    get:
      operationId: getTenant
      summary: Get tenant
      tags:
        - tenant_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - tenants:read
      security:
        - ServiceKey: []
      description: Get tenant
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Tenant"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
    patch:
      operationId: updateTenant
      summary: Update tenant name
      tags:
        - tenant_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - tenants:write
      security:
        - ServiceKey: []
      description: Update tenant name
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Tenant"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateTenant"
    delete:
      operationId: deleteTenant
      summary: Delete tenant
      tags:
        - tenant_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - tenants:write
      security:
        - ServiceKey: []
      description: Delete tenant
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "202":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
            Location:
              schema:
                type: string
              description: Poll the accepted resource at this path.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/DeletionJob"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments:
    get:
      operationId: listEnvironments
      summary: List tenant environments
      tags:
        - environments
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - environments:read
      security:
        - ServiceKey: []
      description: List tenant environments
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Environment"
                  next_cursor:
                    type:
                      - string
                      - "null"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - items
                  - next_cursor
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}:
    get:
      operationId: getEnvironment
      summary: Get environment provisioning state
      tags:
        - environment
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - environments:read
      security:
        - ServiceKey: []
      description: Get environment provisioning state
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Environment"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
    delete:
      operationId: deleteEnvironment
      summary: Delete environment
      tags:
        - environment
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - environments:write
      security:
        - ServiceKey: []
      description: Delete environment
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "202":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
            Location:
              schema:
                type: string
              description: Poll the accepted resource at this path.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/DeletionJob"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/api-keys:
    get:
      operationId: listApiKey
      summary: List api-keys
      tags:
        - api-keys
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - keys:read
      security:
        - ServiceKey: []
      description: List api-keys
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/ApiKey"
                  next_cursor:
                    type:
                      - string
                      - "null"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - items
                  - next_cursor
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/api-keys/{key_id}:
    get:
      operationId: getApiKey
      summary: Get key
      tags:
        - key_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - keys:read
      security:
        - ServiceKey: []
      description: Get key
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: key_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/ApiKey"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/api-keys/{key_id}/revoke:
    post:
      operationId: revokeApiKey
      summary: Revoke API key
      tags:
        - revoke
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - keys:revoke
      security:
        - ServiceKey: []
      description: Within management ceiling only. Immediately rejects next
        request/tool and invalidates descendant leases; SSE ends within 15
        seconds. Accepted external operations may finish and retain receipts.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: key_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/ApiKey"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/users:
    get:
      operationId: listUser
      summary: List users
      tags:
        - users
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - users:read
      security:
        - ServiceKey: []
      description: List users
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/User"
                  next_cursor:
                    type:
                      - string
                      - "null"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - items
                  - next_cursor
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
    post:
      operationId: createUser
      summary: Create user
      tags:
        - users
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - users:write
      security:
        - ServiceKey: []
      description: Create user
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "201":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/User"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUser"
  /v1/tenants/{tenant_id}/environments/{environment}/users/{user_id}:
    get:
      operationId: getUser
      summary: Get user
      tags:
        - user_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - users:read
      security:
        - ServiceKey: []
      description: Get user
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/User"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
    patch:
      operationId: updateUser
      summary: Update user
      tags:
        - user_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - users:write
      security:
        - ServiceKey: []
      description: Update user
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/User"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateActor"
    delete:
      operationId: deleteUser
      summary: Delete user
      tags:
        - user_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - users:write
      security:
        - ServiceKey: []
      description: Immediately deny access and revoke derived authority. Live purge
        within 24 hours; backups expire separately within 30 days. Restore
        replays deletion journal before serving.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "202":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
            Location:
              schema:
                type: string
              description: Poll the accepted resource at this path.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/DeletionJob"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/service-actors:
    get:
      operationId: listServiceActor
      summary: List service-actors
      tags:
        - service-actors
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - service-actors:read
      security:
        - ServiceKey: []
      description: List service-actors
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/ServiceActor"
                  next_cursor:
                    type:
                      - string
                      - "null"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - items
                  - next_cursor
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
    post:
      operationId: createServiceActor
      summary: Create service_actor
      tags:
        - service-actors
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - service-actors:write
      security:
        - ServiceKey: []
      description: Create service_actor
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "201":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/ServiceActor"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateServiceActor"
  /v1/tenants/{tenant_id}/environments/{environment}/service-actors/{service_actor_id}:
    get:
      operationId: getServiceActor
      summary: Get service_actor
      tags:
        - service_actor_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - service-actors:read
      security:
        - ServiceKey: []
      description: Get service_actor
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: service_actor_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/ServiceActor"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
    patch:
      operationId: updateServiceActor
      summary: Update service_actor
      tags:
        - service_actor_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - service-actors:write
      security:
        - ServiceKey: []
      description: Update service_actor
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: service_actor_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/ServiceActor"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateActor"
    delete:
      operationId: deleteServiceActor
      summary: Delete service_actor
      tags:
        - service_actor_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - service-actors:write
      security:
        - ServiceKey: []
      description: Immediately deny access and revoke derived authority. Live purge
        within 24 hours; backups expire separately within 30 days. Restore
        replays deletion journal before serving.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: service_actor_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "202":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
            Location:
              schema:
                type: string
              description: Poll the accepted resource at this path.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/DeletionJob"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/actor-sessions:
    post:
      operationId: createActorSession
      summary: Issue delegated user session
      tags:
        - actor-sessions
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes: []
      security:
        - ServiceKey: []
      description: Trusted backend delegation requires identity:delegate OR
        approval:delegate. An identity-only key may mint its configured
        execution/files scope subset, never approval scopes. An approval-only
        key may mint only approvals:read and approvals:write leases. Both
        authorities are required to mix those scope categories. Requested scopes
        must also be a subset of the active parent key scopes. Five-minute
        user-only lease; current active user and matching workspace owner are
        checked. Service actors cannot become approvers. Fresh issuance returns
        token_available:true and a token; replay returns token_available:false
        and no token. Use a fresh idempotency key for a new lease. Parent key
        revocation invalidates derived leases.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "201":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/ActorSession"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ActorSessionRequest"
      x-any-required-scopes:
        - identity:delegate
        - approval:delegate
  /v1/tenants/{tenant_id}/environments/{environment}/workspaces:
    get:
      operationId: listWorkspace
      summary: List workspaces
      tags:
        - workspaces
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - workspaces:read
      security:
        - ServiceKey: []
        - ActorToken: []
      description: List workspaces
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Workspace"
                  next_cursor:
                    type:
                      - string
                      - "null"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - items
                  - next_cursor
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
    post:
      operationId: createWorkspace
      summary: Create workspace
      tags:
        - workspaces
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - workspaces:write
      security:
        - ServiceKey: []
        - ActorToken: []
      description: One workspace per owner actor/environment. Server derives ownership
        from authenticated authority; a delegated user requires
        identity:delegate. Another actor workspace is inaccessible.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "201":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Workspace"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWorkspace"
  /v1/tenants/{tenant_id}/environments/{environment}/workspaces/{workspace_id}:
    get:
      operationId: getWorkspace
      summary: Get workspace
      tags:
        - workspace_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - workspaces:read
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Get workspace
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: workspace_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Workspace"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
    delete:
      operationId: deleteWorkspace
      summary: Delete workspace
      tags:
        - workspace_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - workspaces:write
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Immediately deny access and revoke derived authority. Live purge
        within 24 hours; backups expire separately within 30 days. Restore
        replays deletion journal before serving.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: workspace_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "202":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
            Location:
              schema:
                type: string
              description: Poll the accepted resource at this path.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/DeletionJob"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/agents:
    get:
      operationId: listAgent
      summary: List agents
      tags:
        - agents
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - agents:read
      security:
        - ServiceKey: []
      description: List agents
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Agent"
                  next_cursor:
                    type:
                      - string
                      - "null"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - items
                  - next_cursor
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
    post:
      operationId: createAgent
      summary: Create agent
      tags:
        - agents
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - agents:write
      security:
        - ServiceKey: []
      description: Create agent
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "201":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Agent"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAgent"
  /v1/tenants/{tenant_id}/environments/{environment}/agents/{agent_id}:
    get:
      operationId: getAgent
      summary: Get agent
      tags:
        - agent_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - agents:read
      security:
        - ServiceKey: []
      description: Get agent
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Agent"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
    patch:
      operationId: updateAgent
      summary: Update agent
      tags:
        - agent_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - agents:write
      security:
        - ServiceKey: []
      description: Update agent
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Agent"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Archive"
  /v1/tenants/{tenant_id}/environments/{environment}/agents/{agent_id}/revisions:
    post:
      operationId: createAgentRevision
      summary: Freeze immutable agent revision
      tags:
        - revisions
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - agents:write
      security:
        - ServiceKey: []
      description: Freeze immutable agent revision
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "201":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/AgentRevision"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAgentRevision"
            example:
              instructions: Summarize the supplied operations report. Use only approved tools.
              model_profile: standard
              tool_ids: []
              memory:
                mode: off
              limits:
                max_active_seconds: 300
                max_steps: 20
                max_input_tokens: 32768
                max_output_tokens: 8192
                max_cost_usd: "1.00"
    get:
      operationId: listAgentRevisions
      summary: List agent revisions
      tags:
        - revisions
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - agents:read
      security:
        - ServiceKey: []
      description: List agent revisions
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/AgentRevision"
                  next_cursor:
                    type:
                      - string
                      - "null"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - items
                  - next_cursor
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/agents/{agent_id}/revisions/{revision_id}:
    get:
      operationId: getAgentRevision
      summary: Get agent revision
      tags:
        - revision_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - agents:read
      security:
        - ServiceKey: []
      description: Get agent revision
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: revision_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/AgentRevision"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/model-profiles:
    get:
      operationId: listModelProfile
      summary: List model-profiles
      tags:
        - model-profiles
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - models:read
      security:
        - ServiceKey: []
      description: List model-profiles
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/ModelProfile"
                  next_cursor:
                    type:
                      - string
                      - "null"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - items
                  - next_cursor
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/model-profiles/{model_profile_id}:
    get:
      operationId: getModelProfile
      summary: Get model_profile
      tags:
        - model_profile_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - models:read
      security:
        - ServiceKey: []
      description: Get model_profile
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: model_profile_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/ModelProfile"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/connections:
    get:
      operationId: listConnection
      summary: List connections
      tags:
        - connections
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - connections:read
      security:
        - ServiceKey: []
        - ActorToken: []
      description: List connections
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Connection"
                  next_cursor:
                    type:
                      - string
                      - "null"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - items
                  - next_cursor
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
    post:
      operationId: createConnection
      summary: Create connection
      tags:
        - connections
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - connections:write
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Pending operator review. Server validates owner and HTTPS
        destinations, binds tenant/user/service owner, freezes operation schema.
        Only activated tools execute. Financial execution and arbitrary code are
        rejected. Service actors cannot consume user-owned connections.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "201":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Connection"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateConnection"
            example:
              name: Acme tickets
              type: customer_https
              owner:
                type: tenant
              base_url: https://tools.acme.invalid
              authentication:
                type: mystro_signed_request
              operations:
                - name: get_ticket
                  effect: read
                  path: /tickets/read
                  input_schema:
                    type: object
                    properties:
                      ticket_id:
                        type: string
                    required:
                      - ticket_id
                    additionalProperties: false
                  output_schema:
                    type: object
                    properties:
                      title:
                        type: string
                    required:
                      - title
                    additionalProperties: false
                - name: add_note
                  effect: write
                  path: /tickets/notes
                  reconciliation_path: /operations/{operation_id}
                  input_schema:
                    type: object
                    properties:
                      ticket_id:
                        type: string
                      note:
                        type: string
                    required:
                      - ticket_id
                      - note
                    additionalProperties: false
                  output_schema:
                    type: object
                    properties:
                      note_id:
                        type: string
                    required:
                      - note_id
                    additionalProperties: false
  /v1/tenants/{tenant_id}/environments/{environment}/connections/{connection_id}:
    get:
      operationId: getConnection
      summary: Get connection
      tags:
        - connection_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - connections:read
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Get connection
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: connection_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Connection"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
    patch:
      operationId: updateConnection
      summary: Update connection
      tags:
        - connection_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - connections:write
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Update connection
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: connection_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Connection"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DisableConnection"
  /v1/tenants/{tenant_id}/environments/{environment}/connections/{connection_id}/revoke:
    post:
      operationId: revokeConnection
      summary: Revoke connection and pending approvals
      tags:
        - revoke
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - connections:write
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Revoke connection and pending approvals
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: connection_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Connection"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/tools:
    get:
      operationId: listTool
      summary: List tools
      tags:
        - tools
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - tools:read
      security:
        - ServiceKey: []
        - ActorToken: []
      description: List tools
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Tool"
                  next_cursor:
                    type:
                      - string
                      - "null"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - items
                  - next_cursor
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/tools/{tool_id}:
    get:
      operationId: getTool
      summary: Get tool
      tags:
        - tool_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - tools:read
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Get tool
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: tool_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Tool"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/conversations:
    get:
      operationId: listConversation
      summary: List conversations
      tags:
        - conversations
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - conversations:read
      security:
        - ServiceKey: []
        - ActorToken: []
      description: List conversations
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Conversation"
                  next_cursor:
                    type:
                      - string
                      - "null"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - items
                  - next_cursor
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
    post:
      operationId: createConversation
      summary: Create conversation
      tags:
        - conversations
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - conversations:write
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Create conversation
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "201":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Conversation"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateConversation"
  /v1/tenants/{tenant_id}/environments/{environment}/conversations/{conversation_id}:
    get:
      operationId: getConversation
      summary: Get conversation
      tags:
        - conversation_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - conversations:read
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Get conversation
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: conversation_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Conversation"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
    patch:
      operationId: updateConversation
      summary: Update conversation
      tags:
        - conversation_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - conversations:write
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Update conversation
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: conversation_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Conversation"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Archive"
    delete:
      operationId: deleteConversation
      summary: Delete conversation
      tags:
        - conversation_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - conversations:write
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Immediately deny access and revoke derived authority. Live purge
        within 24 hours; backups expire separately within 30 days. Restore
        replays deletion journal before serving.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: conversation_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "202":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
            Location:
              schema:
                type: string
              description: Poll the accepted resource at this path.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/DeletionJob"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/conversations/{conversation_id}/runs:
    post:
      operationId: createRun
      summary: Start durable work
      tags:
        - runs
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - runs:write
      security:
        - ServiceKey: []
        - ActorToken: []
      description: "202 only after control-plane acceptance reservation and cell
        persistence. Prefer: wait=10 may return the same terminal run with 200;
        disconnect never cancels. Admission grants a bounded 15-minute durable
        execution authorization, independent of the five-minute actor token used
        to submit the request. Persist the original opaque lease ID, user epoch,
        workspace and scopes with the run. Each dispatch still checks the
        current parent key, tenant/environment generation, current user status
        and revocation; revocation invalidates admitted authority. Token expiry
        alone does not interrupt admitted work. The 15-minute total
        authorization wall clock includes queue and human-approval waits; active
        execution remains at most five minutes and an individual approval at
        most ten minutes. Retry is explicit new key plus retry_of_run_id;
        unresolved writes reject retry. Per-workspace one active, cell two
        active, queue100 and five-minute start deadline. Model admission fails
        closed on budget/control-plane outage."
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: conversation_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
        - name: Prefer
          in: header
          required: false
          schema:
            type: string
            enum:
              - wait=10
      responses:
        "200":
          description: Same run reached terminal state within requested wait
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Run"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "202":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
            Location:
              schema:
                type: string
              description: Poll the accepted resource at this path.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Run"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRun"
            example:
              input:
                - type: text
                  text: Read ticket T-104 and propose a concise internal follow-up note.
  /v1/tenants/{tenant_id}/environments/{environment}/runs:
    get:
      operationId: listRun
      summary: List runs
      tags:
        - runs
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - runs:read
      security:
        - ServiceKey: []
        - ActorToken: []
      description: List runs
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Run"
                  next_cursor:
                    type:
                      - string
                      - "null"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - items
                  - next_cursor
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/runs/{run_id}:
    get:
      operationId: getRun
      summary: Get run
      tags:
        - run_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - runs:read
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Get run
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: run_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Run"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/runs/{run_id}/cancel:
    post:
      operationId: cancelRun
      summary: Request run cancellation
      tags:
        - cancel
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - runs:write
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Stop new tool dispatch and interrupt runtime. Cancellation is best
        effort; an unresolved dispatched write yields outcome_unknown, never
        false cancelled success.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: run_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "202":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
            Location:
              schema:
                type: string
              description: Poll the accepted resource at this path.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Run"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/runs/{run_id}/events:
    get:
      operationId: listRunEvents
      summary: Read durable ordered run events
      tags:
        - events
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - runs:read
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Stable durable per-run sequence. Opaque cursor bound to
        tenant/environment/run. Same IDs as SSE; historic terminal events remain
        immutable.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: run_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
        - name: after_event_id
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Event"
                  next_cursor:
                    type:
                      - string
                      - "null"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - items
                  - next_cursor
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/runs/{run_id}/events/stream:
    get:
      operationId: streamRunEvents
      summary: Stream durable run events over SSE
      tags:
        - stream
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - runs:read
      security:
        - ServiceKey: []
        - ActorToken: []
      description: "text/event-stream: id is durable event ID, event is typed event
        name, data is Event JSON. Reconnect with Last-Event-ID; client
        deduplicates. Heartbeat at most15s; reauthorize within15s. No guaranteed
        token-level stream. Replay expiry returns410 before stream opens.
        Disconnect does not cancel."
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: run_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: Last-Event-ID
          in: header
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: SSE durable event stream
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            text/event-stream:
              schema:
                type: string
              example: |+
                id: evt_1
                event: run.queued
                data: {"id":"evt_1","run_id":"run_demo","sequence":1,"type":"run.queued","created_at":"2026-09-07T10:00:00Z","data":{}}

        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/approvals:
    get:
      operationId: listApproval
      summary: List approvals
      tags:
        - approvals
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - approvals:read
      security:
        - ServiceKey: []
        - ActorToken: []
      description: List approvals
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Approval"
                  next_cursor:
                    type:
                      - string
                      - "null"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - items
                  - next_cursor
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/approvals/{approval_id}:
    get:
      operationId: getApproval
      summary: Get approval
      tags:
        - approval_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - approvals:read
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Get approval
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: approval_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Approval"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/approvals/{approval_id}/decision:
    post:
      operationId: decideApproval
      summary: Approve or deny exact tool operation
      tags:
        - decision
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - approvals:write
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Authenticated current user only, or separately authorized
        approval:delegate backend asserting current user. Service actors cannot
        approve. Uses server-stored immutable10min operation authorization bound
        to run, actor, input hash, tool revision and connector generation.
        Approval persists continuation, releases runtime and resumes without
        replaying completed tools.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: approval_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Approval"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApprovalDecision"
      x-authorization:
        any_of:
          - approvals:write with current user actor
          - approval:delegate with explicit current user identity
        denied_actor_types:
          - service_actor
  /v1/tenants/{tenant_id}/environments/{environment}/files:
    get:
      operationId: listFile
      summary: List files
      tags:
        - files
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - files:read
      security:
        - ServiceKey: []
        - ActorToken: []
      description: List files
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/File"
                  next_cursor:
                    type:
                      - string
                      - "null"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - items
                  - next_cursor
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
    post:
      operationId: createFile
      summary: Create file
      tags:
        - files
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - files:write
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Create file
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "201":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/File"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UploadFile"
  /v1/tenants/{tenant_id}/environments/{environment}/files/{file_id}:
    get:
      operationId: getFile
      summary: Get file
      tags:
        - file_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - files:read
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Get file
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: file_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/File"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
    delete:
      operationId: deleteFile
      summary: Delete file
      tags:
        - file_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - files:write
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Immediately deny access and revoke derived authority. Live purge
        within 24 hours; backups expire separately within 30 days. Restore
        replays deletion journal before serving.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: file_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "202":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
            Location:
              schema:
                type: string
              description: Poll the accepted resource at this path.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/DeletionJob"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/files/{file_id}/download:
    get:
      operationId: downloadFile
      summary: Download available file through authenticated proxy
      tags:
        - download
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - files:read
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Only scanned available files; authorization checked on every
        download. No public signed URL. nosniff and attachment disposition.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: file_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: Bounded file bytes
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
            Content-Disposition:
              schema:
                type: string
            X-Content-Type-Options:
              schema:
                type: string
              example: nosniff
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema: {}
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/webhook-endpoints:
    get:
      operationId: listWebhookEndpoint
      summary: List webhook-endpoints
      tags:
        - webhook-endpoints
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - webhooks:read
      security:
        - ServiceKey: []
      description: Environment-wide administrative webhook capability, restricted to
        the explicit webhooks scope. Notifications contain reference-only event
        ID, run ID, type, status and creation time; never prompts, results, file
        content or secrets. The webhook administration scope is not authority to
        read end-user content. Protected run/file reads independently require
        the receiving application actor authorization. New or changed
        destinations require operator review before dispatch.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/WebhookEndpoint"
                  next_cursor:
                    type:
                      - string
                      - "null"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - items
                  - next_cursor
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
    post:
      operationId: createWebhookEndpoint
      summary: Create webhook_endpoint
      tags:
        - webhook-endpoints
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - webhooks:write
      security:
        - ServiceKey: []
      description: Environment-wide administrative webhook capability, restricted to
        the explicit webhooks scope. Notifications contain reference-only event
        ID, run ID, type, status and creation time; never prompts, results, file
        content or secrets. The webhook administration scope is not authority to
        read end-user content. Protected run/file reads independently require
        the receiving application actor authorization. New or changed
        destinations require operator review before dispatch.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "201":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/WebhookSecret"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWebhook"
  /v1/tenants/{tenant_id}/environments/{environment}/webhook-endpoints/{webhook_endpoint_id}:
    get:
      operationId: getWebhookEndpoint
      summary: Get webhook_endpoint
      tags:
        - webhook_endpoint_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - webhooks:read
      security:
        - ServiceKey: []
      description: Environment-wide administrative webhook capability, restricted to
        the explicit webhooks scope. Notifications contain reference-only event
        ID, run ID, type, status and creation time; never prompts, results, file
        content or secrets. The webhook administration scope is not authority to
        read end-user content. Protected run/file reads independently require
        the receiving application actor authorization. New or changed
        destinations require operator review before dispatch.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: webhook_endpoint_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/WebhookEndpoint"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
    patch:
      operationId: updateWebhookEndpoint
      summary: Update webhook_endpoint
      tags:
        - webhook_endpoint_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - webhooks:write
      security:
        - ServiceKey: []
      description: Environment-wide administrative webhook capability, restricted to
        the explicit webhooks scope. Notifications contain reference-only event
        ID, run ID, type, status and creation time; never prompts, results, file
        content or secrets. The webhook administration scope is not authority to
        read end-user content. Protected run/file reads independently require
        the receiving application actor authorization. New or changed
        destinations require operator review before dispatch.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: webhook_endpoint_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/WebhookEndpoint"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateWebhook"
    delete:
      operationId: deleteWebhookEndpoint
      summary: Delete webhook_endpoint
      tags:
        - webhook_endpoint_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - webhooks:write
      security:
        - ServiceKey: []
      description: Immediately deny access and revoke derived authority. Live purge
        within 24 hours; backups expire separately within 30 days. Restore
        replays deletion journal before serving.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: webhook_endpoint_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "202":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
            Location:
              schema:
                type: string
              description: Poll the accepted resource at this path.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/DeletionJob"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/webhook-endpoints/{webhook_endpoint_id}/rotate-secret:
    post:
      operationId: rotateWebhookSecret
      summary: Rotate webhook signing secret
      tags:
        - rotate-secret
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - webhooks:write
      security:
        - ServiceKey: []
      description: Fresh response only, no-store; replay exposes original rotation
        metadata only. Rotation returns current_version, previous_version and
        previous_retire_at. Sender includes both signature digests during a
        bounded 24-hour overlap. A second distinct rotation returns 409
        rotation_overlap_active until the previous version retires. The same
        idempotency key replays original metadata without a secret, even after
        later rotations. A lost new-secret response cannot be recovered; retain
        the previous verifier during overlap, then perform a fresh rotation
        after retirement and safely store its secret before resuming deliveries.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: webhook_endpoint_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/WebhookSecret"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/webhook-deliveries:
    get:
      operationId: listWebhookDelivery
      summary: List webhook-deliveries
      tags:
        - webhook-deliveries
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - webhooks:read
      security:
        - ServiceKey: []
      description: Environment-wide administrative webhook capability, restricted to
        the explicit webhooks scope. Notifications contain reference-only event
        ID, run ID, type, status and creation time; never prompts, results, file
        content or secrets. The webhook administration scope is not authority to
        read end-user content. Protected run/file reads independently require
        the receiving application actor authorization. New or changed
        destinations require operator review before dispatch.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/WebhookDelivery"
                  next_cursor:
                    type:
                      - string
                      - "null"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - items
                  - next_cursor
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/webhook-deliveries/{webhook_delivery_id}:
    get:
      operationId: getWebhookDelivery
      summary: Get webhook_delivery
      tags:
        - webhook_delivery_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - webhooks:read
      security:
        - ServiceKey: []
      description: Environment-wide administrative webhook capability, restricted to
        the explicit webhooks scope. Notifications contain reference-only event
        ID, run ID, type, status and creation time; never prompts, results, file
        content or secrets. The webhook administration scope is not authority to
        read end-user content. Protected run/file reads independently require
        the receiving application actor authorization. New or changed
        destinations require operator review before dispatch.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: webhook_delivery_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/WebhookDelivery"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/webhook-deliveries/{webhook_delivery_id}/replay:
    post:
      operationId: replayWebhookDelivery
      summary: Replay failed reference-only webhook
      tags:
        - replay
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - webhooks:write
      security:
        - ServiceKey: []
      description: Environment-wide administrative webhook capability, restricted to
        the explicit webhooks scope. Notifications contain reference-only event
        ID, run ID, type, status and creation time; never prompts, results, file
        content or secrets. The webhook administration scope is not authority to
        read end-user content. Protected run/file reads independently require
        the receiving application actor authorization. New or changed
        destinations require operator review before dispatch. Replay delivery
        does not rerun the agent or repeat tool operations.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: webhook_delivery_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "202":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
            Location:
              schema:
                type: string
              description: Poll the accepted resource at this path.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/WebhookDelivery"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/usage:
    get:
      operationId: getUsage
      summary: Inspect usage aggregates and held reservations
      tags:
        - usage
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - usage:read
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Returns only the own authenticated actor usage in this tenant and
        environment, including held reservations. Public credentials cannot
        request tenant billing totals in the MVP; those remain in an authorized
        human console. Measured vendor cost is separate from customer rating.
        rated_charge_usd is null with rating_status:unrated until all included
        usage is rated; a rated zero is explicit. Unknown supplier usage remains
        provisional and reserved. Omit both from and to to use the current UTC
        month start through request time. When either bound is supplied, both
        are required as UTC ISO 8601 timestamps ending in Z; from must precede
        to and the window must not exceed 90 days. Invalid windows return 400.
      x-date-window:
        default: current_utc_month_to_now
        paired:
          - from
          - to
        timezone: UTC
        ordering: from < to
        max_duration_days: 90
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: from
          in: query
          required: false
          description: Optional UTC timestamp ending in Z. Supply both from and to, with
            from < to and a maximum 90-day window; omit both for current UTC
            month start through now.
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          required: false
          description: Optional UTC timestamp ending in Z. Supply both from and to, with
            from < to and a maximum 90-day window; omit both for current UTC
            month start through now.
          schema:
            type: string
            format: date-time
        - name: run_id
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Usage"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/usage/records:
    get:
      operationId: listUsageRecords
      summary: Read immutable usage ledger
      tags:
        - records
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - usage:read
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Read immutable ledger entries belonging only to the own
        authenticated actor. Measured supplier cost is retained even when rating
        is pending. rated_charge_usd is null if and only if rating_status is
        unrated; rated zero must be explicit. Tenant-wide billing access is not
        granted by public usage:read.
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/UsageRecord"
                  next_cursor:
                    type:
                      - string
                      - "null"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - items
                  - next_cursor
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/quotas:
    get:
      operationId: getQuotas
      summary: Get quotas
      tags:
        - quotas
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - quotas:read
      security:
        - ServiceKey: []
      description: Get quotas
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Quotas"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
    patch:
      operationId: updateQuotas
      summary: Update quotas
      tags:
        - quotas
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - quotas:write
      security:
        - ServiceKey: []
      description: Update quotas
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Quotas"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateQuotas"
  /v1/tenants/{tenant_id}/environments/{environment}/settings:
    get:
      operationId: getSettings
      summary: Get settings
      tags:
        - settings
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - settings:read
      security:
        - ServiceKey: []
      description: Get settings
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Settings"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
    patch:
      operationId: updateSettings
      summary: Update settings
      tags:
        - settings
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - settings:write
      security:
        - ServiceKey: []
      description: Update settings
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/Settings"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateSettings"
  /v1/tenants/{tenant_id}/environments/{environment}/audit:
    get:
      operationId: listAuditEntries
      summary: Read sanitized audit events
      tags:
        - audit
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - audit:read
      security:
        - ServiceKey: []
      description: Read sanitized audit events
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/AuditEntry"
                  next_cursor:
                    type:
                      - string
                      - "null"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - items
                  - next_cursor
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /v1/tenants/{tenant_id}/environments/{environment}/deletion-jobs/{deletion_job_id}:
    get:
      operationId: getDeletionJob
      summary: Inspect purge and backup expiry
      tags:
        - deletion_job_id
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes:
        - deletions:read
      security:
        - ServiceKey: []
        - ActorToken: []
      description: Inspect purge and backup expiry
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: environment
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EnvironmentName"
        - name: deletion_job_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    $ref: "#/components/schemas/DeletionJob"
                  request_id:
                    type: string
                    minLength: 1
                    maxLength: 128
                required:
                  - data
                  - request_id
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
  /.well-known/jwks.json:
    get:
      operationId: getToolJwks
      summary: Read Mystro outbound verification keys
      tags:
        - jwks.json
      x-release-stage: proposed
      x-visibility: public
      x-required-scopes: []
      security: []
      description: Customer tools verify JWT kid/signature/audience/expiry/operation
        digest/generation using this keyset. Public keys only; key rotation
        overlaps outstanding token lifetimes.
      parameters: []
      responses:
        "200":
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
                minLength: 1
                maxLength: 128
              description: Sanitized support correlation ID.
            Cache-Control:
              schema:
                type: string
              example: no-store
              description: Responses containing credentials or private data are never cached.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Jwks"
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "409":
          $ref: "#/components/responses/Error409"
        "410":
          $ref: "#/components/responses/Error410"
        "429":
          $ref: "#/components/responses/Error429"
        "503":
          $ref: "#/components/responses/Error503"
components:
  securitySchemes:
    ServiceKey:
      type: http
      scheme: bearer
      description: Server-only API key. Per-environment, immutable scopes and actor;
        management keys cannot mint keys or imply end-user content access.
    ActorToken:
      type: http
      scheme: bearer
      bearerFormat: opaque
      description: Delegated actor request tokens last five minutes and authorize new
        API requests only. Bound to current workspace, scopes, parent-key epoch
        and user epoch; revocation closes streams within 15 seconds. A run
        accepted before token expiry has a separate, bounded 15-minute durable
        execution authorization tied to its original opaque lease, current
        parent key and current user/workspace revocation. Expiry of the request
        token never grants access to additional resources or extends admitted
        authorization.
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 200
        pattern: ^[A-Za-z0-9_.:-]+$
    Cursor:
      name: cursor
      in: query
      required: false
      schema:
        type: string
        maxLength: 2048
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
  responses:
    Error400:
      description: Invalid request
      headers:
        X-Request-Id:
          schema:
            type: string
            minLength: 1
            maxLength: 128
          description: Sanitized support correlation ID.
        Cache-Control:
          schema:
            type: string
          example: no-store
          description: Responses containing credentials or private data are never cached.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Error401:
      description: Invalid or expired authentication
      headers:
        X-Request-Id:
          schema:
            type: string
            minLength: 1
            maxLength: 128
          description: Sanitized support correlation ID.
        Cache-Control:
          schema:
            type: string
          example: no-store
          description: Responses containing credentials or private data are never cached.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Error403:
      description: Scope or human authorization required
      headers:
        X-Request-Id:
          schema:
            type: string
            minLength: 1
            maxLength: 128
          description: Sanitized support correlation ID.
        Cache-Control:
          schema:
            type: string
          example: no-store
          description: Responses containing credentials or private data are never cached.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Error404:
      description: Missing or inaccessible resource
      headers:
        X-Request-Id:
          schema:
            type: string
            minLength: 1
            maxLength: 128
          description: Sanitized support correlation ID.
        Cache-Control:
          schema:
            type: string
          example: no-store
          description: Responses containing credentials or private data are never cached.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Error409:
      description: Idempotency, ownership or state conflict
      headers:
        X-Request-Id:
          schema:
            type: string
            minLength: 1
            maxLength: 128
          description: Sanitized support correlation ID.
        Cache-Control:
          schema:
            type: string
          example: no-store
          description: Responses containing credentials or private data are never cached.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Error410:
      description: Expired idempotency replay; never recreate
      headers:
        X-Request-Id:
          schema:
            type: string
            minLength: 1
            maxLength: 128
          description: Sanitized support correlation ID.
        Cache-Control:
          schema:
            type: string
          example: no-store
          description: Responses containing credentials or private data are never cached.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Error429:
      description: Rate, budget or quota exceeded
      headers:
        X-Request-Id:
          schema:
            type: string
            minLength: 1
            maxLength: 128
          description: Sanitized support correlation ID.
        Cache-Control:
          schema:
            type: string
          example: no-store
          description: Responses containing credentials or private data are never cached.
        Retry-After:
          schema:
            type: integer
            minimum: 1
          description: Seconds until retry may be attempted.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Error503:
      description: Admission or dependency unavailable
      headers:
        X-Request-Id:
          schema:
            type: string
            minLength: 1
            maxLength: 128
          description: Sanitized support correlation ID.
        Cache-Control:
          schema:
            type: string
          example: no-store
          description: Responses containing credentials or private data are never cached.
        Retry-After:
          schema:
            type: integer
            minimum: 1
          description: Seconds until retry may be attempted.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  schemas:
    Id:
      type: string
      minLength: 1
      maxLength: 128
    Money:
      type: string
      pattern: ^(0|[1-9][0-9]*)(\.[0-9]{1,6})?$
      example: "1.00"
    Scope:
      type: string
      enum:
        - tenants:read
        - tenants:write
        - environments:read
        - environments:write
        - keys:read
        - keys:revoke
        - users:read
        - users:write
        - service-actors:read
        - service-actors:write
        - identity:delegate
        - approval:delegate
        - workspaces:read
        - workspaces:write
        - agents:read
        - agents:write
        - models:read
        - connections:read
        - connections:write
        - tools:read
        - conversations:read
        - conversations:write
        - runs:read
        - runs:write
        - approvals:read
        - approvals:write
        - files:read
        - files:write
        - webhooks:read
        - webhooks:write
        - usage:read
        - quotas:read
        - quotas:write
        - settings:read
        - settings:write
        - audit:read
        - deletions:read
    Actor:
      type: object
      additionalProperties: false
      properties:
        type:
          type: string
          enum:
            - user
            - service_actor
        id:
          type: string
          minLength: 1
          maxLength: 128
      required:
        - type
        - id
    EnvironmentName:
      type: string
      enum:
        - sandbox
        - production
    Error:
      type: object
      additionalProperties: false
      properties:
        error:
          type: object
          additionalProperties: false
          properties:
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
          required:
            - code
            - message
            - retryable
        request_id:
          type: string
          minLength: 1
          maxLength: 128
      required:
        - error
        - request_id
      example:
        error:
          code: scope_required
          message: The credential does not authorize this operation.
          retryable: false
        request_id: req_demo
    Tenant:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        name:
          type: string
        status:
          type: string
          enum:
            - pending
            - active
            - suspended
            - deleting
            - deleted
        created_at:
          type: string
          format: date-time
      required:
        - id
        - name
        - status
        - created_at
      example:
        id: ten_demo
        name: Acme Operations
        status: pending
        created_at: 2026-09-07T10:00:00Z
    UpdateTenant:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
      required:
        - name
    Environment:
      type: object
      additionalProperties: true
      properties:
        tenant_id:
          type: string
          minLength: 1
          maxLength: 128
        environment:
          $ref: "#/components/schemas/EnvironmentName"
        status:
          type: string
          enum:
            - absent
            - provisioning
            - ready
            - failed
            - suspended
            - deleting
            - deleted
        generation:
          type: integer
          minimum: 0
        failure_code:
          type:
            - string
            - "null"
      required:
        - tenant_id
        - environment
        - status
        - generation
        - failure_code
    User:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        tenant_id:
          type: string
          minLength: 1
          maxLength: 128
        environment:
          $ref: "#/components/schemas/EnvironmentName"
        external_id:
          type: string
          minLength: 1
          maxLength: 256
        status:
          type: string
          enum:
            - active
            - disabled
            - deleting
            - deleted
        created_at:
          type: string
          format: date-time
      required:
        - id
        - tenant_id
        - environment
        - external_id
        - status
        - created_at
    CreateUser:
      type: object
      additionalProperties: false
      properties:
        external_id:
          type: string
          minLength: 1
          maxLength: 256
      required:
        - external_id
    UpdateActor:
      type: object
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
            - active
            - disabled
      required:
        - status
    ServiceActor:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        tenant_id:
          type: string
          minLength: 1
          maxLength: 128
        environment:
          $ref: "#/components/schemas/EnvironmentName"
        name:
          type: string
        status:
          type: string
          enum:
            - active
            - disabled
            - deleting
            - deleted
        created_at:
          type: string
          format: date-time
      required:
        - id
        - tenant_id
        - environment
        - name
        - status
        - created_at
    CreateServiceActor:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
      required:
        - name
    ActorSessionRequest:
      type: object
      additionalProperties: false
      properties:
        actor:
          type: object
          additionalProperties: false
          properties:
            type:
              type: string
              const: user
            id:
              type: string
              minLength: 1
              maxLength: 128
          required:
            - type
            - id
        workspace_id:
          type: string
          minLength: 1
          maxLength: 128
        scopes:
          type: array
          items:
            $ref: "#/components/schemas/Scope"
          minItems: 1
          uniqueItems: true
      required:
        - actor
        - workspace_id
        - scopes
    ActorSession:
      type: object
      additionalProperties: false
      properties:
        token:
          type: string
          x-sensitive: true
          description: One-time fresh response only. Never logged, cached, persisted in
            replay, or included in analytics.
        expires_at:
          type: string
          format: date-time
        workspace_id:
          type: string
          minLength: 1
          maxLength: 128
        actor:
          $ref: "#/components/schemas/Actor"
        scopes:
          type: array
          items:
            $ref: "#/components/schemas/Scope"
        token_available:
          type: boolean
      required:
        - expires_at
        - workspace_id
        - actor
        - scopes
        - token_available
      description: Fresh issuance contains token and token_available:true; replay has
        token_available:false and omits token. Obtain a new lease with a fresh
        idempotency key.
      allOf:
        - if:
            properties:
              token_available:
                const: true
          then:
            required:
              - token
          else:
            not:
              required:
                - token
    Workspace:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        tenant_id:
          type: string
          minLength: 1
          maxLength: 128
        environment:
          $ref: "#/components/schemas/EnvironmentName"
        owner:
          $ref: "#/components/schemas/Actor"
        status:
          type: string
          enum:
            - active
            - deleting
            - deleted
        created_at:
          type: string
          format: date-time
      required:
        - id
        - tenant_id
        - environment
        - owner
        - status
        - created_at
    CreateWorkspace:
      type: object
      additionalProperties: false
      properties:
        owner:
          $ref: "#/components/schemas/Actor"
      required:
        - owner
    Agent:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        tenant_id:
          type: string
          minLength: 1
          maxLength: 128
        environment:
          $ref: "#/components/schemas/EnvironmentName"
        name:
          type: string
        archived:
          type: boolean
        latest_revision_id:
          type:
            - string
            - "null"
        created_at:
          type: string
          format: date-time
      required:
        - id
        - tenant_id
        - environment
        - name
        - archived
        - latest_revision_id
        - created_at
    CreateAgent:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
      required:
        - name
    Archive:
      type: object
      additionalProperties: false
      properties:
        archived:
          type: boolean
      required:
        - archived
    RunLimits:
      type: object
      additionalProperties: false
      properties:
        max_active_seconds:
          type: integer
          minimum: 1
          maximum: 300
          default: 300
        max_steps:
          type: integer
          minimum: 1
          maximum: 20
          default: 20
        max_input_tokens:
          type: integer
          minimum: 1
          maximum: 32768
          default: 32768
        max_output_tokens:
          type: integer
          minimum: 1
          maximum: 8192
          default: 8192
        max_cost_usd:
          $ref: "#/components/schemas/Money"
      required:
        - max_active_seconds
        - max_steps
        - max_input_tokens
        - max_output_tokens
        - max_cost_usd
    CreateAgentRevision:
      type: object
      additionalProperties: false
      properties:
        instructions:
          type: string
          minLength: 1
          maxLength: 32768
        model_profile:
          type: string
          enum:
            - standard
        tool_ids:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 128
          maxItems: 20
          uniqueItems: true
        memory:
          type: object
          additionalProperties: false
          properties:
            mode:
              type: string
              const: off
          required:
            - mode
        limits:
          $ref: "#/components/schemas/RunLimits"
      required:
        - instructions
        - model_profile
        - tool_ids
        - memory
        - limits
      example:
        instructions: Summarize the supplied operations report. Use only approved tools.
        model_profile: standard
        tool_ids: []
        memory:
          mode: off
        limits:
          max_active_seconds: 300
          max_steps: 20
          max_input_tokens: 32768
          max_output_tokens: 8192
          max_cost_usd: "1.00"
    AgentRevision:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        tenant_id:
          type: string
          minLength: 1
          maxLength: 128
        environment:
          $ref: "#/components/schemas/EnvironmentName"
        agent_id:
          type: string
          minLength: 1
          maxLength: 128
        instructions:
          type: string
        model_profile:
          type: string
          enum:
            - standard
        tool_ids:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 128
        memory:
          type: object
          additionalProperties: false
          properties:
            mode:
              type: string
              const: off
          required:
            - mode
        limits:
          $ref: "#/components/schemas/RunLimits"
        created_at:
          type: string
          format: date-time
      required:
        - id
        - tenant_id
        - environment
        - agent_id
        - instructions
        - model_profile
        - tool_ids
        - memory
        - limits
        - created_at
    ModelProfile:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          enum:
            - standard
        name:
          type: string
        input_token_limit:
          type: integer
        output_token_limit:
          type: integer
        available:
          type: boolean
      required:
        - id
        - name
        - input_token_limit
        - output_token_limit
        - available
    ConnectionOwner:
      oneOf:
        - type: object
          additionalProperties: false
          properties:
            type:
              type: string
              enum:
                - tenant
          required:
            - type
        - $ref: "#/components/schemas/Actor"
    ToolOperation:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          pattern: ^[a-z][a-z0-9_]{0,63}$
        effect:
          type: string
          enum:
            - read
            - write
        path:
          type: string
          pattern: ^/[^?#]*$
        reconciliation_path:
          type: string
          pattern: ^/[^?#]*$
        input_schema:
          type: object
          description: JSON Schema 2020-12, reviewed and frozen before activation.
        output_schema:
          type: object
          description: JSON Schema 2020-12, reviewed and frozen before activation.
      required:
        - name
        - effect
        - path
        - input_schema
        - output_schema
      description: Writes require reconciliation_path and human approval. Financial
        execution, arbitrary code and credential return are prohibited.
      if:
        properties:
          effect:
            const: write
        required:
          - effect
      then:
        required:
          - reconciliation_path
    CreateConnection:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
        type:
          type: string
          enum:
            - customer_https
        owner:
          $ref: "#/components/schemas/ConnectionOwner"
        base_url:
          type: string
          format: uri
          pattern: ^https://
        authentication:
          type: object
          additionalProperties: false
          properties:
            type:
              type: string
              enum:
                - mystro_signed_request
          required:
            - type
        operations:
          type: array
          items:
            $ref: "#/components/schemas/ToolOperation"
          minItems: 1
          maxItems: 20
      required:
        - name
        - type
        - owner
        - base_url
        - authentication
        - operations
      example:
        name: Acme tickets
        type: customer_https
        owner:
          type: tenant
        base_url: https://tools.acme.invalid
        authentication:
          type: mystro_signed_request
        operations:
          - name: get_ticket
            effect: read
            path: /tickets/read
            input_schema:
              type: object
              properties:
                ticket_id:
                  type: string
              required:
                - ticket_id
              additionalProperties: false
            output_schema:
              type: object
              properties:
                title:
                  type: string
              required:
                - title
              additionalProperties: false
          - name: add_note
            effect: write
            path: /tickets/notes
            reconciliation_path: /operations/{operation_id}
            input_schema:
              type: object
              properties:
                ticket_id:
                  type: string
                note:
                  type: string
              required:
                - ticket_id
                - note
              additionalProperties: false
            output_schema:
              type: object
              properties:
                note_id:
                  type: string
              required:
                - note_id
              additionalProperties: false
    Connection:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        tenant_id:
          type: string
          minLength: 1
          maxLength: 128
        environment:
          $ref: "#/components/schemas/EnvironmentName"
        name:
          type: string
        type:
          type: string
          enum:
            - customer_https
        owner:
          $ref: "#/components/schemas/ConnectionOwner"
        base_url:
          type: string
          format: uri
        status:
          type: string
          enum:
            - pending_review
            - active
            - disabled
            - revoked
        generation:
          type: integer
          minimum: 1
        tool_ids:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 128
        created_at:
          type: string
          format: date-time
      required:
        - id
        - tenant_id
        - environment
        - name
        - type
        - owner
        - base_url
        - status
        - generation
        - tool_ids
        - created_at
    DisableConnection:
      type: object
      additionalProperties: false
      properties:
        disabled:
          type: boolean
      required:
        - disabled
    Tool:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        tenant_id:
          type: string
          minLength: 1
          maxLength: 128
        environment:
          $ref: "#/components/schemas/EnvironmentName"
        connection_id:
          type: string
          minLength: 1
          maxLength: 128
        revision_id:
          type: string
          minLength: 1
          maxLength: 128
        name:
          type: string
        effect:
          type: string
          enum:
            - read
            - write
        path:
          type: string
        reconciliation_path:
          type: string
        input_schema:
          type: object
        output_schema:
          type: object
        created_at:
          type: string
          format: date-time
      required:
        - id
        - tenant_id
        - environment
        - connection_id
        - revision_id
        - name
        - effect
        - path
        - input_schema
        - output_schema
        - created_at
    CreateConversation:
      type: object
      additionalProperties: false
      properties:
        workspace_id:
          type: string
          minLength: 1
          maxLength: 128
        agent_revision_id:
          type: string
          minLength: 1
          maxLength: 128
      required:
        - workspace_id
        - agent_revision_id
    Conversation:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        tenant_id:
          type: string
          minLength: 1
          maxLength: 128
        environment:
          $ref: "#/components/schemas/EnvironmentName"
        workspace_id:
          type: string
          minLength: 1
          maxLength: 128
        agent_revision_id:
          type: string
          minLength: 1
          maxLength: 128
        archived:
          type: boolean
        created_at:
          type: string
          format: date-time
      required:
        - id
        - tenant_id
        - environment
        - workspace_id
        - agent_revision_id
        - archived
        - created_at
    RunInput:
      type: array
      minItems: 1
      maxItems: 10
      items:
        oneOf:
          - type: object
            additionalProperties: false
            properties:
              type:
                const: text
              text:
                type: string
                minLength: 1
                maxLength: 131072
            required:
              - type
              - text
          - type: object
            additionalProperties: false
            properties:
              type:
                const: file
              file_id:
                $ref: "#/components/schemas/Id"
            required:
              - type
              - file_id
    CreateRun:
      type: object
      additionalProperties: false
      properties:
        input:
          $ref: "#/components/schemas/RunInput"
        retry_of_run_id:
          type: string
          minLength: 1
          maxLength: 128
      required:
        - input
      example:
        input:
          - type: text
            text: Read ticket T-104 and propose a concise internal follow-up note.
    RunStatus:
      type: string
      enum:
        - queued
        - running
        - requires_action
        - cancel_requested
        - succeeded
        - failed
        - cancelled
        - expired
        - interrupted
        - outcome_unknown
    Run:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        tenant_id:
          type: string
          minLength: 1
          maxLength: 128
        environment:
          $ref: "#/components/schemas/EnvironmentName"
        conversation_id:
          type: string
          minLength: 1
          maxLength: 128
        workspace_id:
          type: string
          minLength: 1
          maxLength: 128
        actor:
          $ref: "#/components/schemas/Actor"
        agent_revision_id:
          type: string
          minLength: 1
          maxLength: 128
        status:
          $ref: "#/components/schemas/RunStatus"
        retry_of_run_id:
          type:
            - string
            - "null"
        last_event_id:
          type:
            - string
            - "null"
        created_at:
          type: string
          format: date-time
        started_at:
          type:
            - string
            - "null"
          format: date-time
        terminal_at:
          type:
            - string
            - "null"
          format: date-time
      required:
        - id
        - tenant_id
        - environment
        - conversation_id
        - workspace_id
        - actor
        - agent_revision_id
        - status
        - retry_of_run_id
        - last_event_id
        - created_at
        - started_at
        - terminal_at
      example:
        id: run_demo
        tenant_id: ten_demo
        environment: sandbox
        conversation_id: con_demo
        workspace_id: wrk_demo
        actor:
          type: user
          id: usr_demo
        agent_revision_id: rev_demo
        status: queued
        retry_of_run_id: null
        last_event_id: evt_1
        created_at: 2026-09-07T10:00:00Z
        started_at: null
        terminal_at: null
    Event:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        run_id:
          type: string
          minLength: 1
          maxLength: 128
        sequence:
          type: integer
          minimum: 1
        type:
          type: string
          enum:
            - run.queued
            - run.started
            - assistant.message
            - tool.started
            - tool.completed
            - run.requires_action
            - run.cancel_requested
            - run.completed
            - reconciliation.receipt
        created_at:
          type: string
          format: date-time
        data:
          type: object
          description: Event-specific payload; do not assume model-token granularity.
      required:
        - id
        - run_id
        - sequence
        - type
        - created_at
        - data
    Approval:
      type: object
      additionalProperties: true
      description: Read-authorized immutable proposal for human review. Render the
        exact destination and validated input as escaped data before allowing
        approve. Content remains in the tenant cell; hashes alone are
        insufficient for informed approval. Recheck actor, tool revision,
        connector generation and expiry immediately before dispatch.
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        tenant_id:
          type: string
          minLength: 1
          maxLength: 128
        environment:
          $ref: "#/components/schemas/EnvironmentName"
        run_id:
          type: string
          minLength: 1
          maxLength: 128
        operation_id:
          type: string
          minLength: 1
          maxLength: 128
        actor:
          $ref: "#/components/schemas/Actor"
        input_hash:
          type: string
          pattern: ^[a-f0-9]{64}$
        tool_revision_id:
          type: string
          minLength: 1
          maxLength: 128
        connector_generation:
          type: integer
          minimum: 1
        proposal:
          type: object
          additionalProperties: false
          properties:
            tool_id:
              $ref: "#/components/schemas/Id"
            display_name:
              type: string
              minLength: 1
              maxLength: 200
            destination:
              type: string
              format: uri
            input:
              type: object
              additionalProperties: true
          required:
            - tool_id
            - display_name
            - destination
            - input
        status:
          type: string
          enum:
            - pending
            - approved
            - denied
            - expired
            - revoked
        expires_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
      required:
        - id
        - tenant_id
        - environment
        - run_id
        - operation_id
        - actor
        - input_hash
        - tool_revision_id
        - connector_generation
        - proposal
        - status
        - expires_at
        - created_at
    ApprovalDecision:
      type: object
      additionalProperties: false
      properties:
        decision:
          type: string
          enum:
            - approve
            - deny
      required:
        - decision
    File:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        tenant_id:
          type: string
          minLength: 1
          maxLength: 128
        environment:
          $ref: "#/components/schemas/EnvironmentName"
        workspace_id:
          type: string
          minLength: 1
          maxLength: 128
        name:
          type: string
        content_type:
          type: string
          enum:
            - text/plain
            - application/json
        size_bytes:
          type: integer
          minimum: 0
          maximum: 10485760
        status:
          type: string
          enum:
            - quarantined
            - available
            - rejected
            - deleting
            - deleted
        created_at:
          type: string
          format: date-time
      required:
        - id
        - tenant_id
        - environment
        - workspace_id
        - name
        - content_type
        - size_bytes
        - status
        - created_at
    UploadFile:
      type: object
      additionalProperties: false
      properties:
        workspace_id:
          type: string
          minLength: 1
          maxLength: 128
        name:
          type: string
          minLength: 1
          maxLength: 255
        content_type:
          type: string
          enum:
            - text/plain
            - application/json
        content_base64:
          type: string
          contentEncoding: base64
          maxLength: 13981016
          description: Decoded content maximum 10 MiB. Strict base64 decoder required;
            scan before availability.
      required:
        - workspace_id
        - name
        - content_type
        - content_base64
      description: Strict canonical base64 text/json upload. Total HTTP request
        maximum14MiB and decoded file maximum10MiB; reject invalid base64, MIME
        mismatch and oversized content before scan. Bounded buffering has memory
        overhead; streaming upload is deferred.
    CreateWebhook:
      type: object
      additionalProperties: false
      properties:
        url:
          type: string
          format: uri
          pattern: ^https://
        event_types:
          type: array
          items:
            type: string
            enum:
              - run.completed
              - run.requires_action
          minItems: 1
          uniqueItems: true
      required:
        - url
        - event_types
    UpdateWebhook:
      type: object
      additionalProperties: false
      properties:
        url:
          type: string
          format: uri
          pattern: ^https://
        event_types:
          type: array
          items:
            type: string
            enum:
              - run.completed
              - run.requires_action
          minItems: 1
          uniqueItems: true
        enabled:
          type: boolean
      required: []
      minProperties: 1
    WebhookEndpoint:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        tenant_id:
          type: string
          minLength: 1
          maxLength: 128
        environment:
          $ref: "#/components/schemas/EnvironmentName"
        url:
          type: string
          format: uri
        event_types:
          type: array
          items:
            type: string
        enabled:
          type: boolean
        created_at:
          type: string
          format: date-time
      required:
        - id
        - tenant_id
        - environment
        - url
        - event_types
        - enabled
        - created_at
    WebhookSecret:
      type: object
      additionalProperties: false
      properties:
        endpoint:
          $ref: "#/components/schemas/WebhookEndpoint"
        secret_available:
          type: boolean
        secret:
          type: string
          x-sensitive: true
          description: One-time fresh response only. Never logged, cached, persisted in
            replay, or included in analytics.
        rotation:
          type: object
          additionalProperties: false
          properties:
            current_version:
              type: integer
              minimum: 2
            previous_version:
              type: integer
              minimum: 1
            previous_retire_at:
              type: string
              format: date-time
          required:
            - current_version
            - previous_version
            - previous_retire_at
          description: Returned on rotation only, including metadata-only replay of the
            original rotation.
      required:
        - endpoint
        - secret_available
    WebhookDelivery:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        endpoint_id:
          type: string
          minLength: 1
          maxLength: 128
        event_id:
          type: string
          minLength: 1
          maxLength: 128
        run_id:
          type: string
          minLength: 1
          maxLength: 128
        status:
          type: string
          enum:
            - pending
            - delivered
            - failed
        attempts:
          type: integer
          minimum: 0
        next_attempt_at:
          type:
            - string
            - "null"
          format: date-time
        created_at:
          type: string
          format: date-time
      required:
        - id
        - endpoint_id
        - event_id
        - run_id
        - status
        - attempts
        - next_attempt_at
        - created_at
    WebhookEvent:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        run_id:
          type: string
          minLength: 1
          maxLength: 128
        type:
          type: string
          enum:
            - run.completed
            - run.requires_action
        status:
          $ref: "#/components/schemas/RunStatus"
        created_at:
          type: string
          format: date-time
      required:
        - id
        - run_id
        - type
        - status
        - created_at
      example:
        id: evt_9
        run_id: run_demo
        type: run.completed
        status: succeeded
        created_at: 2026-09-07T10:00:00Z
    UsageRecord:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        tenant_id:
          type: string
          minLength: 1
          maxLength: 128
        environment:
          $ref: "#/components/schemas/EnvironmentName"
        run_id:
          type:
            - string
            - "null"
        operation_id:
          type:
            - string
            - "null"
        kind:
          type: string
          enum:
            - measured
            - adjustment
        quantity:
          type: string
          pattern: ^-?[0-9]+(\.[0-9]+)?$
        unit:
          type: string
          enum:
            - input_tokens
            - output_tokens
            - runtime_seconds
            - storage_bytes
            - tool_calls
        measured_cost_usd:
          type: string
          pattern: ^-?[0-9]+(\.[0-9]{1,6})?$
        rated_charge_usd:
          type:
            - string
            - "null"
          pattern: ^-?[0-9]+(\.[0-9]{1,6})?$
          description: Null until customer rating is known; never represent an unknown
            price as zero.
        adjustment_of:
          type:
            - string
            - "null"
        created_at:
          type: string
          format: date-time
        rating_status:
          type: string
          enum:
            - unrated
            - rated
      required:
        - id
        - tenant_id
        - environment
        - run_id
        - operation_id
        - kind
        - quantity
        - unit
        - measured_cost_usd
        - rated_charge_usd
        - adjustment_of
        - created_at
        - rating_status
      allOf:
        - if:
            properties:
              rating_status:
                const: unrated
          then:
            properties:
              rated_charge_usd:
                type: "null"
          else:
            properties:
              rated_charge_usd:
                type: string
    Usage:
      type: object
      additionalProperties: true
      properties:
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
        measured_cost_usd:
          $ref: "#/components/schemas/Money"
        rated_charge_usd:
          type:
            - string
            - "null"
          pattern: ^-?[0-9]+(\.[0-9]{1,6})?$
          description: Null until customer rating is known; never represent an unknown
            price as zero.
        reserved_cost_usd:
          $ref: "#/components/schemas/Money"
        input_tokens:
          type: integer
          minimum: 0
        output_tokens:
          type: integer
          minimum: 0
        runtime_seconds:
          type: number
          minimum: 0
        storage_bytes:
          type: integer
          minimum: 0
        provisional:
          type: boolean
        rating_status:
          type: string
          enum:
            - unrated
            - rated
      required:
        - from
        - to
        - measured_cost_usd
        - rated_charge_usd
        - reserved_cost_usd
        - input_tokens
        - output_tokens
        - runtime_seconds
        - storage_bytes
        - provisional
        - rating_status
      allOf:
        - if:
            properties:
              rating_status:
                const: unrated
          then:
            properties:
              rated_charge_usd:
                type: "null"
          else:
            properties:
              rated_charge_usd:
                type: string
    Quotas:
      type: object
      additionalProperties: true
      properties:
        monthly_budget_usd:
          $ref: "#/components/schemas/Money"
        per_run_budget_usd:
          $ref: "#/components/schemas/Money"
        running_per_workspace:
          type: integer
          const: 1
        running_per_cell:
          type: integer
          const: 2
        queued_per_cell:
          type: integer
          const: 100
        storage_bytes:
          type: integer
          maximum: 1073741824
        queue_deadline_seconds:
          type: integer
          const: 300
      required:
        - monthly_budget_usd
        - per_run_budget_usd
        - running_per_workspace
        - running_per_cell
        - queued_per_cell
        - storage_bytes
        - queue_deadline_seconds
    UpdateQuotas:
      type: object
      additionalProperties: false
      properties:
        monthly_budget_usd:
          $ref: "#/components/schemas/Money"
        per_run_budget_usd:
          $ref: "#/components/schemas/Money"
      required: []
      minProperties: 1
      description: Within operator-approved ceilings only; protective budget is not a
        quoted price.
    Settings:
      type: object
      additionalProperties: true
      properties:
        content_retention_days:
          type: integer
          enum:
            - 7
            - 30
            - 90
        audit_retention_days:
          type: integer
          const: 90
        billing_retention_months:
          type: integer
          const: 13
        backup_retention_days:
          type: integer
          const: 30
      required:
        - content_retention_days
        - audit_retention_days
        - billing_retention_months
        - backup_retention_days
    UpdateSettings:
      type: object
      additionalProperties: false
      properties:
        content_retention_days:
          type: integer
          enum:
            - 7
            - 30
            - 90
      required:
        - content_retention_days
    AuditEntry:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        actor_id:
          type: string
          minLength: 1
          maxLength: 128
        action:
          type: string
        resource_id:
          type: string
          minLength: 1
          maxLength: 128
        outcome:
          type: string
          enum:
            - allowed
            - denied
            - failed
        created_at:
          type: string
          format: date-time
      required:
        - id
        - actor_id
        - action
        - resource_id
        - outcome
        - created_at
    DeletionJob:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        tenant_id:
          type: string
          minLength: 1
          maxLength: 128
        environment:
          type:
            - string
            - "null"
          enum:
            - sandbox
            - production
            - null
          description: Null for a tenant-wide deletion spanning all environments.
        resource_type:
          type: string
        resource_id:
          type: string
          minLength: 1
          maxLength: 128
        status:
          type: string
          enum:
            - pending
            - purging
            - completed
            - failed
        live_purge_due_at:
          type: string
          format: date-time
        backup_expiry_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
      required:
        - id
        - tenant_id
        - environment
        - resource_type
        - resource_id
        - status
        - live_purge_due_at
        - backup_expiry_at
        - created_at
    ApiKey:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 128
        tenant_id:
          type: string
          minLength: 1
          maxLength: 128
        environment:
          $ref: "#/components/schemas/EnvironmentName"
        name:
          type: string
        public_id:
          type: string
          minLength: 1
          maxLength: 128
        prefix:
          type: string
        last4:
          type: string
          minLength: 4
          maxLength: 4
        scopes:
          type: array
          items:
            $ref: "#/components/schemas/Scope"
        actor:
          $ref: "#/components/schemas/Actor"
        creator_id:
          type: string
          minLength: 1
          maxLength: 128
        family_id:
          type: string
          minLength: 1
          maxLength: 128
        expires_at:
          type: string
          format: date-time
        last_used_at:
          type:
            - string
            - "null"
          format: date-time
        revoked_at:
          type:
            - string
            - "null"
          format: date-time
        retires_at:
          type:
            - string
            - "null"
          format: date-time
        created_at:
          type: string
          format: date-time
      required:
        - id
        - tenant_id
        - environment
        - name
        - public_id
        - prefix
        - last4
        - scopes
        - actor
        - creator_id
        - family_id
        - expires_at
        - last_used_at
        - revoked_at
        - retires_at
        - created_at
    ToolInvocation:
      type: object
      additionalProperties: false
      properties:
        operation_id:
          type: string
          minLength: 1
          maxLength: 128
        tool_id:
          type: string
          minLength: 1
          maxLength: 128
        tool_revision_id:
          type: string
          minLength: 1
          maxLength: 128
        run_id:
          type: string
          minLength: 1
          maxLength: 128
        tenant_id:
          type: string
          minLength: 1
          maxLength: 128
        environment:
          $ref: "#/components/schemas/EnvironmentName"
        actor:
          $ref: "#/components/schemas/Actor"
        input_hash:
          type: string
          pattern: ^[a-f0-9]{64}$
        input:
          type: object
      required:
        - operation_id
        - tool_id
        - tool_revision_id
        - run_id
        - tenant_id
        - environment
        - actor
        - input_hash
        - input
      example:
        operation_id: op_demo
        tool_id: tool_note
        tool_revision_id: tr_demo
        run_id: run_demo
        tenant_id: ten_demo
        environment: sandbox
        actor:
          type: user
          id: usr_demo
        input_hash: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
        input:
          ticket_id: T-104
          note: Follow up on the delayed shipment.
    ToolResult:
      type: object
      additionalProperties: false
      properties:
        operation_id:
          type: string
          minLength: 1
          maxLength: 128
        status:
          type: string
          enum:
            - succeeded
            - failed
            - pending
            - not_found
        output: {}
        error_code:
          type: string
      required:
        - operation_id
        - status
    ToolJwtClaims:
      type: object
      additionalProperties: false
      properties:
        iss:
          type: string
          format: uri
        aud:
          type: string
          format: uri
        sub:
          type: string
          minLength: 1
          maxLength: 128
        tenant_id:
          type: string
          minLength: 1
          maxLength: 128
        environment:
          $ref: "#/components/schemas/EnvironmentName"
        actor:
          $ref: "#/components/schemas/Actor"
        operation_id:
          type: string
          minLength: 1
          maxLength: 128
        input_hash:
          type: string
          pattern: ^[a-f0-9]{64}$
        cell_generation:
          type: integer
          minimum: 1
        iat:
          type: integer
        exp:
          type: integer
      required:
        - iss
        - aud
        - sub
        - tenant_id
        - environment
        - actor
        - operation_id
        - input_hash
        - cell_generation
        - iat
        - exp
    Jwks:
      type: object
      additionalProperties: false
      properties:
        keys:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              kid:
                type: string
                minLength: 1
                maxLength: 128
              kty:
                type: string
                enum:
                  - RSA
              use:
                type: string
                enum:
                  - sig
              alg:
                type: string
                enum:
                  - RS256
              n:
                type: string
              e:
                type: string
            required:
              - kid
              - kty
              - use
              - alg
              - n
              - e
      required:
        - keys
webhooks:
  runEvent:
    post:
      operationId: receiveMystroWebhook
      summary: Customer receives reference-only run webhook
      x-release-stage: proposed
      x-visibility: public
      security: []
      description: 'Customer-hosted endpoint, not Mystro ingress. Headers:
        X-Mystro-Timestamp unix seconds, X-Mystro-Event-Id, X-Mystro-Signature
        one or two comma-separated v1=hex digests (current first during a
        24-hour rotation overlap), computed as HMAC-SHA256(secret, timestamp +
        "." + eventid + "." + rawbody). Reject skew>5min, compare constant-time,
        dedupe eventID, acknowledge2xx after durable receipt.
        Atleastonce/unordered; retry24h. Fetch authorized content separately.'
      parameters:
        - name: X-Mystro-Timestamp
          in: header
          required: true
          schema:
            type: string
            pattern: ^[0-9]+$
        - name: X-Mystro-Event-Id
          in: header
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: X-Mystro-Signature
          in: header
          required: true
          schema:
            type: string
            pattern: ^v1=[a-f0-9]{64}(,\s*v1=[a-f0-9]{64})?$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookEvent"
            example:
              id: evt_9
              run_id: run_demo
              type: run.completed
              status: succeeded
              created_at: 2026-09-07T10:00:00Z
      responses:
        "204":
          description: Durably received
        "400":
          description: Invalid signature or payload
        "503":
          description: Retryable receiver failure
x-customer-tool-protocol:
  description: Customer routes configured in CreateConnection, not Mystro API
    routes. POST configured operation.path with ToolInvocation, Authorization
    Bearer ToolJwt. Customer checks JWT aud/iss/signature/expiry/digest/actor
    live permissions then transactionally deduplicates operation_id with
    business write. GET configured reconciliation_path substitutes operation_id
    and returns ToolResult. No redirect/private IP/DNS rebinding. Ambiguous
    writes reconcile only, never replay.
  invocation_schema:
    $ref: "#/components/schemas/ToolInvocation"
  result_schema:
    $ref: "#/components/schemas/ToolResult"
  jwt_claims_schema:
    $ref: "#/components/schemas/ToolJwtClaims"