fabro/openapi/arc-api.yaml

openapi: "3.1.0"
info:
  title: Arc Run API
  version: "0.1.0"
  description: HTTP API for managing Arc workflow run executions.

tags:
  - name: Runs
    description: Run management operations

paths:
  /runs:
    get:
      operationId: listRuns
      tags: [Runs]
      summary: List all runs
      responses:
        "200":
          description: Array of run statuses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/RunStatusResponse"
    post:
      operationId: startRun
      tags: [Runs]
      summary: Start a new run
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StartRunRequest"
      responses:
        "201":
          description: Run created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StartRunResponse"
        "400":
          description: Invalid DOT source
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /runs/{id}:
    get:
      operationId: getRunStatus
      tags: [Runs]
      summary: Get run status
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Run status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunStatusResponse"
        "404":
          description: Run not found

  /runs/{id}/cancel:
    post:
      operationId: cancelRun
      tags: [Runs]
      summary: Cancel a running run
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Run cancelled
          content:
            application/json:
              schema:
                type: object
                properties:
                  cancelled:
                    type: boolean
                required:
                  - cancelled
        "404":
          description: Run not found
        "409":
          description: Run is not running
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /runs/{id}/graph:
    get:
      operationId: getGraph
      tags: [Runs]
      summary: Get run graph as SVG
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: SVG image of the workflow graph
          content:
            image/svg+xml:
              schema:
                type: string
        "404":
          description: Run not found
        "502":
          description: Graphviz not available
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /runs/{id}/checkpoint:
    get:
      operationId: getCheckpoint
      tags: [Runs]
      summary: Get run checkpoint
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Checkpoint data (null if not yet available)
          content:
            application/json:
              schema: {}
        "404":
          description: Run not found

  /runs/{id}/context:
    get:
      operationId: getContext
      tags: [Runs]
      summary: Get run context
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Context key-value map
          content:
            application/json:
              schema:
                type: object
        "404":
          description: Run not found

  /runs/{id}/events:
    get:
      operationId: getEvents
      tags: [Runs]
      summary: Subscribe to run events via SSE
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Server-sent event stream
          content:
            text/event-stream:
              schema:
                type: string
        "404":
          description: Run not found
        "410":
          description: Event stream closed

  /runs/{id}/questions:
    get:
      operationId: getQuestions
      tags: [Runs]
      summary: Get pending questions for a run
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Array of pending questions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiQuestion"
        "404":
          description: Run not found

  /runs/{id}/questions/{qid}/answer:
    post:
      operationId: submitAnswer
      tags: [Runs]
      summary: Submit an answer to a question
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: qid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SubmitAnswerRequest"
      responses:
        "200":
          description: Answer accepted or rejected
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubmitAnswerResponse"
        "400":
          description: Invalid option key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Run not found

  /runs/{id}/retro:
    get:
      operationId: getRetro
      tags: [Runs]
      summary: Get run retrospective
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Retro data (null if not yet available)
          content:
            application/json:
              schema: {}
        "404":
          description: Run not found

components:
  schemas:
    RunStatus:
      type: string
      enum:
        - running
        - completed
        - failed
        - cancelled

    StartRunRequest:
      type: object
      required:
        - dot_source
      properties:
        dot_source:
          type: string

    StartRunResponse:
      type: object
      required:
        - id
      properties:
        id:
          type: string

    RunStatusResponse:
      type: object
      required:
        - id
        - status
      properties:
        id:
          type: string
        status:
          $ref: "#/components/schemas/RunStatus"
        error:
          type: string

    ApiQuestionOption:
      type: object
      required:
        - key
        - label
      properties:
        key:
          type: string
        label:
          type: string

    ApiQuestion:
      type: object
      required:
        - id
        - text
        - question_type
        - options
        - allow_freeform
      properties:
        id:
          type: string
        text:
          type: string
        question_type:
          type: string
        options:
          type: array
          items:
            $ref: "#/components/schemas/ApiQuestionOption"
        allow_freeform:
          type: boolean

    SubmitAnswerRequest:
      type: object
      required:
        - value
      properties:
        value:
          type: string
        selected_option_key:
          type: string

    SubmitAnswerResponse:
      type: object
      required:
        - accepted
      properties:
        accepted:
          type: boolean

    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string