openapi: 3.1.0
info:
  title: Sandbox Platform API
  version: 1.0.0
  description: 'Integrator-facing Sandbox API via the gateway. Guides: https://sandbox.turing.com/docs


    ## Correlation and LLM tracing


    Send **`x-correlation-id`** on every request to tie logs, Cloud Trace, harbor
    async jobs, and Langfuse traces to one eval run.


    | Field | Source | Langfuse |

    | --- | --- | --- |

    | `x-correlation-id` | Your client (or gateway-generated ULID if omitted) | `trace.id`
    |

    | Harbor `job_id` | Response header / poll URL | `session_id` (groups LLM generations)
    |


    The header is echoed on responses. Async jobs (`POST .../jobs/execute-tasks`)
    copy it into the Pub/Sub payload so workers and harbor subprocesses continue the
    same id.


    Platform docs: [Observability](/docs/introduction/observability).

    '
servers:
- url: http://localhost:8780
  description: Local gateway
- url: https://sandbox-dev.turing.com
  description: Development
- url: https://sandbox.turing.com
  description: Production
paths:
  /sandbox/healthz:
    get:
      tags:
      - Gateway
      summary: Gateway aggregated health
      operationId: sandbox_healthz_sandbox_healthz_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Sandbox Healthz Sandbox Healthz Get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
  /sandbox/v1/catalog:
    get:
      tags:
      - Gateway
      summary: Execution catalog (languages, agents, profiles)
      operationId: catalog_list_sandbox_v1_catalog_get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: kind
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Kind
      responses:
        '200':
          description: Execution catalog entries
          content:
            application/json:
              schema: {}
              examples:
                agents:
                  summary: Tier-1 agents
                  value:
                    items:
                    - id: oracle
                      kind: agent
                      tier: 1
                    - id: opencode
                      kind: agent
                      tier: 1
                    count: 2
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/v1/usage/summary:
    get:
      tags:
      - Gateway
      summary: Project-scoped latency percentiles (p50/p95/p99)
      operationId: usage_summary_sandbox_v1_usage_summary_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Usage Summary Sandbox V1 Usage Summary Get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
  /sandbox/v1/admin/credential-plane/teams:
    post:
      tags:
      - Admin
      summary: 'Admin: create team (credential plane)'
      operationId: admin_create_team_cp_sandbox_v1_admin_credential_plane_teams_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Admin Create Team Cp Sandbox V1 Admin Credential Plane
                  Teams Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
  /sandbox/v1/admin/credential-plane/keys:
    post:
      tags:
      - Admin
      summary: 'Admin: add LLM provider key (credential plane)'
      operationId: admin_add_key_cp_sandbox_v1_admin_credential_plane_keys_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Admin Add Key Cp Sandbox V1 Admin Credential Plane
                  Keys Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
  /sandbox/v1/admin/keyhive/teams:
    post:
      tags:
      - Admin
      summary: 'Admin: create KeyHive team (legacy path; proxies credential plane)'
      operationId: admin_create_team_sandbox_v1_admin_keyhive_teams_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Admin Create Team Sandbox V1 Admin Keyhive Teams Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
  /sandbox/v1/admin/keyhive/keys:
    post:
      tags:
      - Admin
      summary: 'Admin: add LLM provider key (legacy path; proxies credential plane)'
      operationId: admin_add_key_sandbox_v1_admin_keyhive_keys_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Admin Add Key Sandbox V1 Admin Keyhive Keys Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
  /sandbox/harbor/capabilities:
    get:
      tags:
      - Harbor
      summary: Harbor runner capabilities
      operationId: harbor_capabilities_capabilities_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Capabilities Capabilities Get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
  /sandbox/harbor/run:
    post:
      tags:
      - Harbor
      summary: Run a Harbor task
      operationId: harbor_run_harbor_run_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunResponse'
        '502':
          description: Harbor subprocess failed
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
  /sandbox/harbor/v1/capabilities:
    get:
      tags:
      - Harbor v1
      summary: Harbor API v1 capabilities
      operationId: harbor_versioned_capabilities_v1_capabilities_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Versioned Capabilities V1 Capabilities Get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
  /sandbox/harbor/v1/run/datapoint:
    post:
      tags:
      - Harbor v1
      summary: Run Harbor datapoint (v1)
      operationId: harbor_run_datapoint_v1_run_datapoint_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunDatapointRequest'
            examples:
              oracle_with_extensions:
                summary: Oracle agent with harbor_extensions
                value:
                  task_slug: example-task
                  metadata:
                    task_archive_url: https://storage.example/tasks/example-task.zip
                  agents:
                  - name: oracle
                    harbor_agent: oracle
                    harbor_extensions:
                      agent_env:
                        SANDBOX_DOCS: '1'
        required: true
      responses:
        '200':
          description: Datapoint completed
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Run Datapoint V1 Run Datapoint Post
              examples:
                success:
                  summary: Succeeded datapoint
                  value:
                    job_id: 550e8400-e29b-41d4-a716-446655440000
                    status: succeeded
                    results:
                    - agent: oracle
                      reward: 1.0
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
  /sandbox/harbor/v1/jobs/execute-tasks:
    post:
      tags:
      - Harbor v1
      summary: Enqueue Harbor datapoint job (v1)
      operationId: harbor_execute_tasks_v1_jobs_execute_tasks_post
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency-Key
      - name: X-Sandbox-Job-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sandbox-Job-Id
      - name: X-Sandbox-Project-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sandbox-Project-Id
      - name: X-Sandbox-Tenant-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sandbox-Tenant-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteTasksRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                title: Response Execute Tasks V1 Jobs Execute Tasks Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/harbor/v1/jobs/{job_id}:
    get:
      tags:
      - Harbor v1
      summary: Get job status (v1)
      operationId: harbor_get_job_v1_jobs__job_id__get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Job status
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Job V1 Jobs  Job Id  Get
              examples:
                running:
                  summary: Job in progress
                  value:
                    job_id: 550e8400-e29b-41d4-a716-446655440000
                    status: running
                    timings:
                      queued_at: '2026-01-01T00:00:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/harbor/v1/jobs/{job_id}/cancel:
    post:
      tags:
      - Harbor v1
      summary: Cancel job (v1)
      operationId: harbor_cancel_job_v1_jobs__job_id__cancel_post
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Cancel Job V1 Jobs  Job Id  Cancel Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/harbor/v1/jobs/{job_id}/events:
    get:
      tags:
      - Harbor v1
      summary: SSE job events (v1)
      operationId: harbor_job_events_v1_jobs__job_id__events_get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: Last-Event-ID
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Last-Event-Id
      responses:
        '200':
          description: Server-sent events stream
          content:
            application/json:
              schema: {}
            text/event-stream:
              examples:
                meta:
                  summary: SSE stream (meta + done)
                  value: 'event: meta\ndata: {"job_id":"550e8400-e29b-41d4-a716-446655440000"}\n\n'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/harbor/v1/jobs/{job_id}/artifacts:
    get:
      tags:
      - Harbor v1
      summary: List job artifacts (v1)
      operationId: harbor_list_artifacts_v1_jobs__job_id__artifacts_get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Artifacts V1 Jobs  Job Id  Artifacts Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/harbor/v1/jobs/{job_id}/artifacts/archive:
    get:
      tags:
      - Harbor v1
      summary: Download job archive (v1)
      operationId: harbor_download_archive_v1_jobs__job_id__artifacts_archive_get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: presigned
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Presigned
      - name: as
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: As
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/harbor/v1/jobs/{job_id}/artifacts/test-stdout/{relative_path}:
    get:
      tags:
      - Harbor v1
      summary: Download verifier test stdout (v1)
      operationId: harbor_download_test_stdout_v1_jobs__job_id__artifacts_test_stdout__relative_path__get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: relative_path
        in: path
        required: true
        schema:
          type: string
          title: Relative Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/harbor/v2/capabilities:
    get:
      tags:
      - Harbor v2
      summary: Harbor API v2 capabilities
      operationId: harbor_versioned_capabilities_v2_capabilities_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Versioned Capabilities V2 Capabilities Get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
  /sandbox/harbor/v2/run/datapoint:
    post:
      tags:
      - Harbor v2
      summary: Run Harbor datapoint (v2)
      operationId: harbor_run_datapoint_v2_run_datapoint_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunDatapointRequest'
            examples:
              oracle_with_extensions:
                summary: Oracle agent with harbor_extensions
                value:
                  task_slug: example-task
                  metadata:
                    task_archive_url: https://storage.example/tasks/example-task.zip
                  agents:
                  - name: oracle
                    harbor_agent: oracle
                    harbor_extensions:
                      agent_env:
                        SANDBOX_DOCS: '1'
        required: true
      responses:
        '200':
          description: Datapoint completed
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Run Datapoint V2 Run Datapoint Post
              examples:
                success:
                  summary: Succeeded datapoint
                  value:
                    job_id: 550e8400-e29b-41d4-a716-446655440000
                    status: succeeded
                    results:
                    - agent: oracle
                      reward: 1.0
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
  /sandbox/harbor/v2/jobs/execute-tasks:
    post:
      tags:
      - Harbor v2
      summary: Enqueue Harbor datapoint job (v2)
      operationId: harbor_execute_tasks_v2_jobs_execute_tasks_post
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency-Key
      - name: X-Sandbox-Job-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sandbox-Job-Id
      - name: X-Sandbox-Project-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sandbox-Project-Id
      - name: X-Sandbox-Tenant-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sandbox-Tenant-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteTasksRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                title: Response Execute Tasks V2 Jobs Execute Tasks Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/harbor/v2/jobs/{job_id}:
    get:
      tags:
      - Harbor v2
      summary: Get job status (v2)
      operationId: harbor_get_job_v2_jobs__job_id__get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Job status
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Job V2 Jobs  Job Id  Get
              examples:
                running:
                  summary: Job in progress
                  value:
                    job_id: 550e8400-e29b-41d4-a716-446655440000
                    status: running
                    timings:
                      queued_at: '2026-01-01T00:00:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/harbor/v2/jobs/{job_id}/cancel:
    post:
      tags:
      - Harbor v2
      summary: Cancel job (v2)
      operationId: harbor_cancel_job_v2_jobs__job_id__cancel_post
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Cancel Job V2 Jobs  Job Id  Cancel Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/harbor/v2/jobs/{job_id}/events:
    get:
      tags:
      - Harbor v2
      summary: SSE job events (v2)
      operationId: harbor_job_events_v2_jobs__job_id__events_get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: Last-Event-ID
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Last-Event-Id
      responses:
        '200':
          description: Server-sent events stream
          content:
            application/json:
              schema: {}
            text/event-stream:
              examples:
                meta:
                  summary: SSE stream (meta + done)
                  value: 'event: meta\ndata: {"job_id":"550e8400-e29b-41d4-a716-446655440000"}\n\n'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/harbor/v2/jobs/{job_id}/artifacts:
    get:
      tags:
      - Harbor v2
      summary: List job artifacts (v2)
      operationId: harbor_list_artifacts_v2_jobs__job_id__artifacts_get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Artifacts V2 Jobs  Job Id  Artifacts Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/harbor/v2/jobs/{job_id}/artifacts/archive:
    get:
      tags:
      - Harbor v2
      summary: Download job archive (v2)
      operationId: harbor_download_archive_v2_jobs__job_id__artifacts_archive_get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: presigned
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Presigned
      - name: as
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: As
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/harbor/v2/jobs/{job_id}/artifacts/test-stdout/{relative_path}:
    get:
      tags:
      - Harbor v2
      summary: Download verifier test stdout (v2)
      operationId: harbor_download_test_stdout_v2_jobs__job_id__artifacts_test_stdout__relative_path__get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: relative_path
        in: path
        required: true
        schema:
          type: string
          title: Relative Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/harbor/run/datapoint:
    post:
      tags:
      - Harbor
      summary: Run Harbor datapoint (v1)
      operationId: harbor_run_datapoint_run_datapoint_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunDatapointRequest'
            examples:
              oracle_with_extensions:
                summary: Oracle agent with harbor_extensions
                value:
                  task_slug: example-task
                  metadata:
                    task_archive_url: https://storage.example/tasks/example-task.zip
                  agents:
                  - name: oracle
                    harbor_agent: oracle
                    harbor_extensions:
                      agent_env:
                        SANDBOX_DOCS: '1'
        required: true
      responses:
        '200':
          description: Datapoint completed
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Run Datapoint Run Datapoint Post
              examples:
                success:
                  summary: Succeeded datapoint
                  value:
                    job_id: 550e8400-e29b-41d4-a716-446655440000
                    status: succeeded
                    results:
                    - agent: oracle
                      reward: 1.0
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
  /sandbox/harbor/jobs/execute-tasks:
    post:
      tags:
      - Harbor
      summary: Enqueue Harbor datapoint job (v1)
      operationId: harbor_execute_tasks_jobs_execute_tasks_post
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency-Key
      - name: X-Sandbox-Job-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sandbox-Job-Id
      - name: X-Sandbox-Project-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sandbox-Project-Id
      - name: X-Sandbox-Tenant-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Sandbox-Tenant-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteTasksRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                title: Response Execute Tasks Jobs Execute Tasks Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/harbor/jobs/{job_id}:
    get:
      tags:
      - Harbor
      summary: Get job status (v1)
      operationId: harbor_get_job_jobs__job_id__get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Job status
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Job Jobs  Job Id  Get
              examples:
                running:
                  summary: Job in progress
                  value:
                    job_id: 550e8400-e29b-41d4-a716-446655440000
                    status: running
                    timings:
                      queued_at: '2026-01-01T00:00:00Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/harbor/jobs/{job_id}/cancel:
    post:
      tags:
      - Harbor
      summary: Cancel job (v1)
      operationId: harbor_cancel_job_jobs__job_id__cancel_post
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Cancel Job Jobs  Job Id  Cancel Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/harbor/jobs/{job_id}/events:
    get:
      tags:
      - Harbor
      summary: SSE job events (v1)
      operationId: harbor_job_events_jobs__job_id__events_get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: Last-Event-ID
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Last-Event-Id
      responses:
        '200':
          description: Server-sent events stream
          content:
            application/json:
              schema: {}
            text/event-stream:
              examples:
                meta:
                  summary: SSE stream (meta + done)
                  value: 'event: meta\ndata: {"job_id":"550e8400-e29b-41d4-a716-446655440000"}\n\n'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/harbor/jobs/{job_id}/artifacts:
    get:
      tags:
      - Harbor
      summary: List job artifacts (v1)
      operationId: harbor_list_artifacts_jobs__job_id__artifacts_get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Artifacts Jobs  Job Id  Artifacts Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/harbor/jobs/{job_id}/artifacts/archive:
    get:
      tags:
      - Harbor
      summary: Download job archive (v1)
      operationId: harbor_download_archive_jobs__job_id__artifacts_archive_get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: presigned
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Presigned
      - name: as
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: As
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/harbor/jobs/{job_id}/artifacts/test-stdout/{relative_path}:
    get:
      tags:
      - Harbor
      summary: Download verifier test stdout (v1)
      operationId: harbor_download_test_stdout_jobs__job_id__artifacts_test_stdout__relative_path__get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: relative_path
        in: path
        required: true
        schema:
          type: string
          title: Relative Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/harbor/api-versions:
    get:
      tags:
      - Harbor
      summary: List Harbor API versions
      operationId: harbor_api_versions_api_versions_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Api Versions Api Versions Get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
  /sandbox/agent/v1/agents:
    get:
      tags:
      - Agent Runtime
      summary: List Agents
      description: Tier 1 catalog entries plus Harbor AgentFactory agents (deduped).
      operationId: agent_list_agents_v1_agents_get
      responses:
        '200':
          description: "Catalog \u222A Harbor factory agents"
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response List Agents V1 Agents Get
              examples:
                agents:
                  summary: Agent registry
                  value:
                    agents:
                    - id: oracle
                      display_name: Oracle
                      source: catalog
                    - id: opencode
                      display_name: OpenCode
                      source: catalog
                    count: 2
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
  /sandbox/agent/capabilities:
    get:
      tags:
      - Agent Runtime
      summary: List agents (catalog-backed)
      operationId: agent_capabilities_capabilities_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Capabilities Capabilities Get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
  /sandbox/agent/v1/runs:
    post:
      tags:
      - Agent Runtime
      summary: Start Agent Run
      operationId: agent_start_agent_run_v1_runs_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRunBody'
            examples:
              oracle_smoke:
                summary: Oracle agent run with harbor_extensions
                value:
                  agent_id: oracle
                  instruction: List files in the workspace root.
                  harbor_extensions:
                    agent_env:
                      SANDBOX_DOCS: '1'
              opencode_plan:
                summary: OpenCode plan via opencode.json default_agent (not Harbor
                  --mode)
                value:
                  agent_id: opencode
                  instruction: Propose a plan to fix the failing test
                  model: anthropic/claude-sonnet-4-5
                  harbor_extensions:
                    opencode_agent: plan
                    agent_env:
                      SANDBOX_DOCS: '1'
        required: true
      responses:
        '202':
          description: Run accepted
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Start Agent Run V1 Runs Post
              examples:
                accepted:
                  summary: Queued agent run
                  value:
                    job_id: agent-run-550e8400
                    status: queued
                    agent_id: oracle
                    message: run accepted
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
  /sandbox/agent/agents/{agent_id}:
    get:
      tags:
      - Agent Runtime
      summary: Get Agent
      operationId: agent_get_agent_agents__agent_id__get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /sandbox/agent/agents:
    post:
      tags:
      - Agent Runtime
      summary: Register Agent
      operationId: agent_register_agent_agents_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
  /sandbox/codeedit/v1/languages:
    get:
      tags:
      - CodeEdit
      summary: List Languages
      operationId: codeedit_list_languages_v1_languages_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response List Languages V1 Languages Get
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
  /sandbox/codeedit/v1/executions:
    post:
      tags:
      - CodeEdit
      summary: Execute
      operationId: codeedit_execute_v1_executions_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecutionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Execute V1 Executions Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
  /sandbox/browser/v1/sessions:
    post:
      summary: Create Session
      operationId: browser_create_session_v1_sessions_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
                title: Response Create Session V1 Sessions Post
      tags:
      - Browser
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
  /sandbox/cirunner/v1/runs:
    post:
      summary: Start Run
      operationId: cirunner_start_run_v1_runs_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CiRunBody'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties:
                  anyOf:
                  - type: string
                  - type: integer
                  - type: 'null'
                type: object
                title: Response Start Run V1 Runs Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - CI Runner
      parameters:
      - $ref: '#/components/parameters/CorrelationId'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Break-glass or service API key
    KeyHiveBearer:
      type: http
      scheme: bearer
      description: KeyHive team token for multi-tenant runs
    KeycloakBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Keycloak service token
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    DatapointAgentBody:
      properties:
        name:
          type: string
          title: Name
          description: Logical agent label in the datapoint result
        harbor_agent:
          type: string
          title: Harbor Agent
          description: Harbor agent id (catalog or factory)
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: LLM model override
        pass_at_k:
          type: integer
          minimum: 1.0
          title: Pass At K
          default: 1
        params:
          additionalProperties: true
          type: object
          title: Params
          description: Per-request agent kwargs forwarded to Harbor as ``--ak key=value``.
            Merged with ``harbor_extensions.agent_kwargs`` (extensions win on conflict).
        harbor_extensions:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Harbor Extensions
          description: "Harbor passthrough: agent_env (--ae), agent_kwargs (--ak),\
            \ sandbox (-e), n_concurrent, custom_agent_import. When harbor_agent is\
            \ opencode: opencode_agent sets default_agent in opencode.json (plan |\
            \ build); opencode_config deep-merges an allowlisted subset of opencode.json\
            \ (agent, permission, tools, model, small_model, subagent_depth, instructions,\
            \ command, mcp) \u2014 e.g. a custom agent.review subagent."
      type: object
      required:
      - name
      - harbor_agent
      title: DatapointAgentBody
    DeliverSpec:
      properties:
        agent_run_zip:
          anyOf:
          - $ref: '#/components/schemas/PresignedDeliverable'
          - type: 'null'
          description: Upload agent outputs as a single zip after the run.
      additionalProperties: false
      type: object
      title: DeliverSpec
      description: "v2 customer delivery \u2014 maps to staged_zip writeback internally."
    ExecuteTasksRequest:
      properties:
        task_slug:
          type: string
          title: Task Slug
        agents:
          items:
            $ref: '#/components/schemas/DatapointAgentBody'
          type: array
          title: Agents
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        artifacts:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Artifacts
        sandbox:
          anyOf:
          - type: string
          - type: 'null'
          title: Sandbox
        notifications:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Notifications
        writeback:
          anyOf:
          - $ref: '#/components/schemas/HarborTaskWritebackSpec'
          - type: 'null'
        deliver:
          anyOf:
          - $ref: '#/components/schemas/DeliverSpec'
          - type: 'null'
      type: object
      required:
      - task_slug
      - agents
      title: ExecuteTasksRequest
    HarborTaskWritebackSpec:
      properties:
        enabled:
          type: boolean
          title: Enabled
          default: true
        destination:
          $ref: '#/components/schemas/WritebackDestination'
        mode:
          type: string
          enum:
          - in_place_overwrite
          - versioned_suffix
          - staged_zip
          title: Mode
          default: in_place_overwrite
        include_paths:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Include Paths
        include_run_outputs:
          type: boolean
          title: Include Run Outputs
          default: true
        include_judge_outputs:
          type: boolean
          title: Include Judge Outputs
          default: false
        deliverable_files:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Deliverable Files
        deliverable_destination_prefix:
          type: string
          title: Deliverable Destination Prefix
          default: outputs/{label}/
        missing_deliverable_is_failure:
          type: boolean
          title: Missing Deliverable Is Failure
          default: true
        include_telemetry:
          type: boolean
          title: Include Telemetry
          default: false
        deliverables_only:
          type: boolean
          title: Deliverables Only
          default: false
      additionalProperties: false
      type: object
      required:
      - destination
      title: HarborTaskWritebackSpec
    PresignedDeliverable:
      properties:
        url:
          type: string
          minLength: 1
          title: Url
          description: Presigned PUT (or POST) URL.
        method:
          type: string
          enum:
          - PUT
          - POST
          title: Method
          default: PUT
        headers:
          additionalProperties:
            type: string
          type: object
          title: Headers
        key:
          type: string
          title: Key
          description: Logical artifact name in writeback outcomes.
          default: agent_run.zip
      additionalProperties: false
      type: object
      required:
      - url
      title: PresignedDeliverable
      description: One presigned HTTP upload target.
    PresignedPut:
      properties:
        key:
          type: string
          title: Key
          description: Relative path under the destination root. The writeback step
            matches files to URLs by this key.
        url:
          type: string
          minLength: 1
          title: Url
        method:
          type: string
          enum:
          - PUT
          - POST
          title: Method
          default: PUT
        headers:
          additionalProperties:
            type: string
          type: object
          title: Headers
      additionalProperties: false
      type: object
      required:
      - key
      - url
      title: PresignedPut
      description: One presigned write target, keyed by relative path within the destination.
    RunDatapointRequest:
      properties:
        task_slug:
          type: string
          title: Task Slug
        agents:
          items:
            $ref: '#/components/schemas/DatapointAgentBody'
          type: array
          title: Agents
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        artifacts:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Artifacts
        sandbox:
          anyOf:
          - type: string
          - type: 'null'
          title: Sandbox
        notifications:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Notifications
        writeback:
          anyOf:
          - $ref: '#/components/schemas/HarborTaskWritebackSpec'
          - type: 'null'
        deliver:
          anyOf:
          - $ref: '#/components/schemas/DeliverSpec'
          - type: 'null'
      type: object
      required:
      - task_slug
      - agents
      title: RunDatapointRequest
    RunRequest:
      properties:
        task_dir:
          type: string
          title: Task Dir
          description: Harbor Class-A task directory path (absolute or relative),
            must resolve under SANDBOX_HARBOR_JOBS_DIR
        agent:
          type: string
          title: Agent
          description: Harbor --agent id (e.g. oracle, claude-code, codex)
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: LiteLLM model string for -m
        n_attempts:
          type: integer
          minimum: 1.0
          title: N Attempts
          default: 1
        sandbox:
          anyOf:
          - type: string
          - type: 'null'
          title: Sandbox
          description: Sandbox driver hint
          default: docker
        job_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Job Id
      type: object
      required:
      - task_dir
      - agent
      title: RunRequest
      description: Request to execute a harbor-format task directory.
    RunResponse:
      properties:
        job_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Job Id
        agent:
          type: string
          title: Agent
        result:
          additionalProperties: true
          type: object
          title: Result
      type: object
      required:
      - job_id
      - agent
      - result
      title: RunResponse
    WritebackDestination:
      properties:
        url:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          title: Url
          description: Destination root URL (``s3://``, ``gs://``, or presigned PUT
            for ``staged_zip``). Optional when ``presigned_writes`` fully specifies
            targets.
        presigned_writes:
          anyOf:
          - items:
              $ref: '#/components/schemas/PresignedPut'
            type: array
          - type: 'null'
          title: Presigned Writes
        storage_connector_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Storage Connector Id
      additionalProperties: false
      type: object
      title: WritebackDestination
    AgentOut:
      properties:
        id:
          type: string
          title: Id
        display_name:
          type: string
          title: Display Name
        requires_model:
          type: boolean
          title: Requires Model
        mcp_adapter:
          anyOf:
          - type: string
          - type: 'null'
          title: Mcp Adapter
        air_gap_capable:
          type: boolean
          title: Air Gap Capable
          default: false
      type: object
      required:
      - id
      - display_name
      - requires_model
      title: AgentOut
    AgentRunBody:
      properties:
        agent_id:
          type: string
          minLength: 1
          title: Agent Id
        instruction:
          type: string
          minLength: 1
          title: Instruction
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
        workspace:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Workspace
        harbor_extensions:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Harbor Extensions
          description: "Harbor passthrough: agent_env, agent_kwargs, sandbox, n_concurrent,\
            \ custom_agent_import. When agent_id is opencode: opencode_agent sets\
            \ default_agent in opencode.json (plan | build); opencode_config deep-merges\
            \ an allowlisted subset of opencode.json (agent, permission, tools, model,\
            \ small_model, subagent_depth, instructions, command, mcp) \u2014 e.g.\
            \ a custom agent.review subagent."
      type: object
      required:
      - agent_id
      - instruction
      title: AgentRunBody
    RegisterRequest:
      properties:
        id:
          type: string
          minLength: 1
          title: Id
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
        requires_model:
          type: boolean
          title: Requires Model
          default: true
        mcp_adapter:
          anyOf:
          - type: string
          - type: 'null'
          title: Mcp Adapter
        air_gap_capable:
          type: boolean
          title: Air Gap Capable
          default: false
      type: object
      required:
      - id
      title: RegisterRequest
    ExecutionRequest:
      properties:
        language:
          type: string
          minLength: 1
          title: Language
        files:
          additionalProperties:
            type: string
          type: object
          title: Files
        stdin:
          anyOf:
          - type: string
          - type: 'null'
          title: Stdin
        limits:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Limits
      type: object
      required:
      - language
      title: ExecutionRequest
    CiRunBody:
      properties:
        commands:
          items:
            type: string
          type: array
          title: Commands
      type: object
      title: CiRunBody
  parameters:
    CorrelationId:
      name: x-correlation-id
      in: header
      required: false
      description: End-to-end correlation id for this eval run. When set, the gateway
        and downstream services honor it verbatim in logs, Cloud Trace span attributes,
        async job payloads, and Langfuse trace.id. When omitted, the gateway generates
        a ULID and echoes it on the response.
      schema:
        type: string
      example: eval-run-2026-07-21-abc123
security:
- ApiKeyAuth: []
- KeyHiveBearer: []
- KeycloakBearer: []
tags:
- name: Gateway
  description: Catalog, health, usage
- name: Harbor v2
  description: Benchmark datapoint and async jobs (recommended)
- name: Harbor v1
  description: Legacy Harbor paths
- name: Harbor
  description: Unversioned Harbor paths
- name: Agent Runtime
  description: Ad-hoc LLM agent runs
- name: CodeEdit
  description: Code execution without LLM
- name: Browser
  description: Browser automation sessions
- name: CI Runner
  description: CI commands in sandbox
- name: Admin
  description: Credential plane administration
