scriptoriumadmin/fabro
1
0
Fork 0
mirror of https://github.com/fabro-sh/fabro.git synced 2026-09-05 08:10:39 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10
fabro/docs/api-reference/fabro-api.yaml
Bryan Helmkamp 87bc42be70 refactor(interview): move run answers onto control channels 
Persist pending interviews in run state, deliver accepted answers to workers
through the server-owned control path, and remove the old scratch-file and
WebInterviewer transports.

This also moves Slack onto the canonical server answer flow, adds richer
question metadata to the API and run events, and covers the subprocess
question lifecycle with end-to-end tests.
2026-04-07 19:23:36 -04:00

4978 lines
141 KiB
YAML
Raw Blame History

openapi: "3.1.0"
info:
title: Fabro Run API
version: "0.1.0"
description: HTTP API for managing Fabro workflow run executions.
tags:
- name: Discovery
description: API discovery and health
- name: Runs
description: Run management operations
- name: Human-in-the-Loop
description: Questions, answers, and steering for runs
- name: Run Outputs
description: Files produced by runs
- name: Run Internals
description: Internal run details (stages, turns, context, configuration)
- name: Workflows
description: Workflow definitions and execution
- name: Billing
description: Token counts and billed totals
- name: Insights
description: SQL query editor and history
- name: Models
description: Available LLM models
- name: Completions
description: Single-turn LLM completions
- name: Settings
description: Platform configuration
- name: System
description: Server runtime, maintenance, and event streaming
security:
- BearerAuth: []
- mTLS: []
paths:
# ── Discovery ────────────────────────────────────────────────────────
/:
get:
operationId: getRoot
tags: [Discovery]
summary: API Discovery
description: Returns discovery URLs for the API.
security: []
responses:
"200":
description: Discovery URLs
content:
application/json:
schema:
$ref: "#/components/schemas/RootResponse"
/health:
get:
operationId: getHealth
tags: [Discovery]
summary: Health Check
description: Returns service health status. Used by load balancers and monitoring.
security: []
responses:
"200":
description: Service is healthy
content:
application/json:
schema:
$ref: "#/components/schemas/HealthResponse"
/api/v1/health/diagnostics:
post:
operationId: runDiagnostics
tags: [Discovery]
summary: Run server health diagnostics
description: Probes external services and server configuration. May be slow.
responses:
"200":
description: Diagnostics report
content:
application/json:
schema:
$ref: "#/components/schemas/DiagnosticsReport"
/api/v1/openapi.json:
get:
operationId: getOpenApiSpec
tags: [Discovery]
summary: OpenAPI Specification
description: Returns the OpenAPI spec as JSON.
security: []
responses:
"200":
description: OpenAPI specification
content:
application/json:
schema:
type: object
/api/v1/user:
get:
operationId: getUser
tags: [Discovery]
summary: Current User
description: Returns info about the authenticated user.
responses:
"200":
description: User info
content:
application/json:
schema:
$ref: "#/components/schemas/UserResponse"
"401":
description: Not authenticated
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
# ── Runs ──────────────────────────────────────────────────────────────
/api/v1/runs:
get:
operationId: listRuns
tags: [Runs]
summary: List Runs
description: Returns durable run summaries from the backing store, including runs persisted before the current server boot.
responses:
"200":
description: Durable run summaries
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/StoreRunSummary"
post:
operationId: createRun
tags: [Runs]
summary: Create Run
description: Creates a new workflow run in `submitted` status from a self-contained manifest.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/RunManifest"
responses:
"201":
description: Run created
content:
application/json:
schema:
$ref: "#/components/schemas/RunStatusResponse"
"400":
description: Invalid Graphviz source
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/preflight:
post:
operationId: runPreflight
tags: [Runs]
summary: Validate Workflow Manifest
description: Validates a workflow manifest without creating a run.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/RunManifest"
responses:
"200":
description: Preflight report
content:
application/json:
schema:
$ref: "#/components/schemas/PreflightResponse"
"400":
description: Invalid manifest or workflow
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/graph/render:
post:
operationId: renderWorkflowGraph
tags: [Runs]
summary: Render Workflow Graph
description: Validates and renders a workflow manifest as SVG or PNG without creating a run.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/RenderWorkflowGraphRequest"
responses:
"200":
description: Rendered graph image
content:
image/svg+xml:
schema:
type: string
format: binary
image/png:
schema:
type: string
format: binary
"400":
description: Invalid manifest or workflow
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"502":
description: Graphviz rendering failed
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}:
get:
operationId: retrieveRun
tags: [Runs]
summary: Retrieve Run
description: Returns the durable run summary for a run.
parameters:
- $ref: "#/components/parameters/RunId"
responses:
"200":
description: Durable run summary
content:
application/json:
schema:
$ref: "#/components/schemas/StoreRunSummary"
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
delete:
operationId: deleteRun
tags: [Runs]
summary: Delete Run
description: Deletes durable store state for a run. This does not remove any local run directory.
parameters:
- $ref: "#/components/parameters/RunId"
responses:
"204":
description: Run deleted or already absent
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/cancel:
post:
operationId: cancelRun
tags: [Runs]
summary: Cancel Run
description: Cancels a running or queued run. Returns 409 if the run has already completed or been cancelled.
parameters:
- $ref: "#/components/parameters/RunId"
responses:
"200":
description: Run cancelled
content:
application/json:
schema:
$ref: "#/components/schemas/RunStatusResponse"
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"409":
description: Run is not running
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/start:
post:
operationId: startRun
tags: [Runs]
summary: Start Run
description: Starts a submitted run, queuing it for execution. Provide `resume=true` to resume an interrupted run from checkpoint. Returns 409 if the run is not startable.
parameters:
- $ref: "#/components/parameters/RunId"
requestBody:
required: false
content:
application/json:
schema:
$ref: "#/components/schemas/StartRunRequest"
responses:
"200":
description: Run started
content:
application/json:
schema:
$ref: "#/components/schemas/RunStatusResponse"
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"409":
description: Run is not in submitted status
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/pause:
post:
operationId: pauseRun
tags: [Runs]
summary: Pause Run
description: Pauses a running run. Returns 409 if the run is not running.
parameters:
- $ref: "#/components/parameters/RunId"
responses:
"200":
description: Run paused
content:
application/json:
schema:
$ref: "#/components/schemas/RunStatusResponse"
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"409":
description: Run is not running
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/unpause:
post:
operationId: unpauseRun
tags: [Runs]
summary: Unpause Run
description: Resumes a paused run. Returns 409 if the run is not paused.
parameters:
- $ref: "#/components/parameters/RunId"
responses:
"200":
description: Run unpaused
content:
application/json:
schema:
$ref: "#/components/schemas/RunStatusResponse"
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"409":
description: Run is not paused
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/graph:
get:
operationId: retrieveRunGraph
tags: [Runs]
summary: Render SVG
description: Renders the workflow graph as an SVG image using Graphviz.
parameters:
- $ref: "#/components/parameters/RunId"
responses:
"200":
description: SVG image of the workflow graph
content:
image/svg+xml:
schema:
type: string
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"502":
description: Graphviz not available
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/checkpoint:
get:
operationId: retrieveRunCheckpoint
tags: [Run Internals]
summary: Retrieve Run Checkpoint
description: Returns the latest checkpoint data for a run, or null if no checkpoint has been recorded yet.
parameters:
- $ref: "#/components/parameters/RunId"
responses:
"200":
description: Checkpoint data (null if not yet available)
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/RunCheckpoint"
- type: "null"
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/boards/runs:
get:
operationId: listBoardRuns
tags: [Runs]
summary: List Board Runs
description: Temporary board-view list of managed runs. This endpoint is UI-oriented and may change as the app evolves.
parameters:
- $ref: "#/components/parameters/PageLimit"
- $ref: "#/components/parameters/PageOffset"
responses:
"200":
description: Paginated list of runs for the board view
content:
application/json:
schema:
$ref: "#/components/schemas/PaginatedRunList"
/api/v1/runs/{id}/state:
get:
operationId: getRunState
tags: [Run Internals]
summary: Get Run State
description: Returns the internal event-sourced run projection. This is not a stable public contract.
parameters:
- $ref: "#/components/parameters/RunId"
responses:
"200":
description: Current run projection
content:
application/json:
schema:
$ref: "#/components/schemas/RunProjection"
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/events:
get:
operationId: listRunEvents
tags: [Run Internals]
summary: List Run Events
description: Returns a paginated JSON list of stored run events.
parameters:
- $ref: "#/components/parameters/RunId"
- $ref: "#/components/parameters/SinceSeq"
- $ref: "#/components/parameters/EventLimit"
responses:
"200":
description: Paginated list of run events
content:
application/json:
schema:
$ref: "#/components/schemas/PaginatedEventList"
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
post:
operationId: appendRunEvent
tags: [Run Internals]
summary: Append Run Event
description: Appends a validated event to the run event log. Intended for trusted internal callers.
parameters:
- $ref: "#/components/parameters/RunId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/RunEvent"
responses:
"200":
description: Event appended
content:
application/json:
schema:
$ref: "#/components/schemas/AppendEventResponse"
"400":
description: Invalid event payload
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/attach:
get:
operationId: attachRunEvents
tags: [Run Internals]
summary: Attach Run Events
description: Opens an ordered server-sent event stream starting at `since_seq`, replaying persisted events and continuing with live updates while the run remains active.
parameters:
- $ref: "#/components/parameters/RunId"
- $ref: "#/components/parameters/SinceSeq"
responses:
"200":
description: Server-sent event stream
content:
text/event-stream:
schema:
type: string
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/blobs:
post:
operationId: writeRunBlob
tags: [Run Internals]
summary: Write Run Blob
description: Writes an opaque binary blob and returns its content-addressed blob identifier.
parameters:
- $ref: "#/components/parameters/RunId"
requestBody:
required: true
content:
application/octet-stream:
schema:
type: string
format: binary
multipart/form-data:
schema:
type: object
required:
- manifest
properties:
manifest:
$ref: "#/components/schemas/ArtifactBatchUploadManifest"
additionalProperties:
type: string
format: binary
description: |
Strict multipart upload format. The `manifest` part must arrive first with JSON
matching `ArtifactBatchUploadManifest`. Each subsequent file part name must match
a manifest entry `part` value.
encoding:
manifest:
contentType: application/json
responses:
"200":
description: Blob written
content:
application/json:
schema:
$ref: "#/components/schemas/WriteBlobResponse"
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/blobs/{blobId}:
get:
operationId: readRunBlob
tags: [Run Internals]
summary: Read Run Blob
description: Reads a previously stored blob by identifier.
parameters:
- $ref: "#/components/parameters/RunId"
- $ref: "#/components/parameters/BlobId"
responses:
"200":
description: Blob contents
content:
application/octet-stream:
schema:
type: string
format: binary
"404":
description: Run or blob not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/questions:
get:
operationId: listRunQuestions
tags: [Human-in-the-Loop]
summary: List Run Questions
description: Returns pending human-in-the-loop questions for a run. Questions are generated when the workflow needs user input to proceed.
parameters:
- $ref: "#/components/parameters/RunId"
- $ref: "#/components/parameters/PageLimit"
- $ref: "#/components/parameters/PageOffset"
responses:
"200":
description: Array of pending questions
content:
application/json:
schema:
$ref: "#/components/schemas/PaginatedApiQuestionList"
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/questions/{qid}/answer:
post:
operationId: submitRunAnswer
tags: [Human-in-the-Loop]
summary: Submit Run Answer
description: Submits an answer to a pending question. The answer can be freeform text or a selected option key, depending on the question type.
parameters:
- $ref: "#/components/parameters/RunId"
- $ref: "#/components/parameters/QuestionId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SubmitAnswerRequest"
responses:
"204":
description: Answer accepted
"400":
description: Invalid option key
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"409":
description: Question no longer exists or already answered
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/stages:
get:
operationId: listRunStages
tags: [Run Internals]
summary: List Run Stages
description: Returns the ordered list of stages in a run's workflow graph with their current status and timing. Stages are bounded by the workflow graph size, typically fewer than 20.
parameters:
- $ref: "#/components/parameters/RunId"
- $ref: "#/components/parameters/PageLimit"
- $ref: "#/components/parameters/PageOffset"
responses:
"200":
description: Array of run stages
content:
application/json:
schema:
$ref: "#/components/schemas/PaginatedRunStageList"
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/stages/{stageId}/turns:
get:
operationId: listStageTurns
tags: [Run Internals]
summary: List Stage Turns
description: Returns a paginated list of conversation turns within a specific stage, including system prompts, assistant responses, and tool invocations.
parameters:
- $ref: "#/components/parameters/RunId"
- $ref: "#/components/parameters/StageId"
- $ref: "#/components/parameters/PageLimit"
- $ref: "#/components/parameters/PageOffset"
responses:
"200":
description: Paginated list of conversation turns
content:
application/json:
schema:
$ref: "#/components/schemas/PaginatedStageTurnList"
"404":
description: Run or stage not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/artifacts:
get:
operationId: listRunArtifacts
tags: [Run Internals]
summary: List Run Artifacts
description: Lists captured artifact files for a run.
parameters:
- $ref: "#/components/parameters/RunId"
responses:
"200":
description: Artifact files captured for the run
content:
application/json:
schema:
$ref: "#/components/schemas/RunArtifactListResponse"
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/stages/{stageId}/artifacts:
get:
operationId: listStageArtifacts
tags: [Run Internals]
summary: List Stage Artifacts
description: Lists artifact filenames stored for a stage.
parameters:
- $ref: "#/components/parameters/RunId"
- $ref: "#/components/parameters/StageId"
responses:
"200":
description: Artifact filenames for the stage
content:
application/json:
schema:
$ref: "#/components/schemas/ArtifactListResponse"
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
post:
operationId: putStageArtifact
tags: [Run Internals]
summary: Put Stage Artifact
description: |
Uploads one or more artifacts for a stage. Intended for trusted internal callers.
The server accepts both:
- `application/octet-stream` for single-file uploads with the `filename` query parameter
- strict manifest-first `multipart/form-data` uploads documented by `ArtifactBatchUploadManifest`
The generated Rust client currently exposes the octet-stream variant because the OpenAPI
code generator in this repo does not support multiple request media types on one operation.
parameters:
- $ref: "#/components/parameters/RunId"
- $ref: "#/components/parameters/StageId"
- name: filename
in: query
required: false
description: Relative artifact path for `application/octet-stream` uploads. Ignored for multipart uploads.
schema:
type: string
requestBody:
required: true
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
"204":
description: Artifact written
"400":
description: Invalid filename, multipart manifest, checksum, or upload body
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/stages/{stageId}/artifacts/download:
get:
operationId: getStageArtifact
tags: [Run Internals]
summary: Get Stage Artifact
description: Downloads an artifact by filename.
parameters:
- $ref: "#/components/parameters/RunId"
- $ref: "#/components/parameters/StageId"
- $ref: "#/components/parameters/ArtifactFilename"
responses:
"200":
description: Artifact contents
content:
application/octet-stream:
schema:
type: string
format: binary
"400":
description: Missing filename
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"404":
description: Run, stage, or artifact not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/billing:
get:
operationId: retrieveRunBilling
tags: [Run Outputs]
summary: Retrieve Run Billing
description: Returns token counts and billed totals broken down by stage and model for a specific run.
parameters:
- $ref: "#/components/parameters/RunId"
responses:
"200":
description: Billing data
content:
application/json:
schema:
$ref: "#/components/schemas/RunBilling"
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/settings:
get:
operationId: retrieveRunSettings
tags: [Run Internals]
summary: Retrieve Run Settings
description: Returns the structured settings used to launch this run.
parameters:
- $ref: "#/components/parameters/RunId"
responses:
"200":
description: Run settings
content:
application/json:
schema:
$ref: "#/components/schemas/RunSettings"
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/preview:
post:
operationId: generatePreviewUrl
tags: [Human-in-the-Loop]
summary: Preview URL
description: Generates a preview URL for a port exposed by the run's sandbox environment.
parameters:
- $ref: "#/components/parameters/RunId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/PreviewUrlRequest"
responses:
"201":
description: Preview URL created
content:
application/json:
schema:
$ref: "#/components/schemas/PreviewUrlResponse"
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"409":
description: Run has no active sandbox
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/ssh:
post:
operationId: createRunSshAccess
tags: [Human-in-the-Loop]
summary: SSH Access
description: Creates a time-limited SSH command for the run's sandbox environment.
parameters:
- $ref: "#/components/parameters/RunId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SshAccessRequest"
responses:
"201":
description: SSH command created
content:
application/json:
schema:
$ref: "#/components/schemas/SshAccessResponse"
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"409":
description: Run has no active sandbox or provider does not support SSH
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/sandbox/files:
get:
operationId: listSandboxFiles
tags: [Human-in-the-Loop]
summary: List Sandbox Files
description: Lists directory entries from the run's sandbox environment.
parameters:
- $ref: "#/components/parameters/RunId"
- in: query
name: path
required: true
schema:
type: string
- in: query
name: depth
required: false
schema:
type: integer
minimum: 1
responses:
"200":
description: Directory entries
content:
application/json:
schema:
$ref: "#/components/schemas/SandboxFileListResponse"
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"409":
description: Run has no active sandbox
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/runs/{id}/sandbox/file:
get:
operationId: getSandboxFile
tags: [Human-in-the-Loop]
summary: Download Sandbox File
description: Downloads a file from the run's sandbox environment.
parameters:
- $ref: "#/components/parameters/RunId"
- in: query
name: path
required: true
schema:
type: string
responses:
"200":
description: File contents
content:
application/octet-stream:
schema:
type: string
format: binary
"404":
description: Run or file not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"409":
description: Run has no active sandbox
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
put:
operationId: putSandboxFile
tags: [Human-in-the-Loop]
summary: Upload Sandbox File
description: Uploads a file into the run's sandbox environment.
parameters:
- $ref: "#/components/parameters/RunId"
- in: query
name: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
"204":
description: File written
"404":
description: Run not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"409":
description: Run has no active sandbox
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
# ── Insights ──────────────────────────────────────────────────────────
/api/v1/insights/queries:
get:
operationId: listSavedQueries
tags: [Insights]
summary: List Saved Queries
description: Returns a paginated list of saved SQL queries for the insights editor.
parameters:
- $ref: "#/components/parameters/PageLimit"
- $ref: "#/components/parameters/PageOffset"
responses:
"200":
description: Paginated list of saved queries
content:
application/json:
schema:
$ref: "#/components/schemas/PaginatedSavedQueryList"
post:
operationId: createSavedQuery
tags: [Insights]
summary: Create Saved Query
description: Saves a new named SQL query for later reuse.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SaveQueryRequest"
responses:
"201":
description: Query saved
content:
application/json:
schema:
$ref: "#/components/schemas/SavedQuery"
/api/v1/insights/queries/{id}:
get:
operationId: retrieveSavedQuery
tags: [Insights]
summary: Retrieve Saved Query
description: Returns a single saved query by ID.
parameters:
- $ref: "#/components/parameters/InsightQueryId"
responses:
"200":
description: Saved query
content:
application/json:
schema:
$ref: "#/components/schemas/SavedQuery"
"404":
description: Query not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
put:
operationId: updateSavedQuery
tags: [Insights]
summary: Update Saved Query
description: Replaces the name and SQL of an existing saved query.
parameters:
- $ref: "#/components/parameters/InsightQueryId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SaveQueryRequest"
responses:
"200":
description: Query updated
content:
application/json:
schema:
$ref: "#/components/schemas/SavedQuery"
"404":
description: Query not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
delete:
operationId: deleteSavedQuery
tags: [Insights]
summary: Delete Saved Query
description: Permanently removes a saved query.
parameters:
- $ref: "#/components/parameters/InsightQueryId"
responses:
"204":
description: Query deleted
"404":
description: Query not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/insights/execute:
post:
operationId: executeQuery
tags: [Insights]
summary: Execute Query
description: Executes an ad-hoc SQL query against the analytics database and returns columnar results.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ExecuteQueryRequest"
responses:
"200":
description: Query results
content:
application/json:
schema:
$ref: "#/components/schemas/ExecuteQueryResponse"
"400":
description: Bad SQL or query error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/insights/history:
get:
operationId: listQueryHistory
tags: [Insights]
summary: List Query History
description: Returns a paginated history of recently executed queries with timing and row counts.
parameters:
- $ref: "#/components/parameters/PageLimit"
- $ref: "#/components/parameters/PageOffset"
responses:
"200":
description: Paginated list of history entries
content:
application/json:
schema:
$ref: "#/components/schemas/PaginatedHistoryEntryList"
# ── Billing ──────────────────────────────────────────────────────────
/api/v1/billing:
get:
operationId: getAggregateBilling
tags: [Billing]
summary: Aggregate Billing
description: Returns aggregate token counts and billed totals across all completed runs since server start.
responses:
"200":
description: Aggregate billing data
content:
application/json:
schema:
$ref: "#/components/schemas/AggregateBilling"
# ── System ───────────────────────────────────────────────────────────
/api/v1/attach:
get:
operationId: attachEvents
tags: [System]
summary: Attach Global Events
description: Opens a server-sent event stream for live run events across the server.
parameters:
- name: run_id
in: query
required: false
description: Optional comma-separated list of run IDs to include.
schema:
type: string
responses:
"200":
description: Server-sent event stream
content:
text/event-stream:
schema:
type: string
/api/v1/system/info:
get:
operationId: getSystemInfo
tags: [System]
summary: Retrieve System Info
description: Returns runtime details about the active Fabro server process.
responses:
"200":
description: System information
content:
application/json:
schema:
$ref: "#/components/schemas/SystemInfoResponse"
/api/v1/system/df:
get:
operationId: getSystemDiskUsage
tags: [System]
summary: Retrieve System Disk Usage
description: Returns disk usage for the server storage directory.
parameters:
- name: verbose
in: query
required: false
description: Include per-run disk usage rows.
schema:
type: boolean
default: false
responses:
"200":
description: Disk usage summary
content:
application/json:
schema:
$ref: "#/components/schemas/DiskUsageResponse"
/api/v1/system/prune/runs:
post:
operationId: pruneRuns
tags: [System]
summary: Prune Runs
description: Deletes completed runs matching the provided filters, or previews the deletion set when dry-run is enabled.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/PruneRunsRequest"
responses:
"200":
description: Prune result
content:
application/json:
schema:
$ref: "#/components/schemas/PruneRunsResponse"
"400":
description: Invalid prune request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
# ── Secrets ──────────────────────────────────────────────────────────
/api/v1/secrets:
get:
operationId: listSecrets
tags: [Secrets]
summary: List stored secrets
description: Returns stored secret names and timestamps. Secret values are never exposed.
responses:
"200":
description: Secret metadata list
content:
application/json:
schema:
$ref: "#/components/schemas/SecretListResponse"
/api/v1/secrets/{name}:
put:
operationId: setSecret
tags: [Secrets]
summary: Store or update a secret
parameters:
- name: name
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SetSecretRequest"
responses:
"200":
description: Secret stored
content:
application/json:
schema:
$ref: "#/components/schemas/SecretMetadata"
"400":
description: Invalid secret name or request body
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
delete:
operationId: deleteSecret
tags: [Secrets]
summary: Delete a stored secret
parameters:
- name: name
in: path
required: true
schema:
type: string
responses:
"204":
description: Secret deleted
"400":
description: Invalid secret name
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"404":
description: Secret not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"500":
description: Secret store write failed
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
# ── Repos ────────────────────────────────────────────────────────────
/api/v1/repos/github/{owner}/{name}:
get:
operationId: getGithubRepo
tags: [Repos]
summary: Check server access to a GitHub repository
parameters:
- name: owner
in: path
required: true
schema:
type: string
- name: name
in: path
required: true
schema:
type: string
responses:
"200":
description: Repository access details
content:
application/json:
schema:
$ref: "#/components/schemas/RepoCheckResponse"
# ── Models ───────────────────────────────────────────────────────────
/api/v1/models:
get:
operationId: listModels
tags: [Models]
summary: List Models
description: Returns a paginated list of available LLM models from the built-in catalog.
parameters:
- $ref: "#/components/parameters/ModelProviderFilter"
- $ref: "#/components/parameters/ModelQueryFilter"
- $ref: "#/components/parameters/PageLimit"
- $ref: "#/components/parameters/PageOffset"
responses:
"200":
description: Paginated list of models
content:
application/json:
schema:
$ref: "#/components/schemas/PaginatedModelList"
"400":
description: Invalid filter value
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/api/v1/models/{id}/test:
post:
operationId: testModel
tags: [Models]
summary: Test Model
description: Tests a model by sending a simple prompt and reporting pass/fail.
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The model identifier.
- $ref: "#/components/parameters/ModelTestModeParam"
responses:
"200":
description: Test result
content:
application/json:
schema:
$ref: "#/components/schemas/ModelTestResult"
"400":
description: Invalid test mode
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"404":
description: Model not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
# ── Completions ───────────────────────────────────────────────────────
/api/v1/completions:
post:
operationId: createCompletion
tags: [Completions]
summary: Create Completion
description: |
Generate a text completion. Set `stream: true` for SSE streaming.
All SSE frames use `event: stream_event` with a JSON-serialized StreamEvent
payload. StreamEvent types: stream_start, text_start, text_delta, text_end,
tool_call_start, tool_call_delta, tool_call_end, finish, error.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateCompletionRequest"
responses:
"200":
description: Completion result (JSON when stream=false, SSE when stream=true)
content:
application/json:
schema:
$ref: "#/components/schemas/CompletionResponse"
"400":
description: Invalid request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
# ── Settings ──────────────────────────────────────────────────────────
/api/v1/settings:
get:
operationId: retrieveServerSettings
tags: [Settings]
summary: Retrieve Server Settings
description: Returns the structured server settings.
responses:
"200":
description: Server settings
content:
application/json:
schema:
$ref: "#/components/schemas/ServerSettings"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
JWT bearer token issued by fabro-web. See the [Authentication](/api-reference/overview#authentication) guide for details.
# OpenAPI 3.1 defines type: mutualTLS, but our parser (openapiv3) only
# supports 3.0 scheme types. We use apiKey as a placeholder; actual mTLS
# enforcement happens at the transport layer via client certificates.
mTLS:
type: apiKey
in: header
name: X-mTLS-Client-CN
description: >
Mutual TLS: client certificate signed by the configured CA. Identity
is extracted from the certificate's Common Name (CN). This scheme is
enforced at the transport layer, not via an HTTP header.
parameters:
RunId:
name: id
in: path
required: true
description: Unique run identifier (ULID).
schema:
type: string
example: 01JNQVR7M0EJ5GKAT2SC4ERS1Z
StageId:
name: stageId
in: path
required: true
description: Identifier of a stage within a run's workflow graph, serialized as `node_id@visit`.
schema:
type: string
example: code@2
BlobId:
name: blobId
in: path
required: true
description: Content-addressed blob identifier.
schema:
type: string
pattern: '^[0-9a-f]{64}$'
example: 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
ArtifactFilename:
name: filename
in: query
required: true
description: Relative artifact path. `/` is allowed as a path separator. Backslash, empty segments, and traversal segments (`.` and `..`) are invalid.
schema:
type: string
example: src/lib.rs
SinceSeq:
name: since_seq
in: query
required: false
description: First event sequence number to include.
schema:
type: integer
minimum: 1
default: 1
example: 42
EventLimit:
name: limit
in: query
required: false
description: Maximum number of events to return.
schema:
type: integer
minimum: 1
maximum: 1000
default: 100
example: 100
QuestionId:
name: qid
in: path
required: true
description: Unique identifier of a pending question.
schema:
type: string
example: q-001
InsightQueryId:
name: id
in: path
required: true
description: Unique identifier of a saved query.
schema:
type: string
example: "1"
CheckpointFilter:
name: checkpoint
in: query
required: false
description: Filter to a specific checkpoint ID. Omit to include all changes.
schema:
type: string
example: cp-3
PageLimit:
name: page[limit]
in: query
required: false
description: Maximum number of items to return per page.
schema:
type: integer
minimum: 1
maximum: 100
default: 20
example: 20
PageOffset:
name: page[offset]
in: query
required: false
description: Number of items to skip before returning results.
schema:
type: integer
minimum: 0
default: 0
example: 0
ModelProviderFilter:
name: provider
in: query
required: false
description: Filter models by provider name. Invalid values return `400`.
schema:
type: string
example: anthropic
ModelQueryFilter:
name: query
in: query
required: false
description: Case-insensitive substring search across `id`, `display_name`, and `aliases`.
schema:
type: string
example: opus
ModelTestModeParam:
name: mode
in: query
required: false
description: Test mode for the single-model test endpoint. Defaults to `basic`.
schema:
$ref: "#/components/schemas/ModelTestMode"
example: basic
schemas:
# ── Pagination ───────────────────────────────────────────────────────
PaginationMeta:
description: Pagination metadata included in every paginated response.
type: object
required:
- has_more
properties:
has_more:
type: boolean
description: Whether additional pages of results are available.
example: true
PaginatedRunList:
description: Paginated list of runs.
type: object
required:
- data
- meta
properties:
data:
type: array
items:
$ref: "#/components/schemas/RunListItem"
meta:
$ref: "#/components/schemas/PaginationMeta"
PaginatedModelList:
description: Paginated list of models.
type: object
required:
- data
- meta
properties:
data:
type: array
items:
$ref: "#/components/schemas/Model"
meta:
$ref: "#/components/schemas/PaginationMeta"
ModelLimits:
description: Token limits for a model.
type: object
required:
- context_window
properties:
context_window:
type: integer
format: int64
description: Maximum context window size in tokens.
example: 1000000
max_output:
type: integer
format: int64
nullable: true
description: Maximum output tokens, if known.
example: 128000
ModelFeatures:
description: Capability flags for a model.
type: object
required:
- tools
- vision
- reasoning
properties:
tools:
type: boolean
description: Whether the model supports tool use.
vision:
type: boolean
description: Whether the model supports vision/image inputs.
reasoning:
type: boolean
description: Whether the model supports extended reasoning.
ModelCosts:
description: Pricing per million tokens in USD.
type: object
properties:
input_cost_per_mtok:
type: number
format: double
nullable: true
description: Cost per million input tokens in USD.
example: 15.0
output_cost_per_mtok:
type: number
format: double
nullable: true
description: Cost per million output tokens in USD.
example: 75.0
cache_input_cost_per_mtok:
type: number
format: double
nullable: true
description: Cost per million cached input tokens in USD.
example: 1.50
Model:
description: An available LLM model from the built-in catalog.
type: object
required:
- id
- provider
- family
- display_name
- limits
- features
- costs
- aliases
- default
properties:
id:
type: string
description: Unique model identifier.
example: "claude-opus-4-6"
provider:
type: string
description: Provider that serves this model.
example: "anthropic"
family:
type: string
description: Model family grouping.
example: "claude-4"
display_name:
type: string
description: Human-readable model name.
example: "Claude Opus 4.6"
limits:
$ref: "#/components/schemas/ModelLimits"
training:
type: string
nullable: true
description: Training data cutoff date (YYYY-MM-DD).
example: "2025-08-01"
features:
$ref: "#/components/schemas/ModelFeatures"
costs:
$ref: "#/components/schemas/ModelCosts"
estimated_output_tps:
type: number
format: double
nullable: true
description: Estimated output tokens per second.
aliases:
type: array
items:
type: string
description: Alternative names that resolve to this model.
example: ["opus"]
default:
type: boolean
description: Whether this is the default model for its provider.
ModelTestResult:
description: Result of testing a model in `basic` or `deep` mode.
type: object
required:
- model_id
- status
properties:
model_id:
type: string
description: The model identifier that was tested.
example: "claude-opus-4-6"
status:
type: string
enum:
- ok
- error
description: Whether the model responded successfully.
error_message:
type: string
nullable: true
description: Error details when status is "error".
ModelTestMode:
description: Single-model test mode.
type: string
enum:
- basic
- deep
# ── Completion Schemas ─────────────────────────────────────────────
CompletionMessage:
description: A message in the conversation.
type: object
required: [role, content]
properties:
role:
type: string
enum: [system, user, assistant, tool, developer]
description: The role of the message author.
content:
type: array
description: Content parts of the message.
items:
$ref: "#/components/schemas/CompletionContentPart"
name:
type: string
description: Optional name for the message author.
tool_call_id:
type: string
description: Tool call ID for tool result messages.
CompletionContentPart:
description: A content part within a message, discriminated by `kind`.
type: object
required: [kind]
properties:
kind:
type: string
description: "Content part type: text, image, tool_call, tool_result, thinking, etc."
data:
description: Content data, structure depends on kind.
CompletionToolDefinition:
description: A tool available for the model to call.
type: object
required: [name, description, parameters]
properties:
name:
type: string
description: Tool name.
description:
type: string
description: Human-readable tool description.
parameters:
description: JSON Schema for the tool's parameters.
CompletionToolChoice:
description: Controls how the model selects tools.
type: object
required: [mode]
properties:
mode:
type: string
enum: [auto, none, required, named]
description: Tool selection mode.
tool_name:
type: string
description: Required when mode is "named".
CreateCompletionRequest:
type: object
required: [messages]
properties:
messages:
type: array
description: The conversation messages.
items:
$ref: "#/components/schemas/CompletionMessage"
model:
type: string
description: Model ID or alias. Server picks default if omitted.
system:
type: string
description: System prompt (convenience; prepended as a system message).
stream:
type: boolean
default: true
description: Stream response via SSE.
tools:
type: array
description: Tool definitions available to the model.
items:
$ref: "#/components/schemas/CompletionToolDefinition"
tool_choice:
$ref: "#/components/schemas/CompletionToolChoice"
schema:
description: JSON Schema for structured output.
temperature:
type: number
format: double
max_tokens:
type: integer
format: int64
top_p:
type: number
format: double
stop_sequences:
type: array
items:
type: string
description: Stop sequences.
reasoning_effort:
type: string
description: Reasoning effort level.
provider:
type: string
description: Provider to route to.
provider_options:
description: Provider-specific options.
CompletionUsage:
type: object
required: [input_tokens, output_tokens]
properties:
input_tokens:
type: integer
format: int64
output_tokens:
type: integer
format: int64
CompletionResponse:
type: object
required: [id, model, message, stop_reason, usage]
properties:
id:
type: string
model:
type: string
message:
$ref: "#/components/schemas/CompletionMessage"
stop_reason:
type: string
description: Why generation stopped (end_turn, max_tokens, tool_calls).
usage:
$ref: "#/components/schemas/CompletionUsage"
output:
description: Parsed structured output when schema was provided.
PaginatedSavedQueryList:
description: Paginated list of saved queries.
type: object
required:
- data
- meta
properties:
data:
type: array
items:
$ref: "#/components/schemas/SavedQuery"
meta:
$ref: "#/components/schemas/PaginationMeta"
PaginatedHistoryEntryList:
description: Paginated list of query history entries.
type: object
required:
- data
- meta
properties:
data:
type: array
items:
$ref: "#/components/schemas/HistoryEntry"
meta:
$ref: "#/components/schemas/PaginationMeta"
PaginatedStageTurnList:
description: Paginated list of stage turns.
type: object
required:
- data
- meta
properties:
data:
type: array
items:
$ref: "#/components/schemas/StageTurn"
meta:
$ref: "#/components/schemas/PaginationMeta"
PaginatedApiQuestionList:
description: Paginated list of pending questions.
type: object
required:
- data
- meta
properties:
data:
type: array
items:
$ref: "#/components/schemas/ApiQuestion"
meta:
$ref: "#/components/schemas/PaginationMeta"
PaginatedRunStageList:
description: Paginated list of run stages.
type: object
required:
- data
- meta
properties:
data:
type: array
items:
$ref: "#/components/schemas/RunStage"
meta:
$ref: "#/components/schemas/PaginationMeta"
# ── Run Schemas ──────────────────────────────────────────────────────
RunStatus:
description: Lifecycle status of a run.
type: string
enum:
- submitted
- queued
- starting
- running
- completed
- failed
- cancelled
- paused
RunManifest:
description: Self-contained workflow run manifest.
type: object
required:
- version
- cwd
- target
- workflows
properties:
version:
type: integer
description: Manifest schema version.
example: 1
run_id:
type: string
nullable: true
description: Optional pre-generated run ID to use instead of allocating a new ULID.
example: "01HV6D7S5YF4Z4B2M7K4N0Q6T9"
cwd:
type: string
description: CLI working directory at invocation time.
example: "/tmp/project"
git:
$ref: "#/components/schemas/ManifestGit"
goal:
$ref: "#/components/schemas/ManifestGoal"
args:
$ref: "#/components/schemas/ManifestArgs"
target:
$ref: "#/components/schemas/ManifestTarget"
configs:
type: array
items:
$ref: "#/components/schemas/ManifestConfig"
workflows:
type: object
additionalProperties:
$ref: "#/components/schemas/ManifestWorkflow"
ManifestGit:
description: Observable git state from the CLI working directory.
type: object
required:
- origin_url
- branch
- sha
- clean
properties:
origin_url:
type: string
description: Remote origin URL with any embedded credentials removed.
example: "https://github.com/acme/my-app.git"
branch:
type: string
description: Current branch name.
example: feature/foo
sha:
type: string
description: Current commit SHA.
example: abc123def
clean:
type: boolean
description: Whether the working tree has uncommitted changes.
ManifestGoal:
description: Resolved goal with provenance.
type: object
required:
- type
- text
properties:
type:
type: string
enum:
- value
- file
- graph
text:
type: string
description: Resolved goal content.
path:
type: string
nullable: true
description: Original goal file path when the goal came from a file.
ManifestArgs:
description: Sparse command-local args that affect run settings.
type: object
properties:
model:
type: string
provider:
type: string
sandbox:
type: string
verbose:
type: boolean
dry_run:
type: boolean
auto_approve:
type: boolean
no_retro:
type: boolean
preserve_sandbox:
type: boolean
label:
type: array
items:
type: string
ManifestTarget:
type: object
required:
- identifier
- path
properties:
identifier:
type: string
description: What the user typed.
example: smoke
path:
type: string
description: Resolved path that keys into the workflows map.
example: fabro/workflows/smoke/workflow.fabro
ManifestConfig:
type: object
required:
- type
properties:
type:
type: string
enum:
- project
- user
path:
type: string
nullable: true
source:
type: string
nullable: true
ManifestWorkflowConfig:
type: object
required:
- path
- source
properties:
path:
type: string
source:
type: string
ManifestFileEntry:
description: A bundled file with discovery metadata.
type: object
required:
- content
- ref
properties:
content:
type: string
ref:
$ref: "#/components/schemas/ManifestFileRef"
ManifestFileRef:
type: object
required:
- type
- original
properties:
type:
type: string
enum:
- file_inline
- import
- dockerfile
original:
type: string
from:
type: string
nullable: true
ManifestWorkflow:
type: object
required:
- source
properties:
source:
type: string
config:
$ref: "#/components/schemas/ManifestWorkflowConfig"
files:
type: object
additionalProperties:
$ref: "#/components/schemas/ManifestFileEntry"
PreflightResponse:
type: object
required:
- ok
- workflow
- checks
properties:
ok:
type: boolean
description: Whether preflight passed using the CLI-compatible success rule.
workflow:
$ref: "#/components/schemas/PreflightWorkflowSummary"
checks:
$ref: "#/components/schemas/PreflightCheckReport"
RenderWorkflowGraphRequest:
type: object
required:
- manifest
properties:
manifest:
$ref: "#/components/schemas/RunManifest"
format:
$ref: "#/components/schemas/RenderWorkflowGraphFormat"
direction:
$ref: "#/components/schemas/RenderWorkflowGraphDirection"
RenderWorkflowGraphFormat:
type: string
enum:
- svg
- png
RenderWorkflowGraphDirection:
type: string
enum:
- lr
- tb
PreflightWorkflowSummary:
type: object
required:
- name
- nodes
- edges
- goal
- diagnostics
properties:
name:
type: string
graph_path:
type: string
nullable: true
nodes:
type: integer
edges:
type: integer
goal:
type: string
diagnostics:
type: array
items:
$ref: "#/components/schemas/WorkflowDiagnostic"
WorkflowDiagnostic:
type: object
required:
- rule
- severity
- message
properties:
rule:
type: string
severity:
type: string
enum:
- error
- warning
- info
message:
type: string
node_id:
type: string
nullable: true
edge:
type: array
nullable: true
minItems: 2
maxItems: 2
items:
type: string
fix:
type: string
nullable: true
PreflightCheckReport:
type: object
required:
- title
- sections
properties:
title:
type: string
sections:
type: array
items:
$ref: "#/components/schemas/PreflightCheckSection"
PreflightCheckSection:
type: object
required:
- title
- checks
properties:
title:
type: string
checks:
type: array
items:
$ref: "#/components/schemas/PreflightCheckResult"
PreflightCheckResult:
type: object
required:
- name
- status
- summary
- details
properties:
name:
type: string
status:
type: string
enum:
- pass
- warning
- error
summary:
type: string
details:
type: array
items:
$ref: "#/components/schemas/PreflightCheckDetail"
remediation:
type: string
nullable: true
PreflightCheckDetail:
type: object
required:
- text
- warn
properties:
text:
type: string
warn:
type: boolean
StartRunRequest:
description: Request body for starting or resuming a run.
type: object
properties:
resume:
type: boolean
description: Resume from checkpoint instead of starting from submitted state.
default: false
RunStatusResponse:
description: Current status of a run with optional error and queue position.
type: object
required:
- id
- status
- created_at
properties:
id:
type: string
description: Unique run identifier (ULID).
example: 01JNQVR7M0EJ5GKAT2SC4ERS1Z
status:
$ref: "#/components/schemas/RunStatus"
error:
$ref: "#/components/schemas/RunError"
queue_position:
type: integer
description: Position in the queue (1-based). Only present when status is `queued`.
example: 3
status_reason:
allOf:
- $ref: "#/components/schemas/StatusReason"
nullable: true
pending_control:
allOf:
- $ref: "#/components/schemas/RunControlAction"
nullable: true
created_at:
type: string
format: date-time
description: Timestamp when the run was created.
example: "2026-03-06T14:30:00Z"
ApiQuestionOption:
description: A selectable option for a multiple-choice or multi-select question.
type: object
required:
- key
- label
properties:
key:
type: string
description: Machine-readable option key used when submitting an answer.
example: option_a
label:
type: string
description: Human-readable label displayed to the user.
example: Accept changes
ApiQuestion:
description: A pending human-in-the-loop question generated by a workflow stage.
type: object
required:
- id
- text
- stage
- question_type
- options
- allow_freeform
properties:
id:
type: string
description: Unique question identifier.
example: q-001
text:
type: string
description: The question text displayed to the user.
example: Should we proceed with the proposed changes?
stage:
type: string
description: Workflow stage identifier that produced the question.
example: gate
question_type:
$ref: "#/components/schemas/QuestionType"
options:
type: array
description: Available options for selection-based questions. Empty for freeform questions.
items:
$ref: "#/components/schemas/ApiQuestionOption"
allow_freeform:
type: boolean
description: Whether the user may provide freeform text in addition to selecting options.
example: true
timeout_seconds:
type: number
format: double
nullable: true
description: Timeout for the question when configured by the workflow.
example: 30
context_display:
type: string
nullable: true
description: Optional contextual text shown alongside the question.
example: Latest draft
QuestionType:
description: The interaction type of a human-in-the-loop question.
type: string
enum:
- yes_no
- multiple_choice
- multi_select
- freeform
- confirmation
SubmitAnswerRequest:
description: >
Request body for submitting an answer to a pending question.
At least one of `value`, `selected_option_key`, or `selected_option_keys` must be provided.
type: object
properties:
value:
type: string
description: Freeform answer text.
example: "Yes, proceed with the changes."
selected_option_key:
type: string
description: Key of the selected option (for single-select multiple-choice questions).
example: option_a
selected_option_keys:
type: array
items:
type: string
description: Keys of selected options (for multi-select questions).
example: ["option_a", "option_b"]
ErrorResponseEntry:
description: A single error entry in an error response.
type: object
required:
- status
- title
- detail
properties:
status:
type: string
description: HTTP status code as a string.
example: "404"
title:
type: string
description: Short error classification.
example: Not Found
detail:
type: string
description: Human-readable error description.
example: Run not found.
ErrorResponse:
description: Standard error response containing one or more error entries.
type: object
required:
- errors
properties:
errors:
type: array
description: List of error entries.
items:
$ref: "#/components/schemas/ErrorResponseEntry"
RunEvent:
description: >
Internal RunEvent-compatible JSON payload. The server validates this
body by deserializing into the typed RunEvent struct.
type: object
required:
- id
- ts
- run_id
- event
properties:
id:
type: string
ts:
type: string
format: date-time
run_id:
type: string
node_id:
type: string
nullable: true
node_label:
type: string
nullable: true
session_id:
type: string
nullable: true
parent_session_id:
type: string
nullable: true
event:
type: string
description: Event type discriminator.
example: stage.started
properties:
type: object
additionalProperties: true
additionalProperties: true
EventEnvelope:
description: Stored event envelope with assigned sequence number.
type: object
required:
- seq
- payload
properties:
seq:
type: integer
description: Assigned event sequence number.
example: 42
payload:
$ref: "#/components/schemas/RunEvent"
PaginatedEventList:
description: Paginated list of stored run events.
type: object
required:
- data
- meta
properties:
data:
type: array
items:
$ref: "#/components/schemas/EventEnvelope"
meta:
$ref: "#/components/schemas/PaginationMeta"
AppendEventResponse:
description: Assigned sequence number for an appended event.
type: object
required:
- seq
properties:
seq:
type: integer
description: Assigned event sequence number.
example: 42
WriteBlobResponse:
description: Content-addressed identifier for a stored blob.
type: object
required:
- id
properties:
id:
type: string
description: Blob identifier.
example: 550e8400-e29b-41d4-a716-446655440000
ArtifactEntry:
description: A single artifact filename.
type: object
required:
- filename
properties:
filename:
type: string
description: Artifact filename.
example: src/lib.rs
ArtifactListResponse:
description: List of artifact filenames for a stage.
type: object
required:
- data
properties:
data:
type: array
items:
$ref: "#/components/schemas/ArtifactEntry"
ArtifactBatchUploadEntry:
description: One file entry in a strict multipart artifact upload manifest.
type: object
required:
- part
- path
properties:
part:
type: string
description: Multipart field name for the file part.
example: file1
path:
type: string
description: Relative artifact path to store.
example: src/lib.rs
sha256:
type: string
nullable: true
description: Optional lowercase hex SHA-256 checksum for the file contents.
example: 3f785df4c5b7d3f1f4c1f0ecb0f55f1d9f6f6a3d9f0a8a98f7a74f29d1f81a2c
expected_bytes:
type: integer
format: int64
nullable: true
minimum: 0
description: Optional exact byte length expected for the file part.
example: 1234
content_type:
type: string
nullable: true
description: Optional client-supplied content type for the file part.
example: text/plain
ArtifactBatchUploadManifest:
description: Manifest for strict multipart artifact uploads.
type: object
required:
- entries
properties:
entries:
type: array
minItems: 1
items:
$ref: "#/components/schemas/ArtifactBatchUploadEntry"
RunArtifactEntry:
description: A captured artifact file for a run.
type: object
required:
- stage_id
- node_slug
- retry
- relative_path
- size
properties:
stage_id:
type: string
description: Stage ID in `node@visit` form.
node_slug:
type: string
description: Node slug that produced the artifact.
retry:
type: integer
format: int32
description: Retry attempt number.
relative_path:
type: string
description: Artifact path relative to the stage artifact capture directory.
size:
type: integer
format: int64
description: Artifact size in bytes.
RunArtifactListResponse:
description: List of captured artifact files for a run.
type: object
required:
- data
properties:
data:
type: array
items:
$ref: "#/components/schemas/RunArtifactEntry"
InternalRunStatus:
description: Internal event-sourced run status.
type: string
enum:
- submitted
- starting
- running
- paused
- removing
- succeeded
- failed
- dead
StatusReason:
description: Optional reason attached to a run status transition.
type: string
enum:
- completed
- partial_success
- workflow_error
- cancelled
- terminated
- transient_infra
- budget_exhausted
- launch_failed
- bootstrap_failed
- sandbox_init_failed
- sandbox_initializing
RunControlAction:
description: Run control action requested by the API.
type: string
enum:
- cancel
- pause
- unpause
RunStatusRecord:
description: Internal run status record from the event projection.
type: object
required:
- status
- updated_at
properties:
status:
$ref: "#/components/schemas/InternalRunStatus"
reason:
oneOf:
- $ref: "#/components/schemas/StatusReason"
- type: "null"
updated_at:
type: string
format: date-time
InternalStageStatus:
description: Internal stage status from outcomes and node status records.
type: string
enum:
- success
- fail
- skipped
- partial_success
- retry
NodeStatusRecord:
description: Internal node status record.
type: object
required:
- status
- timestamp
properties:
status:
$ref: "#/components/schemas/InternalStageStatus"
notes:
type: string
nullable: true
failure_reason:
type: string
nullable: true
timestamp:
type: string
format: date-time
NodeState:
description: Internal node projection state.
type: object
properties:
prompt:
type: string
nullable: true
response:
type: string
nullable: true
status:
oneOf:
- $ref: "#/components/schemas/NodeStatusRecord"
- type: "null"
provider_used:
nullable: true
diff:
type: string
nullable: true
script_invocation:
nullable: true
script_timing:
nullable: true
parallel_results:
nullable: true
stdout:
type: string
nullable: true
stderr:
type: string
nullable: true
RunProjection:
description: Raw internal run projection derived from the event log.
type: object
required:
- nodes
properties:
run:
type: object
additionalProperties: true
nullable: true
graph_source:
type: string
nullable: true
start:
type: object
additionalProperties: true
nullable: true
status:
oneOf:
- $ref: "#/components/schemas/RunStatusRecord"
- type: "null"
checkpoint:
oneOf:
- $ref: "#/components/schemas/RunCheckpoint"
- type: "null"
checkpoints:
type: array
description: Sequence-tagged checkpoint history entries as `[seq, checkpoint]`.
items:
type: array
minItems: 2
maxItems: 2
items:
oneOf:
- type: integer
- $ref: "#/components/schemas/RunCheckpoint"
conclusion:
type: object
additionalProperties: true
nullable: true
retro:
type: object
additionalProperties: true
nullable: true
retro_prompt:
type: string
nullable: true
retro_response:
type: string
nullable: true
sandbox:
type: object
additionalProperties: true
nullable: true
final_patch:
type: string
nullable: true
pull_request:
type: object
additionalProperties: true
nullable: true
nodes:
type: object
description: Map from StageId (`node_id@visit`) to NodeState.
additionalProperties:
$ref: "#/components/schemas/NodeState"
StoreRunSummary:
description: Durable run summary derived from the backing store.
type: object
required:
- run_id
- labels
properties:
run_id:
type: string
workflow_name:
type: string
nullable: true
workflow_slug:
type: string
nullable: true
goal:
type: string
nullable: true
labels:
type: object
additionalProperties:
type: string
host_repo_path:
type: string
nullable: true
start_time:
type: string
format: date-time
nullable: true
status:
type: string
nullable: true
status_reason:
type: string
nullable: true
pending_control:
allOf:
- $ref: "#/components/schemas/RunControlAction"
nullable: true
duration_ms:
type: integer
format: int64
minimum: 0
nullable: true
total_usd_micros:
type: integer
format: int64
nullable: true
# ── Run Board Schemas ────────────────────────────────────────────────
BoardColumn:
description: Board column status for a run in the list view.
type: string
enum:
- working
- pending
- review
- merge
CheckRunStatus:
description: Status of a CI check run.
type: string
enum:
- success
- failure
- skipped
- pending
- queued
CheckRun:
description: A CI check run result associated with a run's pull request.
type: object
required:
- name
- status
properties:
name:
type: string
description: Name of the CI check.
example: unit-tests
status:
$ref: "#/components/schemas/CheckRunStatus"
duration_secs:
type: number
description: Duration of the check run in seconds.
example: 154.0
# ── Reusable Sub-Schemas ───────────────────────────────────────────
ModelReference:
description: Reference to a model by its identifier.
type: object
required:
- id
properties:
id:
type: string
description: Model identifier.
example: claude-opus-4-6
WorkflowReference:
description: Reference to a workflow by its slug.
type: object
required:
- slug
properties:
slug:
type: string
description: URL-safe workflow slug.
example: implement
RunReference:
description: Reference to a run with its title.
type: object
required:
- id
- title
properties:
id:
type: string
description: Unique run identifier.
example: run-047
title:
type: string
description: Human-readable run title.
example: "PR #312 — Add OAuth2 PKCE flow"
RepositoryReference:
description: Reference to a repository by name.
type: object
required:
- name
properties:
name:
type: string
description: Repository name.
example: api-server
BilledTokenCounts:
description: Token counts with optional billed USD micros totals.
type: object
required:
- input_tokens
- output_tokens
- total_tokens
properties:
input_tokens:
type: integer
description: Number of input tokens consumed.
example: 28640
output_tokens:
type: integer
description: Number of output tokens generated.
example: 8750
total_tokens:
type: integer
description: Total billable tokens aggregated across categories.
example: 37390
reasoning_tokens:
type: integer
description: Number of reasoning tokens.
example: 1200
cache_read_tokens:
type: integer
description: Number of cache read tokens.
example: 4800
cache_write_tokens:
type: integer
description: Number of cache write tokens.
example: 1500
total_usd_micros:
type: integer
format: int64
nullable: true
description: Billed USD amount in micros.
example: 720000
CodeLocation:
description: A file and line location in the codebase.
type: object
required:
- file
properties:
file:
type: string
description: File path.
example: src/middleware/rate-limit.ts
line:
type: integer
description: Line number in the file.
example: 42
RunError:
description: Error information for a failed run.
type: object
required:
- message
properties:
message:
type: string
description: Error message.
example: "Stage 'apply-changes' exceeded maximum retries."
RunPullRequest:
description: Pull request information for a run.
type: object
required:
- number
properties:
number:
type: integer
description: Pull request number.
example: 889
additions:
type: integer
description: Lines added.
example: 234
deletions:
type: integer
description: Lines deleted.
example: 67
comments:
type: integer
description: Number of review comments.
example: 4
checks:
type: array
description: CI check run results.
items:
$ref: "#/components/schemas/CheckRun"
RunTimings:
description: Timing information for a run.
type: object
required:
- elapsed_secs
properties:
elapsed_secs:
type: number
description: Wall-clock time elapsed in seconds.
example: 420.0
elapsed_warning:
type: boolean
description: Whether the elapsed time exceeds the expected threshold.
example: false
SandboxResources:
description: Compute resources allocated to a sandbox.
type: object
required:
- cpu
- memory
properties:
cpu:
type: integer
description: Number of CPU cores.
example: 4
memory:
type: integer
description: Memory in GB.
example: 8
RunSandbox:
description: Sandbox environment for a run.
type: object
required:
- id
properties:
id:
type: string
description: Sandbox identifier.
example: sb-a1b2c3d4
resources:
$ref: "#/components/schemas/SandboxResources"
RunQuestion:
description: A pending human-in-the-loop question summary.
type: object
required:
- text
properties:
text:
type: string
description: Question text.
example: Accept or push for another round?
AggregateBillingTotals:
description: Aggregate billing totals across all runs.
type: object
required:
- runs
- input_tokens
- output_tokens
- total_tokens
- runtime_secs
properties:
runs:
type: integer
description: Total number of completed runs.
example: 9
input_tokens:
type: integer
description: Total input tokens.
example: 643860
output_tokens:
type: integer
description: Total output tokens.
example: 189720
total_tokens:
type: integer
description: Total tokens aggregated across all billing categories.
example: 833580
reasoning_tokens:
type: integer
description: Total reasoning tokens.
example: 12040
cache_read_tokens:
type: integer
description: Total cache read tokens.
example: 85400
cache_write_tokens:
type: integer
description: Total cache write tokens.
example: 9200
total_usd_micros:
type: integer
format: int64
nullable: true
description: Total billed USD amount in micros.
example: 20340000
runtime_secs:
type: number
description: Total runtime in seconds.
example: 3501.0
BillingStageRef:
description: Reference to a billing stage.
type: object
required:
- id
- name
properties:
id:
type: string
description: Stage identifier (slug).
example: propose-changes
name:
type: string
description: Human-readable stage name.
example: Propose Changes
# ── Run Board Schemas (updated) ─────────────────────────────────────
RunListItem:
description: Summary of a run shown in the board view.
type: object
required:
- id
- repository
- title
- workflow
- status
- created_at
properties:
id:
type: string
description: Unique run identifier (ULID).
example: 01JNQVR7M0EJ5GKAT2SC4ERS1Z
repository:
$ref: "#/components/schemas/RepositoryReference"
title:
type: string
description: Human-readable title describing the run's goal.
example: Add rate limiting to auth endpoints
workflow:
$ref: "#/components/schemas/WorkflowReference"
status:
$ref: "#/components/schemas/BoardColumn"
pull_request:
$ref: "#/components/schemas/RunPullRequest"
timings:
$ref: "#/components/schemas/RunTimings"
sandbox:
$ref: "#/components/schemas/RunSandbox"
question:
$ref: "#/components/schemas/RunQuestion"
created_at:
type: string
format: date-time
description: Timestamp when the run was created.
example: "2026-03-06T14:30:00Z"
RunCheckpoint:
description: Serializable snapshot of execution state for crash recovery and resume.
type: object
required:
- timestamp
- current_node
- completed_nodes
- node_retries
- context_values
properties:
timestamp:
type: string
format: date-time
description: ISO 8601 timestamp when the checkpoint was created.
current_node:
type: string
description: Identifier of the node being executed at checkpoint time.
completed_nodes:
type: array
items:
type: string
description: Identifiers of nodes that have completed execution.
node_retries:
type: object
additionalProperties:
type: integer
description: Map of node identifier to retry count.
context_values:
type: object
additionalProperties: true
description: Key-value context map accumulated during execution.
node_outcomes:
type: object
additionalProperties: true
description: Map of node identifier to outcome data for goal gate checks after resume.
next_node_id:
type: string
description: The node to resume execution at after this checkpoint.
git_commit_sha:
type: string
description: SHA of the git commit created at this checkpoint.
loop_failure_signatures:
type: object
additionalProperties: true
description: Failure signature counts within the main loop.
restart_failure_signatures:
type: object
additionalProperties: true
description: Failure signature counts across loop_restart edges.
# ── Stage / Turn Schemas ─────────────────────────────────────────────
StageStatus:
description: Execution status of a workflow stage.
type: string
enum:
- completed
- running
- pending
- failed
- cancelled
RunStage:
description: A single stage in a run's workflow graph.
type: object
required:
- id
- name
- status
properties:
id:
type: string
description: Unique stage identifier within the run.
example: propose-changes
name:
type: string
description: Human-readable stage name.
example: Propose Changes
status:
$ref: "#/components/schemas/StageStatus"
duration_secs:
type: number
description: Time spent in this stage, in seconds.
example: 154.0
dot_id:
type: string
description: Node identifier in the Graphviz graph source.
example: propose
ToolUse:
description: A single tool invocation with its input, result, and execution metadata.
type: object
required:
- id
- tool_name
- input
- result
- is_error
properties:
id:
type: string
description: Unique identifier for this tool invocation. Enables correlation in parallel tool use.
example: toolu_01A09q90qw90lq917835lq9
tool_name:
type: string
description: Name of the tool that was invoked.
example: read_file
input:
type: string
description: JSON-encoded input passed to the tool.
example: '{ "path": "src/routes/auth.ts" }'
result:
type: string
description: Output returned by the tool. Contains the error message when is_error is true.
example: 'import { Router } from "express";'
is_error:
type: boolean
description: Whether the tool invocation failed. When true, the result field contains the error message.
example: false
duration_ms:
type: integer
description: Wall-clock execution time of the tool invocation in milliseconds.
example: 142
StageTurn:
description: A single turn in a stage conversation — a system prompt, assistant response, or tool invocation block.
discriminator:
propertyName: kind
mapping:
system: "#/components/schemas/SystemStageTurn"
assistant: "#/components/schemas/AssistantStageTurn"
tool: "#/components/schemas/ToolStageTurn"
oneOf:
- $ref: "#/components/schemas/SystemStageTurn"
- $ref: "#/components/schemas/AssistantStageTurn"
- $ref: "#/components/schemas/ToolStageTurn"
SystemStageTurn:
description: A system prompt turn that sets the stage's instructions.
type: object
required:
- kind
- content
properties:
kind:
type: string
enum: [system]
content:
type: string
description: System prompt text.
example: You are a drift detection agent. Compare the production and staging environments.
AssistantStageTurn:
description: An assistant response turn within a stage.
type: object
required:
- kind
- content
properties:
kind:
type: string
enum: [assistant]
content:
type: string
description: Assistant response text.
example: I'll start by loading the environment configurations for both production and staging.
ToolStageTurn:
description: A tool invocation turn containing one or more tool calls.
type: object
required:
- kind
- tools
properties:
kind:
type: string
enum: [tool]
content:
type: string
description: Text accompanying the tool invocations, or null when the turn contains only tool calls.
tools:
type: array
description: Tool invocations executed in this turn.
items:
$ref: "#/components/schemas/ToolUse"
# ── File Diff Schemas ──────────────────────────────────────────────
FileCheckpoint:
description: A named checkpoint within a run, used to filter file diffs.
type: object
required:
- id
- label
properties:
id:
type: string
description: Checkpoint identifier.
example: cp-3
label:
type: string
description: Human-readable label for the checkpoint.
example: "Checkpoint 3 — Review Changes"
DiffFile:
description: A file's contents at one side of a diff.
type: object
required:
- name
- contents
properties:
name:
type: string
description: File path relative to the repository root.
example: src/commands/run.ts
contents:
type: string
description: Full file contents. Empty string for newly created or deleted files.
example: 'import { parseArgs } from "node:util";'
FileDiff:
description: A before/after pair showing changes to a single file.
type: object
required:
- old_file
- new_file
properties:
old_file:
$ref: "#/components/schemas/DiffFile"
new_file:
$ref: "#/components/schemas/DiffFile"
DiffStats:
description: Aggregate line-change statistics for a diff.
type: object
required:
- additions
- deletions
properties:
additions:
type: integer
description: Total lines added.
example: 567
deletions:
type: integer
description: Total lines deleted.
example: 234
PaginatedRunFileList:
description: Paginated list of file diffs produced by a run.
type: object
required:
- data
- meta
properties:
data:
type: array
items:
$ref: "#/components/schemas/FileDiff"
meta:
$ref: "#/components/schemas/PaginationMeta"
# ── Billing Schemas ──────────────────────────────────────────────────
RunBillingStage:
description: Token counts and billed totals for a single stage within a run.
type: object
required:
- stage
- model
- billing
- runtime_secs
properties:
stage:
$ref: "#/components/schemas/BillingStageRef"
model:
$ref: "#/components/schemas/ModelReference"
billing:
$ref: "#/components/schemas/BilledTokenCounts"
runtime_secs:
type: number
description: Wall-clock runtime in seconds.
example: 154.0
RunBillingTotals:
description: Aggregate billing totals across all stages of a run.
type: object
required:
- runtime_secs
- input_tokens
- output_tokens
- total_tokens
properties:
runtime_secs:
type: number
description: Total wall-clock runtime in seconds.
example: 389.0
input_tokens:
type: integer
description: Total input tokens consumed.
example: 71540
output_tokens:
type: integer
description: Total output tokens generated.
example: 21080
total_tokens:
type: integer
description: Total tokens aggregated across all billing categories.
example: 92620
reasoning_tokens:
type: integer
description: Total reasoning tokens.
example: 3400
cache_read_tokens:
type: integer
description: Total cache read tokens.
example: 22000
cache_write_tokens:
type: integer
description: Total cache write tokens.
example: 4500
total_usd_micros:
type: integer
format: int64
nullable: true
description: Total billed USD amount in micros.
example: 2260000
BillingByModel:
description: Billing statistics grouped by model.
type: object
required:
- model
- stages
- billing
properties:
model:
$ref: "#/components/schemas/ModelReference"
stages:
type: integer
description: Number of stages that used this model.
example: 2
billing:
$ref: "#/components/schemas/BilledTokenCounts"
RunBilling:
description: Complete billing breakdown for a single run.
type: object
required:
- stages
- totals
- by_model
properties:
stages:
type: array
description: Per-stage billing breakdown.
items:
$ref: "#/components/schemas/RunBillingStage"
totals:
$ref: "#/components/schemas/RunBillingTotals"
by_model:
type: array
description: Billing grouped by model.
items:
$ref: "#/components/schemas/BillingByModel"
AggregateBilling:
description: Aggregate token counts and billed totals across all runs since server start.
type: object
required:
- totals
- by_model
properties:
totals:
$ref: "#/components/schemas/AggregateBillingTotals"
by_model:
type: array
description: Billing grouped by model.
items:
$ref: "#/components/schemas/BillingByModel"
PreviewUrlRequest:
description: Request body for generating a preview URL from a sandbox port.
type: object
required:
- port
- expires_in_secs
properties:
port:
type: integer
description: Port number exposed by the sandbox.
example: 3000
expires_in_secs:
type: integer
description: Time-to-live for the preview URL in seconds.
minimum: 1
maximum: 86400
example: 3600
signed:
type: boolean
description: When true, return a signed URL that does not require a preview token header.
default: false
PreviewUrlResponse:
description: Response containing the generated preview URL.
type: object
required:
- url
properties:
url:
type: string
description: Preview URL.
example: "https://preview.example.com/sb-a1b2c3d4/3000"
token:
type: string
description: Preview token header value for unsigned preview URLs.
example: "preview-token-123"
SshAccessRequest:
description: Request body for creating SSH access for a sandbox-backed run.
type: object
required:
- ttl_minutes
properties:
ttl_minutes:
type: number
description: Time-to-live for the SSH command in minutes.
minimum: 1
maximum: 1440
example: 60
SshAccessResponse:
description: Response containing an SSH command for the sandbox.
type: object
required:
- command
properties:
command:
type: string
description: SSH command to connect to the sandbox.
example: ssh daytona@preview.example.com -p 2222
SandboxFileEntry:
description: A directory entry in a run sandbox.
type: object
required:
- name
- is_dir
properties:
name:
type: string
description: Basename of the entry.
is_dir:
type: boolean
description: Whether the entry is a directory.
size:
type: integer
format: int64
description: File size in bytes when known.
SandboxFileListResponse:
description: Non-paginated list of sandbox directory entries.
type: object
required:
- data
properties:
data:
type: array
items:
$ref: "#/components/schemas/SandboxFileEntry"
# ── Insights Schemas ─────────────────────────────────────────────────
SavedQuery:
description: A saved SQL query for the insights editor.
type: object
required:
- id
- name
- sql
- created_at
- updated_at
properties:
id:
type: string
description: Unique query identifier.
example: "1"
name:
type: string
description: Human-readable query name.
example: Run duration by workflow
sql:
type: string
description: SQL query text.
example: "SELECT workflow_name, AVG(duration_seconds) FROM runs GROUP BY 1"
created_at:
type: string
format: date-time
description: Timestamp when the query was saved.
example: "2026-03-01T10:00:00Z"
updated_at:
type: string
format: date-time
description: Timestamp when the query was last modified.
example: "2026-03-05T14:30:00Z"
SaveQueryRequest:
description: Request body for creating or updating a saved query.
type: object
required:
- name
- sql
properties:
name:
type: string
description: Human-readable query name.
example: Run duration by workflow
sql:
type: string
description: SQL query text.
example: "SELECT workflow_name, AVG(duration_seconds) FROM runs GROUP BY 1"
ExecuteQueryRequest:
description: Request body for executing an ad-hoc SQL query.
type: object
required:
- sql
properties:
sql:
type: string
description: SQL query to execute.
example: "SELECT workflow_name, COUNT(*) FROM runs GROUP BY 1"
ExecuteQueryResponse:
description: Columnar result set from an executed query.
type: object
required:
- columns
- rows
- elapsed
- row_count
properties:
columns:
type: array
description: Column names in the result set.
items:
type: string
example: ["workflow_name", "count"]
rows:
type: array
description: Result rows, each an array of values matching the column order.
items:
type: array
items:
oneOf:
- type: string
- type: number
- type: boolean
- type: "null"
elapsed:
type: number
description: Query execution time in seconds.
example: 0.342
row_count:
type: integer
description: Number of rows returned.
example: 3
HistoryEntry:
description: A previously executed query in the history log.
type: object
required:
- id
- sql
- timestamp
- elapsed
- row_count
properties:
id:
type: string
description: Unique history entry identifier.
example: h1
sql:
type: string
description: SQL query that was executed.
example: "SELECT workflow_name, COUNT(*) FROM runs GROUP BY 1"
timestamp:
type: string
format: date-time
description: ISO 8601 timestamp of execution.
example: "2025-09-15T14:00:00Z"
elapsed:
type: number
description: Query execution time in seconds.
example: 0.342
row_count:
type: integer
description: Number of rows returned.
example: 6
# ── Settings Schemas ─────────────────────────────────────────────────
RunSettings:
description: Structured run settings mirroring fabro_types::Settings.
type: object
required:
- version
- graph
properties:
version:
type: integer
description: Settings schema version.
example: 1
goal:
type: string
description: Goal description for the run.
example: Diagnose and fix CI build failures
graph:
type: string
description: Graphviz graph filename.
example: fix_build.fabro
work_dir:
type: string
description: Working directory for the run.
llm:
$ref: "#/components/schemas/LlmSettings"
setup:
$ref: "#/components/schemas/SetupSettings"
sandbox:
$ref: "#/components/schemas/SandboxSettings"
vars:
type: object
additionalProperties:
type: string
description: Variable map for template expansion.
hooks:
type: array
items:
$ref: "#/components/schemas/HookDefinition"
LlmSettings:
description: LLM provider and model settings.
type: object
properties:
model:
type: string
description: Model identifier.
example: claude-sonnet
provider:
type: string
description: Provider name.
example: anthropic
fallbacks:
type: object
additionalProperties:
type: array
items:
type: string
description: Provider fallback chains.
SetupSettings:
description: Setup commands run before the workflow.
type: object
required:
- commands
properties:
commands:
type: array
items:
type: string
description: Shell commands to execute.
timeout_ms:
type: integer
description: Timeout per command in milliseconds.
SandboxSettings:
description: Sandbox execution environment settings.
type: object
properties:
provider:
type: string
description: Sandbox provider name.
example: daytona
preserve:
type: boolean
description: Whether to preserve the sandbox after the run.
devcontainer:
type: boolean
description: Whether to use a devcontainer for the sandbox.
daytona:
$ref: "#/components/schemas/DaytonaSettings"
local:
$ref: "#/components/schemas/LocalSandboxSettings"
env:
type: object
additionalProperties:
type: string
description: Environment variables injected into the sandbox.
LocalSandboxSettings:
description: Local sandbox settings.
type: object
properties:
worktree_mode:
type: string
description: Git worktree mode for local sandbox.
enum: [always, clean, dirty, never]
default: clean
DaytonaSettings:
description: Daytona-specific sandbox settings.
type: object
properties:
auto_stop_interval:
type: integer
description: Auto-stop interval in seconds.
labels:
type: object
additionalProperties:
type: string
description: Labels applied to the sandbox.
snapshot:
$ref: "#/components/schemas/DaytonaSnapshotSettings"
network:
description: "Network access mode: \"block\", \"allow_all\", or {\"allow_list\": [...]}."
oneOf:
- type: string
enum:
- block
- allow_all
- type: object
required:
- allow_list
properties:
allow_list:
type: array
items:
type: string
description: CIDR allowlist for network access.
skip_clone:
type: boolean
default: false
description: Skip git repo detection and cloning during initialization.
DaytonaSnapshotSettings:
description: Snapshot configuration for Daytona sandboxes.
type: object
required:
- name
properties:
name:
type: string
description: Snapshot name.
cpu:
type: integer
description: CPU cores.
memory:
type: integer
description: Memory in GB.
disk:
type: integer
description: Disk in GB.
dockerfile:
type: string
description: Dockerfile content for snapshot creation.
HookDefinition:
description: |
A single hook definition. The type discriminator and variant fields are flattened into this object.
Field-to-type mapping:
- `command`: requires `command`
- `http`: requires `url`; optional `headers`, `allowed_env_vars`, `tls`
- `prompt`: requires `prompt`; optional `model`
- `agent`: requires `prompt`; optional `model`, `max_tool_rounds`
Top-level `command` without `type` is shorthand for type=command.
type: object
required:
- event
properties:
name:
type: string
description: Human-readable hook name.
event:
type: string
description: Event that triggers this hook.
enum:
- run_start
- run_complete
- stage_start
- stage_complete
command:
type: string
description: Shell command (shorthand for type=command).
type:
type: string
description: Hook execution type.
enum:
- command
- http
- prompt
- agent
url:
type: string
description: URL for HTTP hooks.
headers:
type: object
additionalProperties:
type: string
description: Headers for HTTP hooks.
allowed_env_vars:
type: array
items:
type: string
description: Environment variables allowed in HTTP hook headers.
tls:
type: string
description: TLS verification mode for HTTP hooks.
enum:
- verify
- no_verify
- "off"
prompt:
type: string
description: Prompt text for prompt/agent hooks.
model:
type: string
description: Model for prompt/agent hooks.
max_tool_rounds:
type: integer
description: Max tool rounds for agent hooks.
matcher:
type: string
description: Regex matched against node_id or handler_type.
blocking:
type: boolean
description: Whether this hook blocks execution.
timeout_ms:
type: integer
description: Timeout in milliseconds.
sandbox:
type: boolean
description: Whether hook runs in sandbox.
ServerSettings:
description: Structured server settings mirroring fabro_types::Settings.
type: object
properties:
version:
type: integer
description: Settings schema version.
goal:
type: string
description: Default goal description.
goal_file:
type: string
description: Path to a goal file.
graph:
type: string
description: Default Graphviz graph path.
labels:
type: object
additionalProperties:
type: string
description: Default label map.
server:
type: object
properties:
target:
type: string
description: Default server target for CLI commands.
tls:
type: object
properties:
cert:
type: string
description: Client certificate path.
key:
type: string
description: Client key path.
ca:
type: string
description: Certificate authority path.
exec:
type: object
properties:
provider:
type: string
description: Default exec provider.
model:
type: string
description: Default exec model.
permissions:
type: string
enum: [read-only, read-write, full]
description: Exec permission level.
output_format:
type: string
enum: [text, json]
description: Exec output format.
prevent_idle_sleep:
type: boolean
description: Prevent system idle sleep while running.
verbose:
type: boolean
description: Enable verbose output by default.
upgrade_check:
type: boolean
description: Whether upgrade checks are enabled.
dry_run:
type: boolean
description: Default dry-run mode.
auto_approve:
type: boolean
description: Default auto-approve mode.
no_retro:
type: boolean
description: Skip retro generation by default.
storage_dir:
type: string
description: Storage directory path.
max_concurrent_runs:
type: integer
description: Maximum concurrent runs.
web:
$ref: "#/components/schemas/WebSettings"
api:
$ref: "#/components/schemas/ApiSettings"
git:
$ref: "#/components/schemas/GitSettings"
features:
$ref: "#/components/schemas/Features"
log:
$ref: "#/components/schemas/LogSettings"
work_dir:
type: string
description: Default working directory.
llm:
$ref: "#/components/schemas/LlmSettings"
setup:
$ref: "#/components/schemas/SetupSettings"
sandbox:
$ref: "#/components/schemas/SandboxSettings"
vars:
type: object
additionalProperties:
type: string
description: Default variable map.
checkpoint:
$ref: "#/components/schemas/CheckpointSettings"
pull_request:
$ref: "#/components/schemas/PullRequestSettings"
hooks:
type: array
items:
$ref: "#/components/schemas/HookDefinition"
artifacts:
$ref: "#/components/schemas/ArtifactsSettings"
mcp_servers:
type: object
additionalProperties:
$ref: "#/components/schemas/McpServerEntry"
description: Default MCP server configurations.
github:
$ref: "#/components/schemas/GitHubSettings"
fabro:
type: object
properties:
root:
type: string
description: Project fabro root directory.
SystemInfoResponse:
description: Runtime information for the active Fabro server process.
type: object
properties:
version:
type: string
description: Server version string.
git_sha:
type: string
nullable: true
description: Build git SHA when available.
build_date:
type: string
nullable: true
description: Build date when available.
os:
type: string
description: Target operating system.
arch:
type: string
description: Target CPU architecture.
storage_engine:
type: string
description: Backing run storage engine.
storage_dir:
type: string
description: Configured storage directory.
uptime_secs:
type: integer
format: int64
description: Seconds since this server process started.
runs:
$ref: "#/components/schemas/SystemRunCounts"
sandbox_provider:
type: string
description: Effective sandbox provider for launched runs.
SystemRunCounts:
description: Counts of known runs in the active server process.
type: object
properties:
total:
type: integer
format: int64
description: Total runs tracked by the server process.
active:
type: integer
format: int64
description: Runs currently queued or executing.
DiskUsageResponse:
description: Disk usage summary for server-managed data.
type: object
properties:
summary:
type: array
items:
$ref: "#/components/schemas/DiskUsageSummaryRow"
total_size_bytes:
type: integer
format: int64
description: Total size of all tracked system data.
total_reclaimable_bytes:
type: integer
format: int64
description: Total bytes reclaimable by deleting inactive runs and logs.
runs:
type: array
nullable: true
description: Per-run usage rows when verbose output is requested.
items:
$ref: "#/components/schemas/DiskUsageRunRow"
DiskUsageSummaryRow:
description: One top-level disk usage category.
type: object
properties:
type:
type: string
description: Category name, such as runs or logs.
count:
type: integer
format: int64
description: Number of items in the category.
active:
type: integer
format: int64
nullable: true
description: Number of active items when applicable.
size_bytes:
type: integer
format: int64
description: Total bytes used by the category.
reclaimable_bytes:
type: integer
format: int64
nullable: true
description: Bytes reclaimable by pruning the category.
DiskUsageRunRow:
description: Per-run disk usage information.
type: object
properties:
run_id:
type: string
description: Run identifier.
workflow_name:
type: string
description: Workflow display name.
status:
type: string
description: Current run status.
start_time:
type: string
description: Human-readable start timestamp.
size_bytes:
type: integer
format: int64
description: Size used by the run scratch directory.
reclaimable:
type: boolean
description: Whether the run is inactive and reclaimable.
PruneRunsRequest:
description: Filters for system run pruning.
type: object
properties:
dry_run:
type: boolean
description: Preview matching runs without deleting them.
default: true
before:
type: string
description: Include runs started before this YYYY-MM-DD prefix.
workflow:
type: string
description: Filter by workflow name substring.
labels:
type: object
additionalProperties:
type: string
description: Label filters applied with AND semantics.
orphans:
type: boolean
description: Include orphan run directories without run metadata.
default: false
older_than:
type: string
description: Include only runs older than this duration, such as 24h or 7d.
PruneRunsResponse:
description: Result of a prune preview or deletion.
type: object
properties:
dry_run:
type: boolean
description: Whether this response is a dry-run preview.
runs:
type: array
nullable: true
description: Matched runs when dry-run is enabled.
items:
$ref: "#/components/schemas/PruneRunEntry"
total_count:
type: integer
format: int64
description: Count of runs matching the prune filters.
total_size_bytes:
type: integer
format: int64
description: Total bytes of the matching runs.
deleted_count:
type: integer
format: int64
description: Number of runs deleted when dry-run is false.
freed_bytes:
type: integer
format: int64
description: Estimated freed bytes when deletion occurs.
PruneRunEntry:
description: One run matched by a prune preview.
type: object
properties:
run_id:
type: string
description: Run identifier.
dir_name:
type: string
description: Scratch directory name for the run.
workflow_name:
type: string
description: Workflow display name.
size_bytes:
type: integer
format: int64
description: Bytes used by the run scratch directory.
GitHubSettings:
description: GitHub App token injection configuration.
type: object
properties:
permissions:
type: object
additionalProperties:
type: string
description: GitHub API permissions to request (e.g. contents = write).
McpServerEntry:
description: MCP server connection entry.
type: object
properties:
type:
type: string
description: Transport type (stdio or http).
command:
type: array
items:
type: string
description: Command and arguments for stdio transport.
env:
type: object
additionalProperties:
type: string
description: Environment variables for stdio transport.
url:
type: string
description: URL for http transport.
headers:
type: object
additionalProperties:
type: string
description: HTTP headers for http transport.
startup_timeout_secs:
type: integer
description: Startup timeout in seconds.
tool_timeout_secs:
type: integer
description: Tool call timeout in seconds.
ArtifactsSettings:
description: Artifact collection configuration.
type: object
properties:
include:
type: array
items:
type: string
description: Glob patterns for files to collect as run artifacts.
LogSettings:
description: Logging configuration.
type: object
properties:
level:
type: string
description: Log level (e.g. trace, debug, info).
CheckpointSettings:
description: Checkpoint configuration for file exclusion.
type: object
properties:
exclude_globs:
type: array
items:
type: string
description: Glob patterns to exclude from checkpoints.
PullRequestSettings:
description: Pull request creation configuration.
type: object
properties:
enabled:
type: boolean
description: Whether to create a pull request after a successful run.
draft:
type: boolean
description: Whether to create the pull request as a draft.
auto_merge:
type: boolean
description: Whether to enable GitHub auto-merge on the created PR. Implies draft = false.
merge_strategy:
type: string
enum: [squash, merge, rebase]
description: Merge strategy for auto-merge.
WebSettings:
description: Web UI configuration.
type: object
properties:
url:
type: string
description: Web UI URL.
auth:
$ref: "#/components/schemas/AuthSettings"
AuthSettings:
description: Authentication configuration.
type: object
properties:
provider:
type: string
description: Auth provider.
enum:
- github
- insecure_disabled
allowed_usernames:
type: array
items:
type: string
description: Allowed usernames.
ApiSettings:
description: API server configuration.
type: object
properties:
base_url:
type: string
description: API base URL.
authentication_strategies:
type: array
items:
type: string
enum:
- jwt
- mtls
description: Authentication strategies.
tls:
$ref: "#/components/schemas/TlsSettings"
TlsSettings:
description: TLS certificate configuration.
type: object
required:
- cert
- key
- ca
properties:
cert:
type: string
description: Certificate file path.
key:
type: string
description: Key file path.
ca:
type: string
description: CA certificate file path.
GitSettings:
description: Git provider configuration.
type: object
properties:
provider:
type: string
description: Git provider.
enum:
- github
app_id:
type: string
description: GitHub App ID.
client_id:
type: string
description: GitHub App Client ID.
slug:
type: string
description: GitHub App slug.
author:
$ref: "#/components/schemas/GitAuthorSettings"
webhooks:
$ref: "#/components/schemas/WebhookSettings"
GitAuthorSettings:
description: Git commit author configuration.
type: object
properties:
name:
type: string
description: Author name for commits.
email:
type: string
description: Author email for commits.
WebhookSettings:
description: Webhook delivery configuration.
type: object
required:
- strategy
properties:
strategy:
type: string
description: Webhook delivery strategy.
enum:
- tailscale_funnel
Features:
description: Feature flags.
type: object
properties:
session_sandboxes:
type: boolean
description: Enable session sandboxes.
retros:
type: boolean
description: "Experimental: enable automatic retro generation after workflow runs."
# ── Discovery Schemas ────────────────────────────────────────────────
RootResponseUrls:
description: Collection of API discovery URLs.
type: object
required:
- openapi_url
- current_user_url
- health_url
properties:
openapi_url:
type: string
description: URL of the OpenAPI JSON specification.
example: /api/v1/openapi.json
current_user_url:
type: string
description: URL of the current user endpoint.
example: /api/v1/user
health_url:
type: string
description: URL of the health check endpoint.
example: /health
RootResponse:
description: API discovery response with navigation URLs.
type: object
required:
- urls
properties:
urls:
$ref: "#/components/schemas/RootResponseUrls"
HealthResponse:
description: Service health check response.
type: object
required:
- status
- version
properties:
status:
type: string
description: Health status indicator.
example: ok
version:
type: string
description: Server version string.
example: "0.176.2"
SetSecretRequest:
description: Request to store a secret value.
type: object
required:
- value
properties:
value:
type: string
description: The secret value to store.
SecretMetadata:
description: Metadata for a stored secret (value is never exposed).
type: object
required:
- name
- created_at
- updated_at
properties:
name:
type: string
description: Secret key name.
example: ANTHROPIC_API_KEY
created_at:
type: string
format: date-time
description: When the secret was first stored.
updated_at:
type: string
format: date-time
description: When the secret was last updated.
SecretListResponse:
description: List of stored secret metadata.
type: object
required:
- data
properties:
data:
type: array
items:
$ref: "#/components/schemas/SecretMetadata"
RepoCheckResponse:
description: Repository access check result.
type: object
required:
- owner
- name
- accessible
properties:
owner:
type: string
description: GitHub repository owner.
example: acme-corp
name:
type: string
description: GitHub repository name.
example: my-app
accessible:
type: boolean
description: Whether the server has read-write access to this repository.
default_branch:
type: string
nullable: true
description: Default branch name, if accessible.
example: main
private:
type: boolean
nullable: true
description: Whether the repository is private, if accessible.
permissions:
type: object
nullable: true
description: Detected permission levels.
properties:
pull:
type: boolean
push:
type: boolean
admin:
type: boolean
install_url:
type: string
nullable: true
description: GitHub App installation URL when the repo is not yet accessible.
DiagnosticsReport:
description: Server health diagnostics report.
type: object
required:
- version
- sections
properties:
version:
type: string
description: Server version.
sections:
type: array
items:
$ref: "#/components/schemas/DiagnosticsSection"
DiagnosticsSection:
type: object
required:
- title
- checks
properties:
title:
type: string
checks:
type: array
items:
$ref: "#/components/schemas/DiagnosticsCheck"
DiagnosticsCheck:
type: object
required:
- name
- status
- summary
properties:
name:
type: string
status:
type: string
enum:
- pass
- warning
- error
summary:
type: string
details:
type: array
items:
$ref: "#/components/schemas/DiagnosticsDetail"
remediation:
type: string
nullable: true
DiagnosticsDetail:
type: object
required:
- text
- warn
properties:
text:
type: string
warn:
type: boolean
UserResponse:
description: Information about the authenticated user.
type: object
required:
- login
properties:
login:
type: string
description: User's login identifier (e.g. GitHub username).
example: octocat
Reference in a new issue View git blame Copy permalink