openapi.yaml

openapi: 3.1.0
info:
  title: kernel_zoo API
  version: 1.0.0
  description: |
    HTTP API surface for the kernel_zoo platform. See
    docs/superpowers/specs/2026-08-02-kernel_zoo-design.md for the full
    design. SP1 ships the contract only; server implementation follows in SP2.
servers:
  - url: http://localhost:8080

x-kernel-zoo-conventions:
  kernel_id_path_capture: |
    All paths containing {kernel_id} use Starlette's :path converter, which
    captures the full remaining path (including '/'). Implementations must
    validate kernel_id segments against ^[A-Za-z0-9._-]+$ and reject any
    traversal ('..') before filesystem access.

components:
  securitySchemes:
    submitterAuth:
      type: apiKey
      in: header
      name: X-Submitter-Id
      description: Self-reported submitter identifier. Any non-empty string is accepted.
    runnerAuth:
      type: apiKey
      in: header
      name: X-Runner-Key
      description: Pre-shared runner key. Must match server config runner_keys[].
  schemas:
    ErrorEnvelope:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code: {type: string}
            message: {type: string}
            details: {type: object, additionalProperties: true}
    KernelSummary:
      type: object
      required: [id, summary, arch, op_class, sub_class, quant, status, tags]
      properties:
        id: {type: string}
        summary: {type: string}
        arch: {type: string}
        op_class: {type: string}
        sub_class: {type: string}
        quant: {type: string}
        status: {enum: [normal, frozen, deprecated]}
        tags: {type: array, items: {type: string}}
    KernelListResponse:
      type: object
      required: [kernels, page, page_size, total]
      properties:
        kernels:
          type: array
          items: {$ref: '#/components/schemas/KernelSummary'}
        page: {type: integer, minimum: 1}
        page_size: {type: integer, minimum: 1}
        total: {type: integer, minimum: 0}
    SubmissionAccepted:
      type: object
      required: [submission_uuid, status]
      properties:
        submission_uuid: {type: string, format: uuid}
        status: {enum: [queued]}
    SubmissionStatus:
      type: object
      required: [status]
      properties:
        status: {enum: [queued, running, done, lost]}
        result:
          description: Present only when status=done.
          type: object
        commit_sha:
          type: string
          nullable: true
        server_accept:
          type: boolean
          nullable: true
    SubmissionLost:
      type: object
      required: [status]
      properties:
        status: {enum: [lost]}
    RunnerClaimResponse:
      type: object
      required: [submission_uuid, kernel_id, package_url]
      properties:
        submission_uuid: {type: string, format: uuid}
        kernel_id: {type: string}
        package_url: {type: string, format: uri}
    HealthResponse:
      type: object
      required: [status]
      properties:
        status: {enum: [ok, degraded]}
        fault:
          type: object
          nullable: true
          properties:
            reason: {type: string}
            since: {type: string, format: date-time}
        queue_depth:
          type: object
          properties:
            pending: {type: integer}
            running: {type: integer}
        generated_index_at: {type: string, format: date-time, nullable: true}
    RebaseRequest:
      type: object
      required: [branch]
      properties:
        branch: {type: string}
    RebaseResponse:
      type: object
      required: [new_main_sha]
      properties:
        new_main_sha: {type: string}
    RebaseConflict:
      type: object
      required: [conflicts]
      properties:
        conflicts:
          type: array
          items: {type: string}
  responses:
    BadRequest:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
    GitFault:
      description: Repository fault; retry may succeed
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"

