evotown-engine-ingest-v0.1.yaml

openapi: 3.0.3
info:
  title: Evotown Engine Ingest API
  version: "0.1.0"
  description: >
    Draft v0.1 — Evotown is the system of record. Independent engines POST run completion
    and optional artifacts. Normative prose: docs/en/EVOTOWN-ENGINE-INGEST-V0.1.md (canonical in this repo).
servers:
  - url: https://{evotown-host}/api/v1
    variables:
      evotown-host:
        default: evotown.example
tags:
  - name: engines
  - name: runs
paths:
  /engines/register:
    post:
      tags: [engines]
      summary: Register or update an engine record
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EngineRegister"
      responses:
        "200":
          description: Registered
          content:
            application/json:
              schema:
                type: object
                required: [registered, engine]
                properties:
                  registered:
                    type: boolean
                  engine:
                    $ref: "#/components/schemas/Engine"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/Unprocessable"
  /engines:
    get:
      tags: [engines]
      summary: List registered engines
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 500
      responses:
        "200":
          description: Engines
          content:
            application/json:
              schema:
                type: object
                required: [engines]
                properties:
                  engines:
                    type: array
                    items:
                      $ref: "#/components/schemas/Engine"
  /runs/lease:
    post:
      tags: [runs]
      summary: Lease one run job (optional pull model)
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Job leased
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunLease"
        "204":
          description: No work available
        "401":
          $ref: "#/components/responses/Unauthorized"
  /runs/{run_id}/complete:
    post:
      tags: [runs]
      summary: Finalize a run (MVP required ingest)
      security:
        - bearerAuth: []
      parameters:
        - name: run_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RunComplete"
      responses:
        "200":
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                required: [accepted, idempotent, run_id, run]
                properties:
                  accepted:
                    type: boolean
                  idempotent:
                    type: boolean
                  run_id:
                    type: string
                  run:
                    $ref: "#/components/schemas/Run"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          description: Run already terminal (idempotency)
        "413":
          description: Payload too large
        "422":
          $ref: "#/components/responses/Unprocessable"
  /runs:
    get:
      tags: [runs]
      summary: List external runs
      parameters:
        - name: engine_id
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 500
      responses:
        "200":
          description: Runs
          content:
            application/json:
              schema:
                type: object
                required: [runs]
                properties:
                  runs:
                    type: array
                    items:
                      $ref: "#/components/schemas/Run"
  /runs/{run_id}:
    get:
      tags: [runs]
      summary: Get one external run
      parameters:
        - name: run_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Run
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Run"
        "404":
          description: Run not found
  /events:
    post:
      tags: [runs]
      summary: Ingest a runtime-neutral run event
      description: >
        Preferred live ingest endpoint for run.started, run.progress, and run.completed.
        Lifecycle events may create or update the run summary before terminal completion.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RunEventIngest"
      responses:
        "200":
          description: Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunEventAccepted"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/Unprocessable"
  /runs/{run_id}/events:
    post:
      tags: [runs]
      summary: Ingest a run event scoped by path run_id
      security:
        - bearerAuth: []
      parameters:
        - name: run_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RunEventIngest"
      responses:
        "200":
          description: Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunEventAccepted"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/Unprocessable"
    get:
      tags: [runs]
      summary: List events for one run
      parameters:
        - name: run_id
          in: path
          required: true
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 500
            minimum: 1
            maximum: 2000
      responses:
        "200":
          description: Run events
          content:
            application/json:
              schema:
                type: object
                required: [events]
                properties:
                  events:
                    type: array
                    items:
                      $ref: "#/components/schemas/RunEvent"
        "404":
          description: Run not found
  /runs/{run_id}/artifacts:
    post:
      tags: [runs]
      summary: Upload large artifact chunk (optional)
      security:
        - bearerAuth: []
      parameters:
        - name: run_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "204":
          description: Chunk stored
        "401":
          $ref: "#/components/responses/Unauthorized"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Evotown-issued engine token
  responses:
    Unauthorized:
      description: Missing or invalid auth
    Unprocessable:
      description: Validation failed
  schemas:
    EngineRegister:
      type: object
      required: [engine_id, engine_version]
      properties:
        engine_id:
          type: string
        engine_type:
          type: string
          enum: [openclaw, hermes, skilllite, custom]
          default: custom
        engine_version:
          type: string
        display_name:
          type: string
        owner_team:
          type: string
        deployment_kind:
          type: string
          enum: [laptop, server, ci, container]
          default: server
        dispatch_url:
          type: string
          format: uri
        capabilities:
          type: object
          additionalProperties: true
    Engine:
      allOf:
        - $ref: "#/components/schemas/EngineRegister"
        - type: object
          properties:
            registered_at:
              type: string
            updated_at:
              type: string
    RunLease:
      type: object
      required: [run_id, callback_base, payload]
      properties:
        run_id:
          type: string
        callback_base:
          type: string
          format: uri
          description: >
            Evotown API prefix including /api/v1 (no trailing slash).
            Client POSTs to {callback_base}/runs/{run_id}/complete
        payload:
          type: object
          additionalProperties: true
    ArtifactManifestItem:
      type: object
      required: [path, sha256, bytes]
      properties:
        path:
          type: string
        sha256:
          type: string
          pattern: "^[a-f0-9]{64}$"
        bytes:
          type: integer
          minimum: 0
    RunComplete:
      type: object
      required:
        - engine_id
        - engine_version
        - status
        - exit_code
        - finished_at
      properties:
        engine_id:
          type: string
        engine_version:
          type: string
        status:
          type: string
          enum: [succeeded, failed, cancelled]
        exit_code:
          type: integer
        finished_at:
          type: string
          format: date-time
        log_excerpt:
          type: string
        artifact_manifest:
          type: array
          items:
            $ref: "#/components/schemas/ArtifactManifestItem"
        artifact_bundle_url:
          type: string
          format: uri
        signals:
          type: object
          additionalProperties: true
    Run:
      type: object
      required: [run_id, engine_id, engine_version, status, exit_code, finished_at, accepted_at]
      properties:
        run_id:
          type: string
        engine_id:
          type: string
        engine_type:
          type: string
          enum: [openclaw, hermes, skilllite, custom]
        engine_version:
          type: string
        tenant_id:
          type: string
        team_id:
          type: string
        agent_id:
          type: string
        task_id:
          type: string
        status:
          type: string
          enum: [running, succeeded, failed, cancelled]
        exit_code:
          type: integer
        started_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
        log_excerpt:
          type: string
        artifact_manifest:
          type: array
          items:
            $ref: "#/components/schemas/ArtifactManifestItem"
        artifact_bundle_url:
          type: string
          format: uri
        signals:
          type: object
          additionalProperties: true
        accepted_at:
          type: string
        updated_at:
          type: string
    RunEventIngest:
      type: object
      required: [event_type, run_id, engine_id, ts]
      properties:
        event_type:
          type: string
          enum:
            - run.started
            - run.progress
            - run.completed
            - run_started
            - step_started
            - user_message
            - assistant_message
            - tool_call
            - tool_result
            - model_call
            - artifact_written
            - policy_violation
            - run_finished
        run_id:
          type: string
        tenant_id:
          type: string
        team_id:
          type: string
        agent_id:
          type: string
        engine_id:
          type: string
        engine_type:
          type: string
          enum: [openclaw, hermes, skilllite, custom]
        engine_version:
          type: string
        task_id:
          type: string
        status:
          type: string
          enum: [running, succeeded, failed, cancelled]
        ts:
          type: string
          format: date-time
        seq:
          type: integer
          default: 0
          minimum: 0
        exit_code:
          type: integer
        log_excerpt:
          type: string
        artifact_manifest:
          type: array
          items:
            $ref: "#/components/schemas/ArtifactManifestItem"
        artifact_bundle_url:
          type: string
          format: uri
        signals:
          type: object
          additionalProperties: true
        payload:
          type: object
          additionalProperties: true
      example:
        event_type: run.started
        run_id: xxx
        tenant_id: company-a
        team_id: growth-team
        agent_id: agent-001
        engine_id: skilllite-local
        engine_type: skilllite
        engine_version: 0.1.29
        task_id: task-xxx
        status: running
        ts: "2026-05-25T09:00:00Z"
        signals: {}
    RunEvent:
      allOf:
        - $ref: "#/components/schemas/RunEventIngest"
        - type: object
          required: [id, accepted_at]
          properties:
            id:
              type: integer
            accepted_at:
              type: string
    RunEventAccepted:
      type: object
      required: [accepted, event]
      properties:
        accepted:
          type: boolean
        event:
          $ref: "#/components/schemas/RunEvent"
        run:
          $ref: "#/components/schemas/Run"