openapi.yaml

openapi: 3.1.0
info:
  title: Model Runtime API
  version: 0.1.0
  description: Provider-neutral AI model execution runtime. Pre-alpha contract.
servers:
  - url: http://127.0.0.1:4320
    description: Local unauthenticated reference server
paths:
  /v1/runtime:
    get:
      operationId: getRuntime
      responses:
        "200":
          description: Runtime metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeInfo"
  /v1/providers:
    get:
      operationId: listProviders
      responses:
        "200":
          description: Provider capability manifests
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ProviderManifest"
  /v1/executions:
    post:
      operationId: createExecution
      description: Accepts an execution for asynchronous processing.
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 256
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExecutionRequest"
      responses:
        "202":
          description: New execution accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecutionSubmission"
        "200":
          description: Idempotent replay of an existing execution
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecutionSubmission"
        "400":
          description: Invalid request
  /v1/executions/{executionId}:
    get:
      operationId: getExecution
      parameters:
        - $ref: "#/components/parameters/ExecutionId"
      responses:
        "200":
          description: Materialized execution state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecutionSnapshot"
        "404":
          description: Execution not found
  /v1/executions/{executionId}/events:
    get:
      operationId: streamExecutionEvents
      parameters:
        - $ref: "#/components/parameters/ExecutionId"
        - name: after
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
        - name: Last-Event-ID
          in: header
          required: false
          schema:
            type: integer
            minimum: 0
      responses:
        "200":
          description: Resumable SSE stream. Event IDs equal monotonic execution sequence values.
          content:
            text/event-stream:
              schema:
                type: string
        "404":
          description: Execution not found
  /v1/executions/{executionId}/result:
    get:
      operationId: getExecutionResult
      parameters:
        - $ref: "#/components/parameters/ExecutionId"
      responses:
        "200":
          description: Successful normalized result, artifacts, and usage facts
        "409":
          description: Execution has not succeeded
        "404":
          description: Execution not found
  /v1/executions/{executionId}/cancel:
    post:
      operationId: cancelExecution
      parameters:
        - $ref: "#/components/parameters/ExecutionId"
      responses:
        "202":
          description: Cancellation requested
        "404":
          description: Execution not found or already terminal
components:
  parameters:
    ExecutionId:
      name: executionId
      in: path
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    RuntimeInfo:
      type: object
      required: [name, protocol_version, provider_count, features]
      properties:
        name:
          const: model-runtime-api
        protocol_version:
          type: string
        provider_count:
          type: integer
          minimum: 0
        features:
          type: object
          required: [routing, flow_control, usage_facts, billing]
          properties:
            routing: { const: true }
            flow_control: { const: true }
            usage_facts: { const: true }
            billing: { const: false }
    ExecutionRequest:
      type: object
      required: [ability, input]
      additionalProperties: false
      properties:
        ability:
          type: string
          minLength: 1
        input:
          type: array
          minItems: 1
          items:
            type: object
            required: [type]
        requirements:
          type: object
          additionalProperties: false
          properties:
            input_modalities:
              type: array
              items: { type: string }
            output_modalities:
              type: array
              items: { type: string }
            stream: { type: boolean }
            tools: { type: boolean }
            structured_output: { type: boolean }
            async: { type: boolean }
            cancel: { type: boolean }
        routing:
          type: object
          additionalProperties: false
          properties:
            strategy:
              enum: [first_available, ordered]
            provider_order:
              type: array
              items: { type: string }
            allow_fallback: { type: boolean }
            max_attempts:
              type: integer
              minimum: 1
              maximum: 32
            retry_budget_ms:
              type: integer
              minimum: 1
              maximum: 86400000
        deadline_ms:
          type: number
          exclusiveMinimum: 0
        metadata:
          type: object
          additionalProperties:
            type: [string, number, boolean]
        extensions:
          type: object
          additionalProperties: true
    ExecutionSubmission:
      type: object
      required: [execution_id, status, created_at, idempotent_replay]
      properties:
        execution_id: { type: string, format: uuid }
        status: { $ref: "#/components/schemas/ExecutionStatus" }
        created_at: { type: string, format: date-time }
        idempotent_replay: { type: boolean }
    ExecutionSnapshot:
      type: object
      required: [execution_id, status, created_at, updated_at, last_sequence, usage]
      properties:
        execution_id: { type: string, format: uuid }
        status: { $ref: "#/components/schemas/ExecutionStatus" }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        last_sequence: { type: integer, minimum: 0 }
        result: {}
        artifacts:
          type: array
          items: { $ref: "#/components/schemas/OutputArtifact" }
        usage:
          type: array
          items: { $ref: "#/components/schemas/UsageFact" }
    ExecutionStatus:
      type: string
      enum: [accepted, routing, running, succeeded, failed, cancelled]
    OutputArtifact:
      type: object
      required: [uri]
      properties:
        uri: { type: string, format: uri }
        media_type: { type: string }
        name: { type: string }
        expires_at: { type: string, format: date-time }
    UsageFact:
      type: object
      required: [unit, quantity, source]
      properties:
        unit: { type: string }
        quantity: { type: number, minimum: 0 }
        source: { enum: [provider, runtime] }
        complete: { type: boolean }
    ProviderManifest:
      type: object
      required: [provider, protocol_version, models]
      properties:
        provider: { type: string }
        protocol_version: { type: string }
        models:
          type: array
          items:
            type: object
            required:
              - model
              - abilities
              - input_modalities
              - output_modalities
              - stream
              - tools
              - structured_output
              - async
              - cancel