Trajectory Benchmark Ingestion API

openapi: 3.2.0
info:
  title: Trajectory Benchmark Ingestion API
  version: 0.1.0
  x-trajectory-api-version: '2026-10-14'
  description: This contract is API version 2026-10-14. The optional Trajectory-API-Version header pins it, and tmp-contract is accepted as an alias. Requests without the header get this version. Version 2026-10-07 and the pre-launch legacy response formats are retired.
tags:
- name: benchmark-ingestion
paths:
  /api/v1/benchmark-ingestion/sessions:
    post:
      tags:
      - benchmark-ingestion
      summary: Create Session
      operationId: createBenchmarkSubmissionSession
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 128
          title: Idempotency-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BenchmarkIngestionSubmissionRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenchmarkIngestionSession'
          headers:
            X-Trajectory-Ingestion-Created:
              description: True for a newly committed session; false for an idempotent replay.
              schema:
                type: string
                enum:
                - 'true'
                - 'false'
      x-trajectory-visibility: public
  /api/v1/benchmark-ingestion/sessions/{operation_id}/uploads:
    post:
      tags:
      - benchmark-ingestion
      summary: Allocate
      operationId: allocateBenchmarkSubmissionUploads
      parameters:
      - name: operation_id
        in: path
        required: true
        schema:
          type: string
          title: Operation Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BenchmarkIngestionAllocateObjectsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenchmarkIngestionUploadUrls'
      x-trajectory-visibility: public
  /api/v1/benchmark-ingestion/sessions/{operation_id}/finalize:
    post:
      tags:
      - benchmark-ingestion
      summary: Finalize
      operationId: finalizeBenchmarkSubmission
      parameters:
      - name: operation_id
        in: path
        required: true
        schema:
          type: string
          title: Operation Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BenchmarkIngestionFinalizeSubmissionRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenchmarkIngestionOperationStatus'
      x-trajectory-visibility: public
  /api/v1/benchmark-ingestion/sessions/{operation_id}/cancel:
    post:
      tags:
      - benchmark-ingestion
      summary: Cancel
      description: Cancel an uploading, queued, or running submission; finished submissions return 409.
      operationId: cancelBenchmarkSubmissionSession
      parameters:
      - name: operation_id
        in: path
        required: true
        schema:
          type: string
          title: Operation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenchmarkIngestionOperationStatus'
      x-trajectory-visibility: public
  /api/v1/benchmark-ingestion/operations/{operation_id}:
    get:
      tags:
      - benchmark-ingestion
      summary: Status
      operationId: getBenchmarkSubmissionOperation
      parameters:
      - name: operation_id
        in: path
        required: true
        schema:
          type: string
          title: Operation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenchmarkIngestionOperationStatus'
      x-trajectory-visibility: public
  /api/v1/benchmark-ingestion/operations/{operation_id}/{kind}:
    get:
      tags:
      - benchmark-ingestion
      summary: Items
      operationId: listBenchmarkSubmissionItems
      parameters:
      - name: operation_id
        in: path
        required: true
        schema:
          type: string
          title: Operation Id
      - name: kind
        in: path
        required: true
        schema:
          enum:
          - result
          - failure
          - runtime
          - runtime_task
          type: string
          title: Kind
      - name: after
        in: query
        required: false
        schema:
          type: string
          maxLength: 1024
          default: ''
          title: After
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 100
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenchmarkIngestionOperationPage'
      x-trajectory-visibility: public
