components:
    schemas:
        CodexProfile:
          type: object
          additionalProperties: false
          properties:
            effort:
              type: string
              enum:
              - none
              - minimal
              - low
              - medium
              - high
              - xhigh
              - max
              - ultra
            summary:
              type: string
              enum:
              - auto
              - concise
              - detailed
              - none
            personality:
              type: string
              enum:
              - none
              - friendly
              - pragmatic
            service_tier:
              type: string
              minLength: 1
        Profile:
          type: object
          additionalProperties: false
          required:
          - id
          - name
          - description
          - harness
          - account_id
          - account_name
          - account_active
          - active
          - available
          - model
          - codex
          - instructions
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
              minLength: 1
              maxLength: 255
            description:
              type:
              - string
              - 'null'
              maxLength: 4096
            harness:
              type: string
              enum:
              - codex
            account_id:
              type: string
              format: uuid
            account_name:
              type: string
              minLength: 1
              maxLength: 255
            account_active:
              type: boolean
            active:
              type: boolean
            available:
              type: boolean
            model:
              type: string
              minLength: 1
              maxLength: 255
            codex:
              $ref: '#/components/schemas/CodexProfile'
            instructions:
              type: string
        Profiles:
          type: object
          additionalProperties: false
          required:
          - items
          - next_cursor
          - prev_cursor
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/Profile'
            next_cursor:
              type:
              - string
              - 'null'
            prev_cursor:
              type:
              - string
              - 'null'
        CreateProfile:
          type: object
          additionalProperties: false
          required:
          - name
          - account_id
          - model
          properties:
            name:
              type: string
              minLength: 1
              maxLength: 255
            account_id:
              type: string
              format: uuid
            description:
              type:
              - string
              - 'null'
              maxLength: 4096
            model:
              type: string
              minLength: 1
              maxLength: 255
            instructions:
              type: string
              maxLength: 65536
            codex:
              $ref: '#/components/schemas/CodexProfile'
            active:
              type: boolean
              default: true
        UpdateProfile:
          type: object
          additionalProperties: false
          required: []
          properties:
            account_id:
              type: string
              format: uuid
            description:
              type:
              - string
              - 'null'
              maxLength: 4096
            model:
              type: string
              minLength: 1
              maxLength: 255
            instructions:
              type: string
              maxLength: 65536
            codex:
              type:
              - object
              - 'null'
              additionalProperties: false
              properties:
                effort:
                  type:
                  - string
                  - 'null'
                  enum:
                  - none
                  - minimal
                  - low
                  - medium
                  - high
                  - xhigh
                  - max
                  - ultra
                  - null
                summary:
                  type:
                  - string
                  - 'null'
                  enum:
                  - auto
                  - concise
                  - detailed
                  - none
                  - null
                personality:
                  type:
                  - string
                  - 'null'
                  enum:
                  - none
                  - friendly
                  - pragmatic
                  - null
                service_tier:
                  type:
                  - string
                  - 'null'
                  minLength: 1
            active:
              type: boolean
          x-go-type: json.RawMessage
          minProperties: 1
        LLMAccount:
          type: object
          additionalProperties: false
          required:
          - id
          - name
          - harness
          - auth_mode
          - active
          - credential_store
          - profiles
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
              minLength: 1
              maxLength: 255
            harness:
              type: string
              enum:
              - codex
            auth_mode:
              type: string
              enum:
              - account
              - api_key
            active:
              type: boolean
            credential_store:
              type:
              - string
              - 'null'
            profiles:
              type: array
              items:
                type: string
        LLMAccountDetails:
          type: object
          additionalProperties: false
          required:
          - id
          - name
          - harness
          - auth_mode
          - active
          - credential_store
          - profiles
          - api_key_mask
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
              minLength: 1
              maxLength: 255
            harness:
              type: string
              enum:
              - codex
            auth_mode:
              type: string
              enum:
              - account
              - api_key
            active:
              type: boolean
            credential_store:
              type:
              - string
              - 'null'
            profiles:
              type: array
              items:
                type: string
            api_key_mask:
              type:
              - string
              - 'null'
        LLMAccounts:
          type: object
          additionalProperties: false
          required:
          - items
          - next_cursor
          - prev_cursor
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/LLMAccount'
            next_cursor:
              type:
              - string
              - 'null'
            prev_cursor:
              type:
              - string
              - 'null'
        AuthFile:
          type: object
          additionalProperties: true
          x-go-type: json.RawMessage
        CreateLLMAccount:
          type: object
          additionalProperties: false
          required:
          - name
          - harness
          - auth_mode
          properties:
            name:
              type: string
              minLength: 1
              maxLength: 255
            harness:
              type: string
              enum:
              - codex
            auth_mode:
              type: string
              enum:
              - account
              - api_key
            active:
              type: boolean
              default: true
            credential_store:
              type: string
              minLength: 1
            auth_file:
              $ref: '#/components/schemas/AuthFile'
            api_key:
              type: string
              minLength: 1
              writeOnly: true
          x-go-type: json.RawMessage
        UpdateLLMAccount:
          type: object
          additionalProperties: false
          required: []
          properties:
            name:
              type: string
              minLength: 1
              maxLength: 255
            active:
              type: boolean
          x-go-type: json.RawMessage
          minProperties: 1
        ReplaceAPIKey:
          type: object
          additionalProperties: false
          required:
          - api_key
          properties:
            api_key:
              type: string
              minLength: 1
              writeOnly: true
        CredentialStores:
          type: object
          additionalProperties: false
          required:
          - items
          properties:
            items:
              type: array
              items:
                type: string
        Template:
            type: object
            additionalProperties: false
            required: [id, name, template_name, tag, description, active]
            properties:
                id: {type: string, format: uuid}
                name: {type: string, description: Exact normalized reference including the optional tag.}
                template_name: {type: string}
                tag: {type: [string, 'null']}
                description: {type: [string, 'null']}
                active: {type: boolean}
        Templates:
            type: object
            additionalProperties: false
            required: [items, next_cursor, prev_cursor]
            properties:
                items:
                    type: array
                    items: {$ref: '#/components/schemas/Template'}
                next_cursor: {type: [string, 'null']}
                prev_cursor: {type: [string, 'null']}
        CreateTemplate:
            type: object
            additionalProperties: false
            required: [template_name]
            properties:
                template_name:
                    type: string
                    minLength: 1
                    maxLength: 255
                    pattern: '^[A-Za-z0-9_-]+(/[A-Za-z0-9_-]+)?$'
                    description: Own-project alias, optionally prefixed by its team slug. Normalized to lowercase.
                tag:
                    type: [string, 'null']
                    minLength: 1
                    maxLength: 128
                    pattern: '^[A-Za-z0-9_.-]+$'
                    description: Normalized to lowercase; UUID build references are rejected. Omission or null checks default but stores an untagged reference.
                description: {type: [string, 'null'], maxLength: 4096}
                active: {type: boolean, default: true}
        UpdateTemplate:
            type: object
            x-go-type: json.RawMessage
            additionalProperties: false
            minProperties: 1
            properties:
                description: {type: [string, 'null'], maxLength: 4096}
                active: {type: boolean}
        ServiceCodes:
            description: Unique configured service codes. Order is insignificant; an unknown code rejects the entire request.
            type: array
            uniqueItems: true
            items:
                type: string
                minLength: 1
                maxLength: 64
                pattern: '^[a-z][a-z0-9_-]*$'
        Service:
            type: object
            additionalProperties: false
            required: [code, name, description, env_from]
            properties:
                code: {type: string}
                name: {type: string}
                description: {type: string}
                env_from:
                    description: Sorted environment variable names; never their values.
                    type: array
                    items: {type: string}
        Services:
            type: object
            additionalProperties: false
            required: [items]
            properties:
                items:
                    type: array
                    items: {$ref: '#/components/schemas/Service'}
        AccountLimitWindow:
            type: object
            additionalProperties: false
            required: [used_percent, remaining_percent, window_minutes, resets_at]
            properties:
                used_percent: {type: number, format: double, minimum: 0}
                remaining_percent: {type: number, format: double, minimum: 0}
                window_minutes: {type: [integer, 'null'], minimum: 1}
                resets_at: {type: [string, 'null'], format: date-time}
        AccountLimitBucket:
            type: object
            additionalProperties: false
            required: [limit_id, limit_name, plan_type, rate_limit_reached_type, primary, secondary]
            properties:
                limit_id: {type: string}
                limit_name: {type: [string, 'null']}
                plan_type: {type: [string, 'null']}
                rate_limit_reached_type: {type: [string, 'null']}
                primary:
                    anyOf:
                        - {$ref: '#/components/schemas/AccountLimitWindow'}
                        - {type: 'null'}
                secondary:
                    anyOf:
                        - {$ref: '#/components/schemas/AccountLimitWindow'}
                        - {type: 'null'}
        AccountLimitItem:
            type: object
            additionalProperties: false
            required: [account_id, profiles, state, observed_at, last_attempt_at, error_code, buckets, reset_credits_available]
            properties:
                account_id: {type: string}
                profiles:
                    type: array
                    items: {type: string}
                state: {type: string, enum: [unknown, unavailable, stale, fresh]}
                observed_at: {type: [string, 'null'], format: date-time}
                last_attempt_at: {type: [string, 'null'], format: date-time}
                error_code:
                    anyOf:
                        - type: string
                          enum: [unsupported, temporarily_unavailable, invalid_response, no_data, authentication_unavailable]
                          x-enum-varnames: [AccountLimitItemErrorCodeUnsupported, AccountLimitItemErrorCodeTemporarilyUnavailable, AccountLimitItemErrorCodeInvalidResponse, AccountLimitItemErrorCodeNoData, AccountLimitItemErrorCodeAuthenticationUnavailable]
                        - type: 'null'
                buckets:
                    type: array
                    items: {$ref: '#/components/schemas/AccountLimitBucket'}
                reset_credits_available:
                    description: Available earned rate-limit resets for the account; null when unknown. Uses the same observation time and freshness state as the quota windows.
                    anyOf:
                        - type: integer
                          format: int64
                          minimum: 0
                        - type: 'null'
        AccountLimits:
            type: object
            additionalProperties: false
            required: [as_of, stale_after_seconds, items]
            properties:
                as_of: {type: string, format: date-time}
                stale_after_seconds: {type: integer, minimum: 1}
                items:
                    type: array
                    items: {$ref: '#/components/schemas/AccountLimitItem'}
        StatusCounts:
            type: object
            additionalProperties: false
            required: [accepted, starting, running, cancelling, finalizing, completed, failed, cancelled]
            properties:
                accepted: {type: integer, format: int64, minimum: 0, maximum: 9007199254740991}
                starting: {type: integer, format: int64, minimum: 0, maximum: 9007199254740991}
                running: {type: integer, format: int64, minimum: 0, maximum: 9007199254740991}
                cancelling: {type: integer, format: int64, minimum: 0, maximum: 9007199254740991}
                finalizing: {type: integer, format: int64, minimum: 0, maximum: 9007199254740991}
                completed: {type: integer, format: int64, minimum: 0, maximum: 9007199254740991}
                failed: {type: integer, format: int64, minimum: 0, maximum: 9007199254740991}
                cancelled: {type: integer, format: int64, minimum: 0, maximum: 9007199254740991}
        AggregateUsage:
            type: object
            additionalProperties: false
            required: [input_tokens, cached_input_tokens, output_tokens, reasoning_output_tokens, total_tokens]
            description: Totals for runs accepted in the period. Cached input and reasoning output are included in input and output respectively. The breakdown is recorded only since collection began; historical usage is not reconstructed. Decimal strings preserve values beyond JavaScript Number precision.
            properties:
                input_tokens: {type: string, pattern: '^(0|[1-9][0-9]*)$'}
                cached_input_tokens: {type: string, pattern: '^(0|[1-9][0-9]*)$'}
                output_tokens: {type: string, pattern: '^(0|[1-9][0-9]*)$'}
                reasoning_output_tokens: {type: string, pattern: '^(0|[1-9][0-9]*)$'}
                total_tokens: {type: string, pattern: '^(0|[1-9][0-9]*)$'}
        AnalyticsBucket:
            type: object
            additionalProperties: false
            required: [from, to, runs_count, by_status]
            properties:
                from: {type: string, format: date-time}
                to: {type: string, format: date-time}
                runs_count: {type: integer, format: int64, minimum: 0, maximum: 9007199254740991}
                by_status: {$ref: '#/components/schemas/StatusCounts'}
        AnalyticsOverview:
            type: object
            additionalProperties: false
            required: [as_of, from, to, bucket, timezone, namespace, current, period, series, namespaces]
            properties:
                as_of: {type: string, format: date-time}
                from: {type: string, format: date-time}
                to: {type: string, format: date-time}
                bucket: {type: string, enum: [hour, day]}
                timezone: {type: string}
                namespace: {type: [string, 'null']}
                current:
                    type: object
                    additionalProperties: false
                    required: [active_sessions]
                    properties:
                        active_sessions: {type: integer, format: int64, minimum: 0, maximum: 9007199254740991}
                period:
                    type: object
                    additionalProperties: false
                    required: [runs_count, by_status, usage, runtime_seconds]
                    description: Runs accepted during [from,to), including their latest recorded usage and full lifetime through as_of.
                    properties:
                        runs_count: {type: integer, format: int64, minimum: 0, maximum: 9007199254740991}
                        by_status: {$ref: '#/components/schemas/StatusCounts'}
                        usage: {$ref: '#/components/schemas/AggregateUsage'}
                        runtime_seconds: {type: number, format: double, minimum: 0}
                series:
                    type: array
                    items: {$ref: '#/components/schemas/AnalyticsBucket'}
                namespaces:
                    type: array
                    description: The period's runs grouped by session namespace, most runs first; null is the group of sessions without a namespace. The groups add up to period.
                    items: {$ref: '#/components/schemas/AnalyticsNamespace'}
        AnalyticsNamespace:
            type: object
            additionalProperties: false
            required: [namespace, runs_count, by_status, usage, runtime_seconds]
            description: Runs accepted during [from,to) whose session has this namespace, with the same definitions as period.
            properties:
                namespace: {type: [string, 'null']}
                runs_count: {type: integer, format: int64, minimum: 0, maximum: 9007199254740991}
                by_status: {$ref: '#/components/schemas/StatusCounts'}
                usage: {$ref: '#/components/schemas/AggregateUsage'}
                runtime_seconds: {type: number, format: double, minimum: 0}
        BrowserAuthSession:
            type: object
            additionalProperties: false
            required: [mode, authenticated, read_access, user, expires_at]
            properties:
                mode:
                    type: string
                    enum: [api_only, saml, anonymous]
                authenticated:
                    type: boolean
                read_access:
                    type: boolean
                user:
                    type: [object, "null"]
                    additionalProperties: false
                    required: [display_name]
                    properties:
                        display_name:
                            type: string
                expires_at:
                    type: [string, "null"]
                    format: date-time
        RunStatus:
            type: string
            enum: [accepted, starting, running, cancelling, finalizing, completed, failed, cancelled]
        Accepted:
            properties:
                message_id:
                    description: ID of the last accepted message in the ordered batch.
                    format: uuid
                    title: Message Id
                    type: string
                run_id:
                    format: uuid
                    title: Run Id
                    type: string
                session_id:
                    format: uuid
                    title: Session Id
                    type: string
            required:
                - session_id
                - run_id
                - message_id
            title: Accepted
            type: object
        AgentConfiguration:
            additionalProperties: false
            properties:
                instructions:
                    title: Instructions
                    type: string
                model:
                    title: Model
                    type: string
                profile:
                    title: Profile
                    type: string
            required:
                - profile
                - model
                - instructions
            title: AgentConfiguration
            type: object
        AgentInput:
            additionalProperties: false
            properties:
                instructions:
                    default: ""
                    title: Instructions
                    type: string
                model:
                    minLength: 1
                    title: Model
                    type: string
                profile:
                    minLength: 1
                    title: Profile
                    type: string
            required:
                - profile
            title: AgentInput
            type: object
        Cancelled:
            properties:
                run_id:
                    format: uuid
                    title: Run Id
                    type: string
                status:
                    $ref: '#/components/schemas/RunStatus'
            required:
                - run_id
                - status
            title: Cancelled
            type: object
        Configuration:
            additionalProperties: false
            properties:
                agent:
                    $ref: '#/components/schemas/AgentConfiguration'
                hooks:
                    $ref: '#/components/schemas/HooksConfiguration'
                limits:
                    $ref: '#/components/schemas/Limits'
                sandbox:
                    $ref: '#/components/schemas/SandboxConfiguration'
            required:
                - agent
                - sandbox
                - limits
                - hooks
            title: Configuration
            type: object
        ConfigurationInput:
            additionalProperties: false
            properties:
                agent:
                    $ref: '#/components/schemas/AgentInput'
                hooks:
                    $ref: '#/components/schemas/HooksInput'
                limits:
                    $ref: '#/components/schemas/LimitsInput'
                sandbox:
                    $ref: '#/components/schemas/SandboxInput'
            required:
                - agent
                - sandbox
            title: ConfigurationInput
            type: object
        CreateSession:
            additionalProperties: false
            properties:
                allow_multiple_runs:
                    description: Immutable session policy. If false, only the run created with the session is allowed and its sandbox is deleted after completion, failure or cancellation. If true, the sandbox is paused for subsequent runs until its retention period expires. Recovery and messages within the current run are allowed in either mode.
                    type: boolean
                    default: false
                namespace:
                    description: Logical integration or workflow name. Opaque identifier, 1–128 UTF-8 bytes; no NUL or whitespace-only value. Compared exactly, without normalization.
                    type: string
                    minLength: 1
                    maxLength: 128
                external_key:
                    description: Source-qualified external object key; not unique across sessions. Opaque identifier, 1–512 UTF-8 bytes; no NUL or whitespace-only value. Compared exactly, without normalization.
                    type: string
                    minLength: 1
                    maxLength: 512
                input_fingerprint:
                    description: Opaque input snapshot version for the first run; does not deduplicate requests. Opaque identifier, 1–256 UTF-8 bytes; no NUL or whitespace-only value. Compared exactly, without normalization.
                    type: string
                    minLength: 1
                    maxLength: 256
                configuration:
                    $ref: '#/components/schemas/ConfigurationInput'
                messages:
                    description: Ordered user messages accepted atomically. The last starts the run; earlier messages are injected into the agent context first.
                    type: array
                    minItems: 1
                    maxItems: 256
                    items:
                        $ref: '#/components/schemas/TextMessage'
                env:
                    description: Explicit environment variables for the first run's before_run and after_run hooks only. Override session sources with the same names; never passed to the harness, after_create, or before_remove.
                    type: object
                    additionalProperties:
                        type: string
                services:
                    description: Services available only to this run's before_run and after_run hooks, as with run env_from. Never passed to the harness, after_create, or before_remove.
                    $ref: '#/components/schemas/ServiceCodes'
                env_from:
                    description: Allowlisted orchestrator environment variable names for the first run's before_run and after_run hooks only. Resolved before each hook; override session sources and are never passed to the harness, after_create, or before_remove.
                    type: array
                    items:
                        type: string
            required:
                - configuration
                - messages
            title: CreateSession
            type: object
        Error:
            properties:
                code:
                    title: Code
                    type: string
                diagnostic_id:
                    description: Identifier of the internal diagnostic log for this error, when available. It does not grant access to logs.
                    anyOf:
                        - type: string
                          format: uuid
                        - type: "null"
                details:
                    items:
                        $ref: '#/components/schemas/ErrorDetail'
                    title: Details
                    type: array
                message:
                    description: Human-readable error message. Harness execution failures include the original harness message and additional details when available; otherwise a generic message is returned.
                    title: Message
                    type: string
                phase:
                    anyOf:
                        - enum:
                            - preparation
                            - execution
                            - finalization
                            - recovery
                          type: string
                        - type: "null"
                    title: Phase
            required:
                - code
                - message
                - phase
                - details
            title: Error
            type: object
        ErrorDetail:
            description: Validation paths start with body, header, query, or path. Hook execution errors identify configuration.hooks.<name>; codes never contain input values or native validator messages.
            properties:
                code:
                    enum: [required, invalid_type, invalid_value, unknown_field, template_not_found, template_inactive, template_forbidden, tag_not_found, profile_not_found, profile_inactive, account_inactive]
                    title: Code
                    type: string
                path:
                    items:
                        anyOf:
                            - type: string
                            - type: integer
                    title: Path
                    type: array
            required:
                - path
                - code
            title: ErrorDetail
            type: object
        ErrorResponse:
            properties:
                error:
                    $ref: '#/components/schemas/Error'
            required:
                - error
            title: ErrorResponse
            type: object
        Event:
            discriminator:
                mapping:
                    message.updated: '#/components/schemas/MessageEvent'
                    run.updated: '#/components/schemas/RunEvent'
                    sandbox.updated: '#/components/schemas/SandboxEvent'
                    tool_call.updated: '#/components/schemas/ToolCallEvent'
                propertyName: type
            oneOf:
                - $ref: '#/components/schemas/RunEvent'
                - $ref: '#/components/schemas/MessageEvent'
                - $ref: '#/components/schemas/ToolCallEvent'
                - $ref: '#/components/schemas/SandboxEvent'
        EventPage:
            properties:
                has_more:
                    title: Has More
                    type: boolean
                items:
                    items:
                        $ref: '#/components/schemas/Event'
                    title: Items
                    type: array
                next_cursor:
                    title: Next Cursor
                    type: string
            required:
                - items
                - next_cursor
                - has_more
            title: EventPage
            type: object
        HooksConfiguration:
            additionalProperties: false
            properties:
                after_create:
                    type: string
                before_run:
                    type: string
                after_run:
                    type: string
                before_remove:
                    type: string
                timeout_seconds:
                    type: integer
                    minimum: 1
                    maximum: 2147483647
            required:
                - timeout_seconds
            type: object
        HooksInput:
            additionalProperties: false
            properties:
                after_create:
                    description: Executable script text with a shebang; runs once after workspace creation.
                    type: string
                before_run:
                    description: Executable script text with a shebang; runs before every assignment.
                    type: string
                after_run:
                    description: Executable script text with a shebang; runs after confirmed agent completion, before sandbox pause or deletion.
                    type: string
                before_remove:
                    description: Reserved for future use; never called, including before automatic sandbox deletion.
                    type: string
                timeout_seconds:
                    description: Timeout for each hook invocation.
                    type: integer
                    default: 300
                    minimum: 1
                    maximum: 2147483647
            type: object
        HookResult:
            properties:
                id:
                    type: string
                    format: uuid
                name:
                    type: string
                    enum: [after_create, before_run, after_run, before_remove]
                status:
                    type: string
                    enum: [pending, running, completed, failed, cancelled, skipped]
                started_at:
                    anyOf:
                        - type: string
                          format: date-time
                        - type: 'null'
                deadline_at:
                    anyOf:
                        - type: string
                          format: date-time
                        - type: 'null'
                finished_at:
                    anyOf:
                        - type: string
                          format: date-time
                        - type: 'null'
                exit_code:
                    anyOf:
                        - type: integer
                        - type: 'null'
                signal:
                    anyOf:
                        - type: integer
                        - type: 'null'
                output:
                    anyOf:
                        - $ref: '#/components/schemas/TextResult'
                        - $ref: '#/components/schemas/TruncatedResult'
                        - type: 'null'
                output_completeness:
                    type: string
                    enum: [complete, truncated, unavailable, unknown]
                truncation_reason:
                    anyOf:
                        - type: string
                          enum: [orpheus_limit]
                        - type: 'null'
                error:
                    anyOf:
                        - $ref: '#/components/schemas/Error'
                        - type: 'null'
            required: [id, name, status, started_at, deadline_at, finished_at, exit_code, signal, output, output_completeness, truncation_reason, error]
            type: object
        HistoryPage:
            properties:
                event_cursor:
                    title: Event Cursor
                    type: string
                items:
                    items:
                        discriminator:
                            mapping:
                                message: '#/components/schemas/MessageItem'
                                tool_call: '#/components/schemas/ToolItem'
                            propertyName: type
                        oneOf:
                            - $ref: '#/components/schemas/MessageItem'
                            - $ref: '#/components/schemas/ToolItem'
                    title: Items
                    type: array
                next_cursor:
                    anyOf:
                        - type: string
                        - type: "null"
                    title: Next Cursor
            required:
                - items
                - next_cursor
                - event_cursor
            title: HistoryPage
            type: object
        JSONResult:
            properties:
                original_bytes:
                    anyOf:
                        - type: integer
                        - type: "null"
                    title: Original Bytes
                type:
                    const: json
                    default: json
                    title: Type
                    type: string
                value:
                    title: Value
                    x-go-type: json.RawMessage
            required:
                - value
                - original_bytes
                - type
            title: JSONResult
            type: object
        LimitsInput:
            additionalProperties: false
            properties:
                max_session_tokens:
                    description: Session-wide input and output token budget. Omission uses DEFAULT_MAX_SESSION_TOKENS (100000000 by default); explicit null is invalid.
                    type: integer
                    format: int64
                    minimum: 1
                    maximum: 9223372036854775807
                run_timeout_seconds:
                    description: Agent execution deadline, independent of the periodically renewed sandbox timeout. AgentBox plan limits on uninterrupted sandbox lifetime still apply.
                    default: 3600
                    exclusiveMinimum: 0
                    maximum: 2.147483647e+09
                    title: Run Timeout Seconds
                    type: integer
            title: LimitsInput
            type: object
        Limits:
            additionalProperties: false
            properties:
                max_session_tokens:
                    description: Session-wide input and output token budget. Omission uses DEFAULT_MAX_SESSION_TOKENS (100000000 by default); explicit null is invalid.
                    type: integer
                    format: int64
                    minimum: 1
                    maximum: 9223372036854775807
                run_timeout_seconds:
                    description: Agent execution deadline, independent of the periodically renewed sandbox timeout. AgentBox plan limits on uninterrupted sandbox lifetime still apply.
                    default: 3600
                    exclusiveMinimum: 0
                    maximum: 2.147483647e+09
                    title: Run Timeout Seconds
                    type: integer
            required: [run_timeout_seconds, max_session_tokens]
            title: Limits
            type: object
        Usage:
            type: object
            description: Last reported token consumption; missed reports are not reconstructed from history. Cached input and reasoning output are included in input and output respectively. The breakdown is recorded only since collection began; historical usage is not reconstructed.
            required: [input_tokens, cached_input_tokens, output_tokens, reasoning_output_tokens, total_tokens]
            properties:
                input_tokens:
                    type: integer
                    format: int64
                    minimum: 0
                cached_input_tokens:
                    type: integer
                    format: int64
                    minimum: 0
                output_tokens:
                    type: integer
                    format: int64
                    minimum: 0
                reasoning_output_tokens:
                    type: integer
                    format: int64
                    minimum: 0
                total_tokens:
                    type: integer
                    format: int64
                    minimum: 0
        Message:
            properties:
                external_key:
                    description: External key supplied for an incoming message; null for agent messages. Opaque identifier, 1–512 UTF-8 bytes; no NUL or whitespace-only value. Compared exactly, without normalization.
                    anyOf:
                        - type: string
                        - type: "null"
                metadata:
                    description: Opaque integration data for an incoming message; never sent to the agent. Null for messages without metadata and agent messages.
                    x-go-type: json.RawMessage
                    anyOf:
                        - type: object
                          additionalProperties: true
                        - type: "null"
                created_at:
                    format: date-time
                    title: Created At
                    type: string
                delivery_status:
                    anyOf:
                        - enum:
                            - pending
                            - sending
                            - delivered
                            - uncertain
                            - rejected
                          type: string
                        - type: "null"
                    title: Delivery Status
                error:
                    anyOf:
                        - $ref: '#/components/schemas/Error'
                        - type: "null"
                id:
                    format: uuid
                    title: Id
                    type: string
                kind:
                    anyOf:
                        - enum:
                            - progress
                            - answer
                          type: string
                        - type: "null"
                    title: Kind
                position:
                    anyOf:
                        - $ref: '#/components/schemas/Position'
                        - type: "null"
                registered_sequence:
                    title: Registered Sequence
                    type: string
                role:
                    enum:
                        - user
                        - assistant
                    title: Role
                    type: string
                run_id:
                    format: uuid
                    title: Run Id
                    type: string
                session_id:
                    format: uuid
                    title: Session Id
                    type: string
                text:
                    title: Text
                    type: string
            required:
                - external_key
                - metadata
                - id
                - session_id
                - run_id
                - role
                - kind
                - text
                - delivery_status
                - error
                - registered_sequence
                - position
                - created_at
            title: Message
            type: object
        MessageEvent:
            properties:
                created_at:
                    format: date-time
                    title: Created At
                    type: string
                data:
                    $ref: '#/components/schemas/Message'
                id:
                    title: Id
                    type: string
                session_id:
                    format: uuid
                    title: Session Id
                    type: string
                type:
                    enum:
                        - message.updated
                    type: string
            required:
                - id
                - session_id
                - type
                - created_at
                - data
            type: object
        MessageItem:
            properties:
                message:
                    $ref: '#/components/schemas/Message'
                type:
                    const: message
                    default: message
                    title: Type
                    type: string
            required:
                - message
                - type
            title: MessageItem
            type: object
        RunPage:
            properties:
                items:
                    items:
                        $ref: '#/components/schemas/Run'
                    title: Items
                    type: array
                next_cursor:
                    anyOf:
                        - type: string
                        - type: "null"
                    title: Next Cursor
            required:
                - items
                - next_cursor
            title: RunPage
            type: object
        SessionPage:
            properties:
                items:
                    items:
                        $ref: '#/components/schemas/Session'
                    title: Items
                    type: array
                next_cursor:
                    anyOf:
                        - type: string
                        - type: "null"
                    title: Next Cursor
            required:
                - items
                - next_cursor
            title: SessionPage
            type: object
        Position:
            properties:
                item_index:
                    title: Item Index
                    type: integer
                run_number:
                    title: Run Number
                    type: integer
            required:
                - run_number
                - item_index
            title: Position
            type: object
        Run:
            properties:
                usage:
                    $ref: '#/components/schemas/Usage'
                phase:
                    anyOf:
                        - type: string
                          enum: [preparation, after_create, before_run, agent, after_run]
                        - type: 'null'
                agent_status:
                    anyOf:
                        - type: string
                          enum: [completed, failed, cancelled]
                        - type: 'null'
                agent_error:
                    anyOf:
                        - $ref: '#/components/schemas/Error'
                        - type: 'null'
                hooks:
                    type: array
                    items:
                        $ref: '#/components/schemas/HookResult'
                env_names:
                    description: Sorted names of explicit variables supplied for this run; values are never returned.
                    type: array
                    items:
                        type: string
                services:
                    description: Immutable service descriptions and environment names resolved when accepted.
                    type: array
                    items: {$ref: '#/components/schemas/Service'}
                env_from:
                    description: Sorted orchestrator environment variable names for this run, including expanded services.
                    type: array
                    items:
                        type: string
                input_fingerprint:
                    description: Input snapshot version supplied when the run was accepted. Opaque identifier, 1–256 UTF-8 bytes; no NUL or whitespace-only value. Compared exactly, without normalization.
                    anyOf:
                        - type: string
                        - type: "null"
                cancel_requested_at:
                    anyOf:
                        - format: date-time
                          type: string
                        - type: "null"
                    title: Cancel Requested At
                created_at:
                    format: date-time
                    title: Created At
                    type: string
                deadline_at:
                    anyOf:
                        - format: date-time
                          type: string
                        - type: "null"
                    title: Deadline At
                error:
                    anyOf:
                        - $ref: '#/components/schemas/Error'
                        - type: "null"
                execution_started_at:
                    anyOf:
                        - format: date-time
                          type: string
                        - type: "null"
                    title: Execution Started At
                final_message:
                    anyOf:
                        - $ref: '#/components/schemas/Message'
                        - type: "null"
                finished_at:
                    anyOf:
                        - format: date-time
                          type: string
                        - type: "null"
                    title: Finished At
                id:
                    format: uuid
                    title: Id
                    type: string
                number:
                    title: Number
                    type: integer
                observation:
                    anyOf:
                        - enum:
                            - attached
                            - reconnecting
                            - uncertain
                          type: string
                        - type: "null"
                    title: Observation
                session_id:
                    format: uuid
                    title: Session Id
                    type: string
                status:
                    $ref: '#/components/schemas/RunStatus'
                stop_method:
                    description: How cancellation stopped agent execution. Null until confirmed, or if the run was cancelled before the first dispatch attempt, including user-requested cancellation.
                    anyOf:
                        - enum:
                            - graceful
                            - forced
                          type: string
                        - type: "null"
                    title: Stop Method
                stop_reason:
                    anyOf:
                        - enum:
                            - user_request
                            - run_timeout
                            - token_limit
                          type: string
                        - type: "null"
                    title: Stop Reason
            required:
                - usage
                - phase
                - agent_status
                - agent_error
                - hooks
                - input_fingerprint
                - env_names
                - env_from
                - services
                - id
                - session_id
                - number
                - status
                - observation
                - created_at
                - execution_started_at
                - deadline_at
                - finished_at
                - cancel_requested_at
                - stop_reason
                - stop_method
                - final_message
                - error
            title: Run
            type: object
        RunEvent:
            properties:
                created_at:
                    format: date-time
                    title: Created At
                    type: string
                data:
                    $ref: '#/components/schemas/Run'
                id:
                    title: Id
                    type: string
                session_id:
                    format: uuid
                    title: Session Id
                    type: string
                type:
                    enum:
                        - run.updated
                    type: string
            required:
                - id
                - session_id
                - type
                - created_at
                - data
            type: object
        SandboxConfiguration:
            additionalProperties: false
            properties:
                services:
                    description: Immutable service descriptions and environment names resolved when accepted.
                    type: array
                    items: {$ref: '#/components/schemas/Service'}
                env_from:
                    description: Sorted orchestrator environment variable names, including expanded services.
                    items:
                        type: string
                    title: Env From
                    type: array
                env_names:
                    items:
                        type: string
                    title: Env Names
                    type: array
                template:
                    title: Template
                    type: string
            required:
                - template
                - env_names
                - env_from
                - services
            title: SandboxConfiguration
            type: object
        SandboxEvent:
            properties:
                created_at:
                    format: date-time
                    title: Created At
                    type: string
                data:
                    $ref: '#/components/schemas/SandboxState'
                id:
                    title: Id
                    type: string
                session_id:
                    format: uuid
                    title: Session Id
                    type: string
                type:
                    enum:
                        - sandbox.updated
                    type: string
            required:
                - id
                - session_id
                - type
                - created_at
                - data
            type: object
        SandboxInput:
            additionalProperties: false
            properties:
                env:
                    additionalProperties:
                        type: string
                    title: Env
                    type: object
                services:
                    description: Services available to the agent and session hooks, expanded together with env_from.
                    $ref: '#/components/schemas/ServiceCodes'
                env_from:
                    items:
                        type: string
                    title: Env From
                    type: array
                template:
                    description: Exact active catalog name, including any team slug and tag. Missing or inactive records return 422 unknown_template with detail code template_not_found or template_inactive. Accepted sessions and idempotent replays keep their stored name regardless of subsequent catalog changes.
                    minLength: 1
                    title: Template
                    type: string
            required:
                - template
            title: SandboxInput
            type: object
        SandboxState:
            properties:
                error:
                    anyOf:
                        - $ref: '#/components/schemas/Error'
                        - type: "null"
                id:
                    anyOf:
                        - type: string
                        - type: "null"
                    description: AgentBox sandbox ID, if known. Retained for diagnostics after deletion or loss; does not guarantee accessibility.
                last_known_state:
                    anyOf:
                        - type: string
                        - type: "null"
                    title: Last Known State
                state:
                    enum:
                        - not_created
                        - provisioning
                        - ready
                        - pausing
                        - paused
                        - resuming
                        - deleting
                        - deleted
                        - unavailable
                    title: State
                    type: string
                workspace:
                    anyOf:
                        - type: string
                        - type: "null"
                    description: Absolute workspace path resolved during sandbox preparation, if known.
            required:
                - state
                - last_known_state
                - error
                - id
                - workspace
            title: SandboxState
            type: object
        CreateRun:
            additionalProperties: false
            properties:
                input_fingerprint:
                    description: Opaque input snapshot version for this run; does not deduplicate requests. Opaque identifier, 1–256 UTF-8 bytes; no NUL or whitespace-only value. Compared exactly, without normalization.
                    type: string
                    minLength: 1
                    maxLength: 256
                messages:
                    description: Ordered user messages accepted atomically. The last starts the run; earlier messages are injected into the agent context first.
                    type: array
                    minItems: 1
                    maxItems: 256
                    items:
                        $ref: '#/components/schemas/TextMessage'
                env:
                    description: Explicit environment variables available only to this run's before_run and after_run hooks. Override session sources with the same names; never passed to the harness, after_create, or before_remove.
                    type: object
                    additionalProperties:
                        type: string
                services:
                    description: Services available only to this run's before_run and after_run hooks, as with run env_from. Never passed to the harness, after_create, or before_remove.
                    $ref: '#/components/schemas/ServiceCodes'
                env_from:
                    description: Allowlisted orchestrator environment variable names available only to this run's before_run and after_run hooks. Resolved before each hook; override session sources and are never passed to the harness, after_create, or before_remove.
                    type: array
                    items:
                        type: string
            required:
                - messages
            title: CreateRun
            type: object
        SendMessage:
            additionalProperties: false
            properties:
                messages:
                    description: Ordered user messages accepted atomically for the active run.
                    type: array
                    minItems: 1
                    maxItems: 256
                    items:
                        $ref: '#/components/schemas/TextMessage'
            required:
                - messages
            title: SendMessage
            type: object
        Session:
            properties:
                allow_multiple_runs:
                    description: Immutable policy allowing subsequent runs. False means the sandbox is deleted after the first run terminates; session history remains available.
                    type: boolean
                last_run_created_at:
                    description: Creation time of the latest run, not the last activity time.
                    format: date-time
                    type: string
                usage:
                    $ref: '#/components/schemas/Usage'
                phase:
                    anyOf:
                        - type: string
                          enum: [preparation, after_create, before_run, agent, after_run]
                        - type: 'null'
                namespace:
                    description: Logical integration or workflow name. Opaque identifier, 1–128 UTF-8 bytes; no NUL or whitespace-only value. Compared exactly, without normalization.
                    anyOf:
                        - type: string
                        - type: "null"
                external_key:
                    description: Source-qualified external object key; not unique across sessions. Opaque identifier, 1–512 UTF-8 bytes; no NUL or whitespace-only value. Compared exactly, without normalization.
                    anyOf:
                        - type: string
                        - type: "null"
                active_run_id:
                    anyOf:
                        - format: uuid
                          type: string
                        - type: "null"
                    title: Active Run Id
                configuration:
                    $ref: '#/components/schemas/Configuration'
                created_at:
                    format: date-time
                    title: Created At
                    type: string
                error:
                    anyOf:
                        - $ref: '#/components/schemas/Error'
                        - type: "null"
                final_message:
                    anyOf:
                        - $ref: '#/components/schemas/Message'
                        - type: "null"
                id:
                    format: uuid
                    title: Id
                    type: string
                last_run_id:
                    format: uuid
                    title: Last Run Id
                    type: string
                sandbox:
                    $ref: '#/components/schemas/SandboxState'
                status:
                    $ref: '#/components/schemas/RunStatus'
            required:
                - allow_multiple_runs
                - usage
                - phase
                - namespace
                - external_key
                - id
                - created_at
                - last_run_created_at
                - configuration
                - sandbox
                - active_run_id
                - last_run_id
                - status
                - final_message
                - error
            title: Session
            type: object
        TextMessage:
            additionalProperties: false
            properties:
                external_key:
                    description: External message or event key; not unique and not sent to the harness. Opaque identifier, 1–512 UTF-8 bytes; no NUL or whitespace-only value. Compared exactly, without normalization.
                    type: string
                    minLength: 1
                    maxLength: 512
                text:
                    minLength: 1
                    title: Text
                    type: string
                metadata:
                    description: Opaque integration data retained with the message, never sent to the agent. If present, must be a JSON object.
                    type: object
                    additionalProperties: true
                    x-go-type: json.RawMessage
            required:
                - text
            title: TextMessage
            type: object
        TextResult:
            properties:
                exit_code:
                    anyOf:
                        - type: integer
                        - type: "null"
                    title: Exit Code
                original_bytes:
                    anyOf:
                        - type: integer
                        - type: "null"
                    title: Original Bytes
                text:
                    title: Text
                    type: string
                type:
                    const: text
                    default: text
                    title: Type
                    type: string
            required:
                - text
                - original_bytes
                - type
            title: TextResult
            type: object
        ToolCall:
            properties:
                created_at:
                    format: date-time
                    title: Created At
                    type: string
                id:
                    format: uuid
                    title: Id
                    type: string
                input:
                    title: Input
                    x-go-type: json.RawMessage
                name:
                    title: Name
                    type: string
                output_completeness:
                    enum:
                        - complete
                        - truncated
                        - unavailable
                        - unknown
                    title: Output Completeness
                    type: string
                position:
                    anyOf:
                        - $ref: '#/components/schemas/Position'
                        - type: "null"
                registered_sequence:
                    title: Registered Sequence
                    type: string
                result:
                    anyOf:
                        - $ref: '#/components/schemas/ToolResult'
                        - type: "null"
                    title: Result
                run_id:
                    format: uuid
                    title: Run Id
                    type: string
                session_id:
                    format: uuid
                    title: Session Id
                    type: string
                status:
                    enum:
                        - running
                        - completed
                        - failed
                        - cancelled
                        - unknown
                    title: Status
                    type: string
                truncation_reason:
                    anyOf:
                        - enum:
                            - orpheus_limit
                            - harness_limit
                          type: string
                        - type: "null"
                    title: Truncation Reason
            required:
                - id
                - session_id
                - run_id
                - name
                - input
                - status
                - result
                - output_completeness
                - truncation_reason
                - registered_sequence
                - position
                - created_at
            title: ToolCall
            type: object
        ToolResult:
            discriminator:
                mapping:
                    json: '#/components/schemas/JSONResult'
                    text: '#/components/schemas/TextResult'
                    truncated_text: '#/components/schemas/TruncatedResult'
                propertyName: type
            oneOf:
                - $ref: '#/components/schemas/TextResult'
                - $ref: '#/components/schemas/JSONResult'
                - $ref: '#/components/schemas/TruncatedResult'
        ToolCallEvent:
            properties:
                created_at:
                    format: date-time
                    title: Created At
                    type: string
                data:
                    $ref: '#/components/schemas/ToolCall'
                id:
                    title: Id
                    type: string
                session_id:
                    format: uuid
                    title: Session Id
                    type: string
                type:
                    enum:
                        - tool_call.updated
                    type: string
            required:
                - id
                - session_id
                - type
                - created_at
                - data
            type: object
        ToolItem:
            properties:
                tool_call:
                    $ref: '#/components/schemas/ToolCall'
                type:
                    const: tool_call
                    default: tool_call
                    title: Type
                    type: string
            required:
                - tool_call
                - type
            title: ToolItem
            type: object
        TruncatedResult:
            properties:
                exit_code:
                    anyOf:
                        - type: integer
                        - type: "null"
                    title: Exit Code
                head:
                    title: Head
                    type: string
                original_bytes:
                    anyOf:
                        - type: integer
                        - type: "null"
                    title: Original Bytes
                source_type:
                    default: text
                    enum:
                        - text
                        - json
                    title: Source Type
                    type: string
                tail:
                    title: Tail
                    type: string
                type:
                    const: truncated_text
                    default: truncated_text
                    title: Type
                    type: string
            required:
                - head
                - tail
                - original_bytes
                - type
            title: TruncatedResult
            type: object
    securitySchemes:
        BrowserSession:
            type: apiKey
            in: cookie
            name: __Host-orpheus_session
            description: Read-only browser session issued after SAML login. Anonymous read access is a deployment option, not a production security scheme.
        HTTPBearer:
            scheme: bearer
            type: http