paths:
  /api/kernels:
    get:
      summary: List all kernel_packages
      security: []
      parameters:
        - in: query
          name: arch
          schema: {type: string}
        - in: query
          name: op_class
          schema: {type: string}
        - in: query
          name: status
          schema: {enum: [normal, frozen, deprecated]}
        - in: query
          name: tag
          schema: {type: string}
        - in: query
          name: page
          schema: {type: integer, minimum: 1, default: 1}
        - in: query
          name: page_size
          schema: {type: integer, minimum: 1, maximum: 200, default: 50}
        - in: query
          name: sort
          schema: {type: string, description: "e.g. -primary_metric_current or +summary"}
      responses:
        '200':
          description: List of kernel summaries.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/KernelListResponse'}
        '503':
          $ref: '#/components/responses/GitFault'

  /api/kernels/{kernel_id}:
    get:
      summary: Kernel detail
      security: []
      parameters:
        - name: kernel_id
          in: path
          required: true
          schema: {type: string}
          x-kernel-zoo-path-capture: true
          description: Path-style capture (allows '/').
      responses:
        '200': {description: desc.yaml as JSON + bench_result.yaml summary.}
        '404':
          $ref: '#/components/responses/NotFound'

  /api/kernels/{kernel_id}/bench-history:
    get:
      summary: Best/current metric summary for a kernel
      security: []
      parameters:
        - name: kernel_id
          in: path
          required: true
          schema: {type: string}
          x-kernel-zoo-path-capture: true
      responses:
        '200': {description: Per-case best/current metrics.}
        '404':
          $ref: '#/components/responses/NotFound'

  /api/kernels/{kernel_id}/claim:
    post:
      summary: Claim a kernel_package tar.gz for optimization
      security: [{submitterAuth: []}]
      parameters:
        - name: kernel_id
          in: path
          required: true
          schema: {type: string}
          x-kernel-zoo-path-capture: true
      responses:
        '200':
          description: kernel_package tar.gz.
          content:
            application/gzip:
              schema: {type: string, format: binary}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409': {description: kernel is frozen.}

  /api/submissions:
    post:
      summary: Submit a kernel_package for benchmarking
      security: [{submitterAuth: []}]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [kernel_id, submitter_id, package]
              properties:
                kernel_id: {type: string}
                submitter_id: {type: string}
                optimization_summary: {type: string}
                package: {type: string, format: binary}
      responses:
        '200':
          description: Queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionAccepted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422': {description: Tarball malformed or envelope invalid.}

  /api/submissions/{uuid}/status:
    get:
      summary: Poll submission status (long-poll, default 30s)
      security: [{submitterAuth: []}]
      parameters:
        - name: uuid
          in: path
          required: true
          schema: {type: string, format: uuid}
        - in: query
          name: timeout
          schema: {type: integer, minimum: 0, maximum: 60, default: 30}
      responses:
        '200':
          description: Current status.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/SubmissionStatus'}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Lost.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionLost'

  /api/submissions/{uuid}/result:
    post:
      summary: Runner submits benchmark result
      security: [{runnerAuth: []}]
      parameters:
        - name: uuid
          in: path
          required: true
          schema: {type: string, format: uuid}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [bench_output, runner_logs_b64]
              properties:
                bench_output:
                  description: A document conforming to schemas/benchmark_output.json.
                  type: object
                runner_logs_b64: {type: string}
      responses:
        '200':
          description: Result accepted by server (may or may not be accepted into the repo).
          content:
            application/json:
              schema:
                type: object
                required: [server_accept]
                properties:
                  server_accept: {type: boolean}
                  commit_sha: {type: string, nullable: true}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422': {description: bench_output violates §3.3 hard constraints.}
        '503':
          $ref: '#/components/responses/GitFault'

  /api/edits/rebase:
    post:
      summary: Rebase a local branch onto main
      security: [{submitterAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/RebaseRequest'}
      responses:
        '200':
          description: Rebased and fast-forward merged.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/RebaseResponse'}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Conflicts.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/RebaseConflict'}
        '503':
          $ref: '#/components/responses/GitFault'

  /api/runner/register:
    post:
      summary: Runner registers its arch + capabilities
      security: [{runnerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [arch, capabilities, heartbeat_interval_s]
              properties:
                arch: {type: string}
                capabilities: {type: array, items: {type: string}}
                heartbeat_interval_s: {type: integer, minimum: 1}
      responses:
        '200':
          description: Registered.
          content:
            application/json:
              schema:
                type: object
                required: [runner_id, poll_interval_s, longpoll_timeout_s]
                properties:
                  runner_id: {type: string}
                  poll_interval_s: {type: integer}
                  longpoll_timeout_s: {type: integer}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403': {description: arch not in whitelist or key invalid.}

  /api/runner/claim:
    post:
      summary: Long-poll for a benchmark task
      security: [{runnerAuth: []}]
      parameters:
        - in: query
          name: timeout
          schema: {type: integer, minimum: 0, maximum: 60, default: 30}
      responses:
        '200':
          description: Task claimed.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/RunnerClaimResponse'}
        '204': {description: No task available within timeout.}
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/runner/heartbeat:
    post:
      summary: Refresh a claimed task's runner.lock
      security: [{runnerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [submission_uuid, stage]
              properties:
                submission_uuid: {type: string, format: uuid}
                stage: {enum: [build, bench]}
      responses:
        '200': {description: Heartbeat recorded.}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/health:
    get:
      summary: System health and queue depth
      security: []
      responses:
        '200':
          description: Current health.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'

  /api/index.json:
    get:
      summary: Pre-built WebUI index (static file)
      security: []
      responses:
        '200':
          description: WebUI index payload.
          content:
            application/json:
              schema: {type: object}