Eigenpal Runs API

openapi: 3.1.0
info:
  title: Eigenpal Automations Runs API
  version: 1.0.0
  description: Public REST API for inspecting automations, starting and monitoring runs, managing files, collecting human reviews, and running evaluations.
  contact:
    name: Eigenpal
    url: https://eigenpal.com
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://studio.eigenpal.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Runs
  description: Start, monitor, retry, review, and debug automation runs, including artifacts.
paths:
  /api/v1/runs:
    get:
      operationId: runs.list
      summary: List runs
      description: List workflow and agent runs with cursor pagination.
      tags:
      - Runs
      parameters:
      - in: query
        name: type
        schema:
          type: string
      - in: query
        name: source
        schema:
          type: string
      - in: query
        name: status
        schema:
          type: string
      - in: query
        name: trigger
        schema:
          type: string
      - in: query
        name: triggeredBy
        schema:
          type: string
      - in: query
        name: sourceRef
        schema:
          type: string
      - in: query
        name: batchId
        schema:
          type: string
      - in: query
        name: exampleId
        schema:
          type: string
      - in: query
        name: exampleIdContains
        schema:
          type: string
      - in: query
        name: from
        schema:
          type: string
      - in: query
        name: to
        schema:
          type: string
      - in: query
        name: createdAfter
        schema:
          type: string
      - in: query
        name: createdBefore
        schema:
          type: string
      - in: query
        name: completedAfter
        schema:
          type: string
      - in: query
        name: completedBefore
        schema:
          type: string
      - in: query
        name: cursor
        schema:
          type: string
      - in: query
        name: offset
        schema:
          type: integer
          minimum: 0
          maximum: 9007199254740991
      - in: query
        name: limit
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - in: query
        name: ids
        schema:
          type: string
      - in: query
        name: experiments
        schema:
          type: string
      - in: query
        name: sort
        schema:
          type: string
      - in: query
        name: order
        schema:
          type: string
      - in: query
        name: reviewStatus
        schema:
          type: string
      - in: query
        name: reviewVerdict
        schema:
          type: string
      - in: query
        name: hasReview
        schema:
          type: string
      - in: query
        name: noReview
        schema:
          type: string
      - in: query
        name: hasCorrections
        schema:
          type: string
      - in: query
        name: reviewNoteContains
        schema:
          type: string
      - in: query
        name: reviewCreatedAfter
        schema:
          type: string
      - in: query
        name: reviewCreatedBefore
        schema:
          type: string
      - in: query
        name: reviewUpdatedAfter
        schema:
          type: string
      - in: query
        name: reviewUpdatedBefore
        schema:
          type: string
      - in: query
        name: reviewClosedAfter
        schema:
          type: string
      - in: query
        name: reviewClosedBefore
        schema:
          type: string
      - in: query
        name: sinceLastClosed
        schema:
          type: string
      - in: query
        name: sampleRate
        schema:
          description: Keep runs whose `sampleRank` is below this threshold (0–1). Pages may return fewer than `limit` rows when filtered.
          type: string
        description: Keep runs whose `sampleRank` is below this threshold (0–1). Pages may return fewer than `limit` rows when filtered.
      responses:
        '200':
          description: Runs page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunsListResponse'
        '400':
          description: Validation error. Request shape did not match the spec.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: API key lacks required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '413':
          description: Payload too large. Upload exceeded the per-request size cap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: Seconds until the next request may succeed
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
    post:
      operationId: runs.start
      summary: Start a run
      description: Start a run. Send JSON or multipart/form-data.
      tags:
      - Runs
      parameters:
      - in: query
        name: version
        schema:
          description: Release or git ref. Defaults to latest.
          type: string
          minLength: 1
        description: Release or git ref. Defaults to latest.
      - in: query
        name: wait_for_completion
        schema:
          description: Seconds to wait before returning (max 600). Omit for async.
          type: integer
          minimum: 0
          maximum: 600
        description: Seconds to wait before returning (max 600). Omit for async.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunStartBody'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/RunStartMultipartRequest'
      responses:
        '200':
          description: Run completed while waiting — same body as GET /api/v1/runs/:id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunStartResponse'
        '201':
          description: Run accepted (async)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunStartResponse'
        '202':
          description: Wait expired with a non-terminal status — poll GET /api/v1/runs/:id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunStartResponse'
        '400':
          description: Validation error. Request shape did not match the spec.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: Trigger disabled or insufficient scope. Run start may return api_trigger_disabled when the API trigger is off, or manual_trigger_disabled for dashboard runs on API-only workflows.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '413':
          description: Payload too large. Upload exceeded the per-request size cap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: Seconds until the next request may succeed
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
  /api/v1/runs/{id}:
    get:
      operationId: runs.get
      summary: Get a run
      description: Fetch one run by id. By default this returns core metadata plus terminal output/error fields. Pass `?expand=input,usage,execution,debug` to include detailed sub-objects; `expand=execution` is also where embedded review and expected artifacts appear.
      tags:
      - Runs
      parameters:
      - in: path
        name: id
        schema:
          type: string
          description: Run id
        required: true
        description: Run id
      - in: query
        name: expand
        schema:
          description: 'Optional sections: `input`, `usage`, `execution`, `debug`. Terminal runs always include top-level output, files, and error.'
          type: string
        description: 'Optional sections: `input`, `usage`, `execution`, `debug`. Terminal runs always include top-level output, files, and error.'
      responses:
        '200':
          description: Run detail. Expanded sections appear only when requested.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'
        '400':
          description: Validation error. Request shape did not match the spec.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: API key lacks required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '413':
          description: Payload too large. Upload exceeded the per-request size cap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: Seconds until the next request may succeed
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
  /api/v1/runs/{id}/artifacts:
    get:
      operationId: runs.artifacts.list
      summary: List run artifacts
      description: Returns a JSON list of downloadable artifact paths for a run. Pass `zip=1` to switch the response to a ZIP download containing output files.
      tags:
      - Runs
      parameters:
      - in: path
        name: id
        schema:
          type: string
          description: Run id
        required: true
        description: Run id
      - in: query
        name: zip
        schema:
          description: When `1`, download output files as a ZIP instead of listing paths. Does not include trace, scores, or input — use `GET /runs/{id}/scores` and `GET /runs/{id}/trace` for those.
          type: string
          enum:
          - '1'
        description: When `1`, download output files as a ZIP instead of listing paths. Does not include trace, scores, or input — use `GET /runs/{id}/scores` and `GET /runs/{id}/trace` for those.
      - in: query
        name: bundle
        schema:
          description: With `zip=1`, use `review` to download a ZIP with `output/` and `expected/` folders (corrected review artifacts).
          type: string
          enum:
          - review
        description: With `zip=1`, use `review` to download a ZIP with `output/` and `expected/` folders (corrected review artifacts).
      - in: query
        name: token
        schema:
          description: Signed email download token (zip only; no Bearer required).
          type: string
        description: Signed email download token (zip only; no Bearer required).
      responses:
        '200':
          description: JSON artifact list, or ZIP bytes when `zip=1`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunArtifactsResponse'
            application/octet-stream:
              schema:
                type: string
                description: ZIP archive
                format: binary
        '400':
          description: Validation error. Request shape did not match the spec.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: API key lacks required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '413':
          description: Payload too large. Upload exceeded the per-request size cap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: Seconds until the next request may succeed
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
  /api/v1/runs/{id}/artifacts/{path}:
    get:
      operationId: runs.artifacts.get
      summary: Download run artifact
      description: Download one artifact by path.
      tags:
      - Runs
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      - in: path
        name: path
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Run artifact
        '400':
          description: Validation error. Request shape did not match the spec.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: API key lacks required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '413':
          description: Payload too large. Upload exceeded the per-request size cap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: Seconds until the next request may succeed
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
  /api/v1/runs/{id}/cancel:
    post:
      operationId: runs.cancel
      summary: Cancel run
      description: Cancel a queued run or request cancellation of an in-flight run.
      tags:
      - Runs
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Cancellation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunCancelResponse'
        '400':
          description: Validation error. Request shape did not match the spec.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: API key lacks required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '413':
          description: Payload too large. Upload exceeded the per-request size cap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: Seconds until the next request may succeed
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
  /api/v1/runs/{id}/events:
    get:
      operationId: runs.events.list
      summary: List run events
      description: List a stable chronological lifecycle timeline for a run.
      tags:
      - Runs
      parameters:
      - in: path
        name: id
        schema:
          type: string
          description: Run id
        required: true
        description: Run id
      responses:
        '200':
          description: Run events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunEventsResponse'
        '400':
          description: Validation error. Request shape did not match the spec.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: API key lacks required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '413':
          description: Payload too large. Upload exceeded the per-request size cap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: Seconds until the next request may succeed
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
  /api/v1/runs/{id}/rerun:
    post:
      operationId: runs.rerun
      summary: Retry run
      description: Start a new run using the source run input. By default the retry uses the latest automation version; pass `version=original` to pin the same source version as the original run.
      tags:
      - Runs
      parameters:
      - in: path
        name: id
        schema:
          type: string
          description: Source run id to retry.
        required: true
        description: Source run id to retry.
      - in: query
        name: version
        schema:
          description: Version for the new run. `original` pins the source run. Defaults to latest.
          type: string
        description: Version for the new run. `original` pins the source run. Defaults to latest.
      - in: query
        name: wait_for_completion
        schema:
          description: Seconds to wait before returning (max 600). Omit for async.
          type: integer
          minimum: 0
          maximum: 600
        description: Seconds to wait before returning (max 600). Omit for async.
      responses:
        '200':
          description: Rerun completed while waiting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunRerunResponse'
        '201':
          description: Rerun accepted (async)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunRerunResponse'
        '202':
          description: Wait expired with a non-terminal status — poll GET /api/v1/runs/:id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunRerunResponse'
        '400':
          description: Validation error. Request shape did not match the spec.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: API key lacks required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '413':
          description: Payload too large. Upload exceeded the per-request size cap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: Seconds until the next request may succeed
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
  /api/v1/runs/{id}/steps:
    get:
      operationId: runs.steps.list
      summary: List run steps
      description: List workflow steps or an agent-compatible execution step summary for a run.
      tags:
      - Runs
      parameters:
      - in: path
        name: id
        schema:
          type: string
          description: Run id
        required: true
        description: Run id
      responses:
        '200':
          description: Run steps
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunStepsResponse'
        '400':
          description: Validation error. Request shape did not match the spec.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: API key lacks required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '413':
          description: Payload too large. Upload exceeded the per-request size cap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: Seconds until the next request may succeed
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
  /api/v1/runs/{id}/trace:
    get:
      operationId: runs.trace.get
      summary: Get run trace
      description: Return low-level execution trace events for debugging one run. Workflow runs expose observability phases or step records; agent runs expose parsed trace.jsonl events. The shape is intentionally extensible, but common fields are documented.
      tags:
      - Runs
      parameters:
      - in: path
        name: id
        schema:
          type: string
          description: Run id.
        required: true
        description: Run id.
      responses:
        '200':
          description: Run trace events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunTraceResponse'
        '400':
          description: Validation error. Request shape did not match the spec.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: API key lacks required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '413':
          description: Payload too large. Upload exceeded the per-request size cap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: Seconds until the next request may succeed
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
  /api/v1/runs/{id}/usage:
    get:
      operationId: runs.usage.get
      summary: Get run usage
      description: Get token, credit, duration, and execution usage for a run.
      tags:
      - Runs
      parameters:
      - in: path
        name: id
        schema:
          type: string
          description: Run id
        required: true
        description: Run id
      responses:
        '200':
          description: Run usage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunUsageResponse'
        '400':
          description: Validation error. Request shape did not match the spec.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '403':
          description: API key lacks required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '413':
          description: Payload too large. Upload exceeded the per-request size cap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: Seconds until the next request may succeed
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelope'
components:
  schemas:
    RunsListResponse:
      type: object
      properties:
        runs:
          type: array
          items:
            $ref: '#/components/schemas/RunListItem'
        nextCursor:
          anyOf:
          - type: string
          - type: 'null'
      required:
      - runs
      - nextCursor
      additionalProperties: false
    RunTraceResponse:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/RunTraceEvent'
          description: Chronological trace events. Workflow runs return observability phases or step

# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/eigenpal/refs/heads/main/openapi/eigenpal-runs-api-openapi.yml