info:
    description: Durable agent sessions in AgentBox sandboxes.
    license:
        identifier: AGPL-3.0-only
        name: GNU Affero General Public License v3.0 only
    title: Orpheus
    version: 0.1.0
openapi: 3.1.0
paths:
    /api/v1/profiles:
      get:
        operationId: get_profiles
        summary: List profiles
        responses:
          '200':
            description: List profiles
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Profiles'
          default:
            description: Invalid input (422), unauthorized (401), forbidden origin (403), missing record (404),
              conflict (409), or unavailable storage (503).
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ErrorResponse'
        security:
        - HTTPBearer: []
        - BrowserSession: []
        parameters:
        - in: query
          name: active
          schema:
            type: boolean
        - in: query
          name: name
          description: Exact case-sensitive name. Incompatible with name_contains.
          schema:
            type: string
            minLength: 1
        - in: query
          name: name_contains
          description: Literal case-insensitive substring. Incompatible with name.
          schema:
            type: string
            minLength: 1
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - in: query
          name: cursor
          schema:
            type: string
            minLength: 1
            maxLength: 8192
        - in: query
          name: available
          schema:
            type: boolean
          description: Profile and account activity combined.
        description: Database catalog ordered by (name, id), with filters bound to forward/backward cursors.
          Changes apply to new sessions; accepted sessions retain their account and execution snapshot.
      post:
        operationId: create_profile
        summary: Create profile
        responses:
          '201':
            description: Create profile
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Profile'
          default:
            description: Invalid input (422), unauthorized (401), forbidden origin (403), missing record (404),
              conflict (409), or unavailable storage (503).
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ErrorResponse'
        security:
        - HTTPBearer: []
        - BrowserSession: []
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateProfile'
    /api/v1/profiles/{id}:
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      get:
        operationId: get_profile
        summary: Read profile
        responses:
          '200':
            description: Read profile
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Profile'
          default:
            description: Invalid input (422), unauthorized (401), forbidden origin (403), missing record (404),
              conflict (409), or unavailable storage (503).
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ErrorResponse'
        security:
        - HTTPBearer: []
        - BrowserSession: []
      patch:
        operationId: update_profile
        summary: Update profile
        responses:
          '200':
            description: Update profile
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Profile'
          default:
            description: Invalid input (422), unauthorized (401), forbidden origin (403), missing record (404),
              conflict (409), or unavailable storage (503).
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ErrorResponse'
        security:
        - HTTPBearer: []
        - BrowserSession: []
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateProfile'
      delete:
        operationId: delete_profile
        summary: Delete profile
        responses:
          '204':
            description: Delete profile
          default:
            description: Invalid input (422), unauthorized (401), forbidden origin (403), missing record (404),
              conflict (409), or unavailable storage (503).
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ErrorResponse'
        security:
        - HTTPBearer: []
        - BrowserSession: []
    /api/v1/llm-accounts:
      get:
        operationId: get_llm_accounts
        summary: List llm-accounts
        responses:
          '200':
            description: List llm-accounts
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/LLMAccounts'
          default:
            description: Invalid input (422), unauthorized (401), forbidden origin (403), missing record (404),
              conflict (409), or unavailable storage (503).
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ErrorResponse'
        security:
        - HTTPBearer: []
        - BrowserSession: []
        parameters:
        - in: query
          name: active
          schema:
            type: boolean
        - in: query
          name: name
          description: Exact case-sensitive name. Incompatible with name_contains.
          schema:
            type: string
            minLength: 1
        - in: query
          name: name_contains
          description: Literal case-insensitive substring. Incompatible with name.
          schema:
            type: string
            minLength: 1
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - in: query
          name: cursor
          schema:
            type: string
            minLength: 1
            maxLength: 8192
        description: Database catalog ordered by (name, id), with filters bound to forward/backward cursors.
          Changes apply to new sessions; accepted sessions retain their account and execution snapshot.
      post:
        operationId: create_llm_account
        summary: Create llm account
        responses:
          '201':
            description: Create llm account
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/LLMAccountDetails'
          default:
            description: Invalid input (422), unauthorized (401), forbidden origin (403), missing record (404),
              conflict (409), or unavailable storage (503).
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ErrorResponse'
        security:
        - HTTPBearer: []
        - BrowserSession: []
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateLLMAccount'
    /api/v1/llm-accounts/{id}:
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      get:
        operationId: get_llm_account
        summary: Read llm account
        responses:
          '200':
            description: Read llm account
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/LLMAccountDetails'
          default:
            description: Invalid input (422), unauthorized (401), forbidden origin (403), missing record (404),
              conflict (409), or unavailable storage (503).
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ErrorResponse'
        security:
        - HTTPBearer: []
        - BrowserSession: []
      patch:
        operationId: update_llm_account
        summary: Update llm account
        responses:
          '200':
            description: Update llm account
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/LLMAccountDetails'
          default:
            description: Invalid input (422), unauthorized (401), forbidden origin (403), missing record (404),
              conflict (409), or unavailable storage (503).
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ErrorResponse'
        security:
        - HTTPBearer: []
        - BrowserSession: []
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateLLMAccount'
      delete:
        operationId: delete_llm_account
        summary: Delete llm account
        responses:
          '204':
            description: Delete llm account
          default:
            description: Invalid input (422), unauthorized (401), forbidden origin (403), missing record (404),
              conflict (409), or unavailable storage (503).
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ErrorResponse'
        security:
        - HTTPBearer: []
        - BrowserSession: []
    /api/v1/credential-stores:
      get:
        operationId: get_credential_stores
        summary: List configured credential store names
        responses:
          '200':
            description: List configured credential store names
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/CredentialStores'
          default:
            description: Invalid input (422), unauthorized (401), forbidden origin (403), missing record (404),
              conflict (409), or unavailable storage (503).
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ErrorResponse'
        security:
        - HTTPBearer: []
        - BrowserSession: []
    /api/v1/llm-accounts/{id}/api-key:
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      put:
        operationId: replace_api_key
        summary: Replace an account API key
        responses:
          '204':
            description: Replace an account API key
          default:
            description: Invalid input (422), unauthorized (401), forbidden origin (403), missing record (404),
              conflict (409), or unavailable storage (503).
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ErrorResponse'
        security:
        - HTTPBearer: []
        - BrowserSession: []
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReplaceAPIKey'
    /api/v1/llm-accounts/{id}/auth-file:
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      get:
        operationId: get_auth_file
        summary: Read the account authorization file
        responses:
          '200':
            description: Read the account authorization file
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/AuthFile'
            headers:
              ETag:
                required: true
                schema:
                  type: string
              Cache-Control:
                required: true
                schema:
                  type: string
                  const: no-store
          default:
            description: Invalid input (422), unauthorized (401), forbidden origin (403), missing record (404),
              conflict (409), or unavailable storage (503).
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ErrorResponse'
        security:
        - HTTPBearer: []
        - BrowserSession: []
      put:
        operationId: replace_auth_file
        summary: Conditionally replace the account authorization file
        responses:
          '204':
            description: Conditionally replace the account authorization file
            headers:
              ETag:
                required: true
                schema:
                  type: string
          default:
            description: Invalid input (422), unauthorized (401), forbidden origin (403), missing record (404),
              conflict (409), or unavailable storage (503).
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ErrorResponse'
        security:
        - HTTPBearer: []
        - BrowserSession: []
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthFile'
        parameters:
        - in: header
          name: If-Match
          required: true
          schema:
            type: string
            minLength: 1
    /api/v1/templates:
        get:
            operationId: get_templates
            summary: List registered templates
            description: Database catalog ordered by (name, id). Filters are bound to opaque forward/backward cursors; no provider calls. New sessions require an exact active name from this catalog. Changes do not affect accepted sessions or idempotent replays.
            parameters:
                - in: query
                  name: active
                  schema: {type: boolean}
                - in: query
                  name: name
                  description: Exact case-sensitive reference. Incompatible with name_contains.
                  schema: {type: string, minLength: 1}
                - in: query
                  name: name_contains
                  description: Literal case-insensitive substring of the reference. Incompatible with name.
                  schema: {type: string, minLength: 1}
                - in: query
                  name: limit
                  schema: {type: integer, minimum: 1, maximum: 200, default: 50}
                - in: query
                  name: cursor
                  schema: {type: string, minLength: 1, maxLength: 8192}
            responses:
                '200':
                    description: One page; cursor fields are null at the respective boundaries.
                    content:
                        application/json:
                            schema: {$ref: '#/components/schemas/Templates'}
                default:
                    description: Invalid input (422), unauthorized (401), forbidden browser origin (403), missing record (404), duplicate (409), or unavailable provider/storage (503).
                    content:
                        application/json:
                            schema: {$ref: '#/components/schemas/ErrorResponse'}
            security:
                - HTTPBearer: []
                - BrowserSession: []
        post:
            operationId: create_template
            summary: Register an own-project AgentBox template
            description: Requires successful alias and tag lookups. Browser writes require the configured Origin and X-Orpheus-CSRF header set to 1. Active records become available to new sessions immediately, without restarting API or worker.
            requestBody:
                required: true
                content:
                    application/json:
                        schema: {$ref: '#/components/schemas/CreateTemplate'}
            responses:
                '201':
                    description: Registered template
                    content:
                        application/json:
                            schema: {$ref: '#/components/schemas/Template'}
                default:
                    description: Invalid input (422), unauthorized (401), forbidden browser origin (403), missing record (404), duplicate (409), or unavailable provider/storage (503).
                    content:
                        application/json:
                            schema: {$ref: '#/components/schemas/ErrorResponse'}
            security:
                - HTTPBearer: []
                - BrowserSession: []
    /api/v1/templates/{id}:
        parameters:
            - in: path
              name: id
              required: true
              schema: {type: string, format: uuid}
        get:
            operationId: get_template
            summary: Read a registered template
            responses:
                '200':
                    description: Registered template, including inactive records
                    content:
                        application/json:
                            schema: {$ref: '#/components/schemas/Template'}
                default:
                    description: Invalid input (422), unauthorized (401), forbidden browser origin (403), missing record (404), duplicate (409), or unavailable provider/storage (503).
                    content:
                        application/json:
                            schema: {$ref: '#/components/schemas/ErrorResponse'}
            security:
                - HTTPBearer: []
                - BrowserSession: []
        patch:
            operationId: update_template
            summary: Update template activity or description
            description: Name and tag are immutable. Empty or whitespace-only descriptions become null. No AgentBox lookup. Browser writes require Origin and X-Orpheus-CSRF.
            requestBody:
                required: true
                content:
                    application/json:
                        schema: {$ref: '#/components/schemas/UpdateTemplate'}
            responses:
                '200':
                    description: Updated template
                    content:
                        application/json:
                            schema: {$ref: '#/components/schemas/Template'}
                default:
                    description: Invalid input (422), unauthorized (401), forbidden browser origin (403), missing record (404), duplicate (409), or unavailable provider/storage (503).
                    content:
                        application/json:
                            schema: {$ref: '#/components/schemas/ErrorResponse'}
            security:
                - HTTPBearer: []
                - BrowserSession: []
        delete:
            operationId: delete_template
            summary: Delete an Orpheus catalog record
            description: Does not modify AgentBox or accepted sessions. Browser writes require Origin and X-Orpheus-CSRF.
            responses:
                '204':
                    description: Deleted
                default:
                    description: Invalid input (422), unauthorized (401), forbidden browser origin (403), missing record (404), duplicate (409), or unavailable provider/storage (503).
                    content:
                        application/json:
                            schema: {$ref: '#/components/schemas/ErrorResponse'}
            security:
                - HTTPBearer: []
                - BrowserSession: []
    /api/v1/services:
        get:
            operationId: get_services
            summary: List configured services
            description: Returns the complete catalog sorted by code from local configuration. No provider or credential lookups are performed.
            responses:
                '200':
                    description: Configured services
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Services'
                '401':
                    description: Unauthorized
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                '503':
                    description: Authentication temporarily unavailable
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
            security:
                - HTTPBearer: []
                - BrowserSession: []
    /api/v1/accounts/limits:
      get:
        operationId: get_account_limits
        summary: Current provider limits by account
        description: Read-only snapshot from worker observations. Does not contact the provider or refresh
          credentials. Responses use Cache-Control no-store.
        responses:
          '200':
            description: Account limits snapshot
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/AccountLimits'
          '401':
            description: Unauthorized
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ErrorResponse'
          '503':
            description: Account limits unavailable
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ErrorResponse'
          default:
            description: Invalid input (422), unauthorized (401), forbidden origin (403), missing record (404),
              conflict (409), or unavailable storage (503).
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ErrorResponse'
        security:
        - HTTPBearer: []
        - BrowserSession: []
        parameters:
        - in: query
          name: account_ids
          style: form
          explode: false
          schema:
            type: array
            minItems: 1
            maxItems: 200
            uniqueItems: true
            items:
              type: string
              format: uuid
          description: Comma-separated account UUIDs. Omit to read all account-file identities.
    /api/v1/analytics/overview:
        get:
            operationId: get_analytics_overview
            summary: Dashboard analytics snapshot
            description: Counts and usage of runs accepted during [from,to), the same totals per namespace, plus current active sessions. All timestamps are UTC.
            parameters:
                - in: query
                  name: window
                  description: Server-relative sliding window. Defaults to 24h; cannot be combined with from/to.
                  schema: {type: string, enum: [24h, 7d, 30d]}
                - in: query
                  name: from
                  description: Inclusive RFC 3339 timestamp with offset; requires to.
                  schema: {type: string, format: date-time}
                - in: query
                  name: to
                  description: Exclusive RFC 3339 timestamp with offset; requires from and cannot be later than as_of. Range at most 31 days.
                  schema: {type: string, format: date-time}
                - in: query
                  name: bucket
                  description: Local calendar hour or day; at most 800 buckets.
                  schema: {type: string, enum: [hour, day], default: hour}
                - in: query
                  name: timezone
                  description: IANA timezone for bucket boundaries; timestamps in the response are UTC.
                  schema: {type: string, default: UTC}
                - in: query
                  name: namespace
                  description: Exact namespace match; omission includes every namespace and null.
                  schema: {type: string, minLength: 1, maxLength: 128}
            responses:
                '200':
                    description: Analytics snapshot
                    content:
                        application/json:
                            schema: {$ref: '#/components/schemas/AnalyticsOverview'}
                '401':
                    description: Unauthorized
                    content:
                        application/json:
                            schema: {$ref: '#/components/schemas/ErrorResponse'}
                '422':
                    description: Invalid query
                    content:
                        application/json:
                            schema: {$ref: '#/components/schemas/ErrorResponse'}
                '503':
                    description: Analytics unavailable or overflow
                    content:
                        application/json:
                            schema: {$ref: '#/components/schemas/ErrorResponse'}
            security:
                - HTTPBearer: []
                - BrowserSession: []
    /api/v1/auth/session:
        get:
            operationId: auth_session
            summary: Read browser authentication state
            security: []
            description: Public browser state; Authorization is ignored. Invalid cookies are cleared. All responses use Cache-Control no-store.
            responses:
                "200":
                    description: Read browser authentication state
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BrowserAuthSession'
                default:
                    description: Storage unavailable (503).
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
    /auth/login:
        get:
            operationId: browser_login
            summary: Start SP-initiated SAML login
            security: []
            description: SAML mode only; otherwise 404 auth_not_enabled. next must be a local absolute path (not auth routes); default /api/v1/auth/session. No Host or proxy header trust.
            parameters:
                - in: query
                  name: next
                  schema:
                      type: string
                      maxLength: 2048
            responses:
                "302":
                    description: Start SP-initiated SAML login
                    headers:
                        Location:
                            schema:
                                type: string
                            description: SAML IdP URL.
                default:
                    description: Invalid return path (400), authentication disabled (404), request validation failed (422), or authentication/storage unavailable (503).
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
    /auth/callback:
        post:
            operationId: browser_callback
            summary: Consume a signed SAML HTTP-POST response
            security: []
            description: SAML mode only. Body is application/x-www-form-urlencoded with exactly one SAMLResponse and RelayState, at most 1 MiB. One-time request and browser nonce are required. Unsolicited responses are rejected.
            responses:
                "303":
                    description: Consume a signed SAML HTTP-POST response
                    headers:
                        Location:
                            schema:
                                type: string
                            description: Validated local return path.
                default:
                    description: Invalid login state (400), invalid SAML response (401), authentication disabled (404), oversized form (413), or authentication/storage unavailable (503).
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
    /auth/logout:
        post:
            operationId: browser_logout
            summary: Revoke the local browser session
            security: []
            description: Requires the configured Origin and X-Orpheus-CSRF header equal to 1. Idempotent; clears the cookie. Does not terminate the IdP session.
            responses:
                "204":
                    description: Revoke the local browser session
                default:
                    description: Invalid origin or CSRF header (403), or storage unavailable (503).
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
    /saml/metadata:
        get:
            operationId: saml_metadata
            summary: Read service provider metadata
            security: []
            responses:
                "200":
                    description: Read service provider metadata
                    content:
                        application/samlmetadata+xml:
                            schema:
                                type: string
                default:
                    description: Authentication disabled (404), or metadata unavailable (503).
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
    /api/v1/runs:
        get:
            description: List All Runs
            operationId: list_all_runs
            parameters:
                - in: query
                  name: namespace
                  required: false
                  schema:
                    type: string
                    minLength: 1
                    maxLength: 128
                    description: Exact match; 1–128 UTF-8 bytes, no NUL or whitespace-only value.
                - in: query
                  name: external_key
                  required: false
                  schema:
                    type: string
                    minLength: 1
                    maxLength: 512
                    description: Exact match; 1–512 UTF-8 bytes, no NUL or whitespace-only value.
                - in: query
                  name: input_fingerprint
                  required: false
                  schema:
                    type: string
                    minLength: 1
                    maxLength: 256
                    description: Exact match; 1–256 UTF-8 bytes, no NUL or whitespace-only value.
                - in: query
                  name: status
                  required: false
                  schema:
                    $ref: '#/components/schemas/RunStatus'
                - in: query
                  name: order
                  required: false
                  schema:
                    type: string
                    enum: [asc, desc]
                    default: asc
                - in: query
                  name: limit
                  required: false
                  schema:
                    default: 50
                    maximum: 200
                    minimum: 1
                    title: Limit
                    type: integer
                - in: query
                  name: cursor
                  required: false
                  schema:
                    anyOf:
                        - type: string
                        - type: "null"
                    title: Cursor
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/RunPage'
                    description: Successful Response
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Bad Request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Not Found
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Conflict
                "413":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Content Too Large
                "415":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unsupported Media Type
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unprocessable Content
                "503":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Service Unavailable
            security:
                - HTTPBearer: []
                - BrowserSession: []
            summary: List All Runs
    /api/v1/sessions:
        get:
            description: List Sessions
            operationId: list_sessions
            parameters:
                - in: query
                  name: activity
                  description: Whether the latest run is unfinished; combined with status using AND.
                  schema: {type: string, enum: [all, active, inactive], default: all}
                - in: query
                  name: sort
                  description: Timestamp used for order and cursor position.
                  schema: {type: string, enum: [created_at, last_run_created_at], default: created_at}
                - in: query
                  name: last_run_created_from
                  description: Inclusive lower bound for the latest run creation time; requires last_run_created_to.
                  schema: {type: string, format: date-time}
                - in: query
                  name: last_run_created_to
                  description: Exclusive upper bound for the latest run creation time; requires last_run_created_from. Range at most 31 days.
                  schema: {type: string, format: date-time}
                - in: query
                  name: namespace
                  required: false
                  schema:
                    type: string
                    minLength: 1
                    maxLength: 128
                    description: Exact match; 1–128 UTF-8 bytes, no NUL or whitespace-only value.
                - in: query
                  name: external_key
                  required: false
                  schema:
                    type: string
                    minLength: 1
                    maxLength: 512
                    description: Exact match; 1–512 UTF-8 bytes, no NUL or whitespace-only value.
                - in: query
                  name: status
                  required: false
                  schema:
                    $ref: '#/components/schemas/RunStatus'
                - in: query
                  name: order
                  required: false
                  schema:
                    type: string
                    enum: [asc, desc]
                    default: asc
                - in: query
                  name: limit
                  required: false
                  schema:
                    default: 50
                    maximum: 200
                    minimum: 1
                    title: Limit
                    type: integer
                - in: query
                  name: cursor
                  required: false
                  schema:
                    anyOf:
                        - type: string
                        - type: "null"
                    title: Cursor
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SessionPage'
                    description: Successful Response
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Bad Request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Not Found
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Conflict
                "413":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Content Too Large
                "415":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unsupported Media Type
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unprocessable Content
                "503":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Service Unavailable
            security:
                - HTTPBearer: []
                - BrowserSession: []
            summary: List Sessions
        post:
            description: Create Session
            operationId: create_session
            parameters:
                - in: header
                  name: Idempotency-Key
                  required: false
                  schema:
                    anyOf:
                        - type: string
                        - type: "null"
                    title: Idempotency-Key
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateSession'
                required: true
            responses:
                "202":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Accepted'
                    description: Successful Response
                    headers:
                        Location:
                            description: URL of the accepted run.
                            required: true
                            schema:
                                type: string
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Bad Request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "403":
                    description: Browser sessions allow reading only (read_only_access).
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Not Found
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Conflict
                "413":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Content Too Large
                "415":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unsupported Media Type
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unprocessable Content
                "503":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Service Unavailable
            security:
                - HTTPBearer: []
            summary: Create Session
    /api/v1/sessions/{sid}:
        get:
            description: Read Session
            operationId: get_session
            parameters:
                - in: path
                  name: sid
                  required: true
                  schema:
                    format: uuid
                    title: Sid
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Session'
                    description: Successful Response
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Bad Request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Not Found
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Conflict
                "413":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Content Too Large
                "415":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unsupported Media Type
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unprocessable Content
                "503":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Service Unavailable
            security:
                - HTTPBearer: []
                - BrowserSession: []
            summary: Read Session
    /api/v1/sessions/{sid}/events:
        get:
            description: Events
            operationId: get_events
            parameters:
                - in: path
                  name: sid
                  required: true
                  schema:
                    format: uuid
                    title: Sid
                    type: string
                - in: query
                  name: after
                  required: false
                  schema:
                    default: "0"
                    title: After
                    type: string
                - in: query
                  name: limit
                  required: false
                  schema:
                    default: 50
                    maximum: 200
                    minimum: 1
                    title: Limit
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/EventPage'
                    description: Successful Response
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Bad Request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Not Found
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Conflict
                "413":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Content Too Large
                "415":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unsupported Media Type
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unprocessable Content
                "503":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Service Unavailable
            security:
                - HTTPBearer: []
                - BrowserSession: []
            summary: Events
    /api/v1/sessions/{sid}/events/stream:
        get:
            description: Stream Events
            operationId: stream_events
            parameters:
                - in: path
                  name: sid
                  required: true
                  schema:
                    format: uuid
                    title: Sid
                    type: string
                - in: query
                  name: after
                  required: false
                  schema:
                    default: "0"
                    title: After
                    type: string
                - in: header
                  name: last-event-id
                  required: false
                  schema:
                    anyOf:
                        - type: string
                        - type: "null"
                    title: Last-Event-Id
            responses:
                "200":
                    content:
                        text/event-stream:
                            schema:
                                type: string
                    description: Successful Response
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Bad Request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Not Found
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Conflict
                "413":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Content Too Large
                "415":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unsupported Media Type
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unprocessable Content
                "503":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Service Unavailable
            security:
                - HTTPBearer: []
                - BrowserSession: []
            summary: Stream Events
    /api/v1/sessions/{sid}/history:
        get:
            description: History
            operationId: get_history
            parameters:
                - in: query
                  name: message_external_key
                  required: false
                  schema:
                    type: string
                    minLength: 1
                    maxLength: 512
                    description: Exact match; 1–512 UTF-8 bytes, no NUL or whitespace-only value.
                - in: path
                  name: sid
                  required: true
                  schema:
                    format: uuid
                    title: Sid
                    type: string
                - in: query
                  name: limit
                  required: false
                  schema:
                    default: 50
                    maximum: 200
                    minimum: 1
                    title: Limit
                    type: integer
                - in: query
                  name: cursor
                  required: false
                  schema:
                    anyOf:
                        - type: string
                        - type: "null"
                    title: Cursor
                - in: query
                  name: run_id
                  required: false
                  schema:
                    anyOf:
                        - format: uuid
                          type: string
                        - type: "null"
                    title: Run Id
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/HistoryPage'
                    description: Successful Response
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Bad Request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Not Found
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Conflict
                "413":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Content Too Large
                "415":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unsupported Media Type
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unprocessable Content
                "503":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Service Unavailable
            security:
                - HTTPBearer: []
                - BrowserSession: []
            summary: History
    /api/v1/sessions/{sid}/runs:
        get:
            description: List Runs
            operationId: list_runs
            parameters:
                - in: query
                  name: input_fingerprint
                  required: false
                  schema:
                    type: string
                    minLength: 1
                    maxLength: 256
                    description: Exact match; 1–256 UTF-8 bytes, no NUL or whitespace-only value.
                - in: query
                  name: status
                  required: false
                  schema:
                    $ref: '#/components/schemas/RunStatus'
                - in: query
                  name: order
                  required: false
                  schema:
                    type: string
                    enum: [asc, desc]
                    default: asc
                - in: path
                  name: sid
                  required: true
                  schema:
                    format: uuid
                    title: Sid
                    type: string
                - in: query
                  name: limit
                  required: false
                  schema:
                    default: 50
                    maximum: 200
                    minimum: 1
                    title: Limit
                    type: integer
                - in: query
                  name: cursor
                  required: false
                  schema:
                    anyOf:
                        - type: string
                        - type: "null"
                    title: Cursor
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/RunPage'
                    description: Successful Response
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Bad Request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Not Found
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Conflict
                "413":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Content Too Large
                "415":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unsupported Media Type
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unprocessable Content
                "503":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Service Unavailable
            security:
                - HTTPBearer: []
                - BrowserSession: []
            summary: List Runs
        post:
            description: >-
                Create a subsequent run. Sessions created with allow_multiple_runs=false
                reject this operation with 409 multiple_runs_not_allowed. Deleting,
                deleted or unavailable environments reject new input with 409
                session_unavailable; create a new session with the required context.
                If external sandbox loss is discovered after acceptance, the run fails
                asynchronously with sandbox_lost. Idempotent replay of an accepted
                request returns the original acceptance, regardless of sandbox state.
            operationId: create_run
            parameters:
                - in: path
                  name: sid
                  required: true
                  schema:
                    format: uuid
                    title: Sid
                    type: string
                - in: header
                  name: Idempotency-Key
                  required: false
                  schema:
                    anyOf:
                        - type: string
                        - type: "null"
                    title: Idempotency-Key
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateRun'
                required: true
            responses:
                "202":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Accepted'
                    description: Successful Response
                    headers:
                        Location:
                            description: URL of the accepted run.
                            required: true
                            schema:
                                type: string
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Bad Request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "403":
                    description: Browser sessions allow reading only (read_only_access).
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Not Found
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Conflict
                "413":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Content Too Large
                "415":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unsupported Media Type
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unprocessable Content
                "503":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Service Unavailable
            security:
                - HTTPBearer: []
            summary: Create Run
    /api/v1/sessions/{sid}/runs/{rid}:
        get:
            description: Read Run
            operationId: get_run
            parameters:
                - in: path
                  name: sid
                  required: true
                  schema:
                    format: uuid
                    title: Sid
                    type: string
                - in: path
                  name: rid
                  required: true
                  schema:
                    format: uuid
                    title: Rid
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Run'
                    description: Successful Response
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Bad Request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Not Found
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Conflict
                "413":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Content Too Large
                "415":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unsupported Media Type
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unprocessable Content
                "503":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Service Unavailable
            security:
                - HTTPBearer: []
                - BrowserSession: []
            summary: Read Run
    /api/v1/sessions/{sid}/runs/{rid}/cancel:
        post:
            description: Cancel Run
            operationId: cancel_run
            parameters:
                - in: path
                  name: sid
                  required: true
                  schema:
                    format: uuid
                    title: Sid
                    type: string
                - in: path
                  name: rid
                  required: true
                  schema:
                    format: uuid
                    title: Rid
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Cancelled'
                    description: OK
                "202":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Cancelled'
                    description: Successful Response
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Bad Request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "403":
                    description: Browser sessions allow reading only (read_only_access).
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Not Found
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Conflict
                "413":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Content Too Large
                "415":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unsupported Media Type
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unprocessable Content
                "503":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Service Unavailable
            security:
                - HTTPBearer: []
            summary: Cancel Run
    /api/v1/sessions/{sid}/runs/{rid}/messages:
        post:
            description: Send Message
            operationId: send_message
            parameters:
                - in: path
                  name: sid
                  required: true
                  schema:
                    format: uuid
                    title: Sid
                    type: string
                - in: path
                  name: rid
                  required: true
                  schema:
                    format: uuid
                    title: Rid
                    type: string
                - in: header
                  name: Idempotency-Key
                  required: false
                  schema:
                    anyOf:
                        - type: string
                        - type: "null"
                    title: Idempotency-Key
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/SendMessage'
                required: true
            responses:
                "202":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Accepted'
                    description: Successful Response
                    headers:
                        Location:
                            description: URL of the accepted run.
                            required: true
                            schema:
                                type: string
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Bad Request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "403":
                    description: Browser sessions allow reading only (read_only_access).
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Not Found
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Conflict
                "413":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Content Too Large
                "415":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unsupported Media Type
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unprocessable Content
                "503":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Service Unavailable
            security:
                - HTTPBearer: []
            summary: Send Message
servers:
    - description: Local development
      url: http://localhost:8000