components:
  schemas:
    BenchmarkIngestionOperationStatus:
      properties:
        operation_id:
          type: string
          title: Operation Id
        bench_id:
          type: string
          title: Bench Id
        status:
          type: string
          enum:
          - uploading
          - queued
          - running
          - cancelled
          - succeeded
          - partial_failure
          - failed
          title: Status
        stage:
          type: string
          enum:
          - verifying
          - registering
          - building
          title: Stage
        attempt:
          type: integer
          minimum: 0.0
          title: Attempt
        max_attempts:
          type: integer
          minimum: 1.0
          title: Max Attempts
        last_error:
          anyOf:
          - $ref: '#/components/schemas/BenchmarkIngestionFailure'
          - type: 'null'
        task_count:
          type: integer
          title: Task Count
          default: 0
        added_count:
          type: integer
          title: Added Count
          default: 0
        updated_count:
          type: integer
          title: Updated Count
          default: 0
        skipped_count:
          type: integer
          title: Skipped Count
          default: 0
        registered_tasks:
          type: integer
          title: Registered Tasks
          default: 0
        total_tasks:
          type: integer
          title: Total Tasks
          default: 0
        ready_runtimes:
          type: integer
          title: Ready Runtimes
          default: 0
        total_runtimes:
          type: integer
          title: Total Runtimes
          default: 0
        failure_count:
          type: integer
          title: Failure Count
          default: 0
        build_images:
          type: boolean
          title: Build Images
        ready:
          type: boolean
          title: Ready
          default: false
      type: object
      required:
      - operation_id
      - bench_id
      - status
      - stage
      - attempt
      - max_attempts
      - build_images
      title: BenchmarkIngestionOperationStatus
    BenchmarkIngestionSession:
      properties:
        session_id:
          type: string
          title: Session Id
        bench_id:
          type: string
          title: Bench Id
        accepted:
          type: boolean
          title: Accepted
      type: object
      required:
      - session_id
      - bench_id
      - accepted
      title: BenchmarkIngestionSession
    BenchmarkIngestionFinalizeSubmissionRequest:
      properties:
        object_count:
          type: integer
          minimum: 1.0
          title: Object Count
        part_count:
          type: integer
          minimum: 1.0
          title: Part Count
      additionalProperties: false
      type: object
      required:
      - object_count
      - part_count
      title: BenchmarkIngestionFinalizeSubmissionRequest
    BenchmarkUploadUrl:
      properties:
        path:
          type: string
          title: Path
        url:
          type: string
          title: Url
        headers:
          additionalProperties:
            type: string
          type: object
          title: Headers
      type: object
      required:
      - path
      - url
      - headers
      title: BenchmarkUploadUrl
    BenchmarkIngestionUploadObject:
      properties:
        path:
          type: string
          title: Path
        content_type:
          type: string
          title: Content Type
        size_bytes:
          type: integer
          title: Size Bytes
        md5:
          type: string
          maxLength: 24
          pattern: ^[A-Za-z0-9+/]{22}==$
          title: Md5
        kind:
          type: string
          enum:
          - artifact
          - part
          title: Kind
          default: artifact
      additionalProperties: false
      type: object
      required:
      - path
      - content_type
      - size_bytes
      - md5
      title: BenchmarkIngestionUploadObject
    BenchmarkIngestionRuntimeResult:
      properties:
        runtime_id:
          type: string
          title: Runtime Id
        status:
          type: string
          enum:
          - pending
          - building
          - ready
          - failed
          title: Status
        provider_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider Ref
      type: object
      required:
      - runtime_id
      - status
      title: BenchmarkIngestionRuntimeResult
    BenchmarkIngestionTaskResult:
      properties:
        task_id:
          type: string
          title: Task Id
        name:
          type: string
          title: Name
        runtime_id:
          type: string
          title: Runtime Id
        action:
          type: string
          enum:
          - added
          - updated
          - skipped
          title: Action
      type: object
      required:
      - task_id
      - name
      - runtime_id
      - action
      title: BenchmarkIngestionTaskResult
    BenchmarkIngestionAllocateObjectsRequest:
      properties:
        files:
          items:
            $ref: '#/components/schemas/BenchmarkIngestionUploadObject'
          type: array
          maxItems: 5000
          minItems: 1
          title: Files
          description: At most 1000 files and 1024 KiB with `put`, or 5000 files and 4096 KiB with `post`.
        upload_method:
          type: string
          enum:
          - put
          - post
          title: Upload Method
          description: '`put` returns a signed PUT URL per file. `post` returns one signed form-upload policy for the whole batch; uploads are checked against their declarations when the submission is verified.'
          default: put
      additionalProperties: false
      type: object
      required:
      - files
      title: BenchmarkIngestionAllocateObjectsRequest
    BenchmarkIngestionFailure:
      properties:
        stage:
          type: string
          enum:
          - verifying
          - registering
          - building
          title: Stage
        resource_type:
          type: string
          enum:
          - submission
          - upload
          - task
          - runtime
          title: Resource Type
        resource_id:
          type: string
          title: Resource Id
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
        retryable:
          type: boolean
          title: Retryable
        provider_status_code:
          anyOf:
          - type: integer
            maximum: 599.0
            minimum: 100.0
          - type: 'null'
          title: Provider Status Code
        affected_tasks_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Affected Tasks Cursor
        resolved:
          type: boolean
          title: Resolved
          default: false
      type: object
      required:
      - stage
      - resource_type
      - resource_id
      - code
      - message
      - retryable
      title: BenchmarkIngestionFailure
    BenchmarkIngestionSubmissionRequest:
      properties:
        agent_id:
          anyOf:
          - type: string
            maxLength: 64
            pattern: ^agt_[a-z0-9]+$
          - type: 'null'
          title: Agent Id
          description: The benchmark's agent ID. Provide agent_id or agent_name for every ingestion.
        agent_name:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Agent Name
          description: The benchmark's agent name. Provide agent_id or agent_name for every ingestion.
        bench_name:
          type: string
          maxLength: 1024
          minLength: 3
          pattern: ^[A-Za-z0-9 ._-]+$
          title: Bench Name
          description: Reusing a benchmark name pushes a new version of that benchmark.
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        upload_digest:
          type: string
          pattern: ^[a-f0-9]{64}$
          title: Upload Digest
        build_images:
          type: boolean
          title: Build Images
          default: false
      additionalProperties: false
      type: object
      required:
      - bench_name
      - metadata
      - upload_digest
      title: BenchmarkIngestionSubmissionRequest
    BenchmarkIngestionUploadPolicy:
      properties:
        url:
          type: string
          title: Url
          description: Form upload endpoint (POST) for every file in the batch.
        fields:
          additionalProperties:
            type: string
          type: object
          title: Fields
          description: Signed form fields; send them with `key`, `Content-Type`, and the file as the last field, `file`.
        artifact_prefix:
          type: string
          title: Artifact Prefix
          description: An artifact's `key` is this prefix plus its path.
        part_prefix:
          type: string
          title: Part Prefix
          description: A task part's `key` is this prefix plus its path.
        expires_at:
          type: string
          format: date-time
          title: Expires At
          description: Uploads must start before this time.
      type: object
      required:
      - url
      - fields
      - artifact_prefix
      - part_prefix
      - expires_at
      title: BenchmarkIngestionUploadPolicy
    BenchmarkIngestionOperationPage:
      properties:
        items:
          items:
            anyOf:
            - $ref: '#/components/schemas/BenchmarkIngestionTaskResult'
            - $ref: '#/components/schemas/BenchmarkIngestionRuntimeResult'
            - $ref: '#/components/schemas/BenchmarkIngestionFailure'
          type: array
          title: Items
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      required:
      - items
      - next_cursor
      title: BenchmarkIngestionOperationPage
    BenchmarkIngestionUploadUrls:
      properties:
        urls:
          items:
            $ref: '#/components/schemas/BenchmarkUploadUrl'
          type: array
          title: Urls
        policy:
          anyOf:
          - $ref: '#/components/schemas/BenchmarkIngestionUploadPolicy'
          - type: 'null'
          description: Set instead of `urls` when the allocation requested `post`.
      type: object
      required:
      - urls
      title: BenchmarkIngestionUploadUrls
  securitySchemes:
    TrajectoryAccessToken:
      type: http
      description: Short-lived token scoped to one rollout trajectory
      scheme: bearer
    InferenceAuthorization:
      type: http
      scheme: bearer