scriptoriumadmin/fabro
1
0
Fork 0
mirror of https://github.com/fabro-sh/fabro.git synced 2026-08-28 05:27:41 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
fabro/docs/api-reference/fabro-api.yaml
Bryan Helmkamp ecdfdd82d8
feat(install): add browser-based setup flow 
Implement the web-first install experience across the server, CLI, API spec,
web app, and packaged SPA assets.

This also removes test-side process env mutation by pushing env-dependent
decision points behind explicit helpers and test wiring.
2026-04-19 11:20:58 -04:00

4954 lines
143 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: Install
description: First-run browser install workflow
- 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: []
- SessionCookie: []
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"
/install/session:
get:
operationId: getInstallSession
tags: [Install]
summary: Get install session
description: >
Returns the current browser-install session snapshot. Requires the one-time
install token in `Authorization: Bearer`, `?token=`, or `X-Install-Token`.
security: []
responses:
"200":
description: Current install session state
content:
application/json:
schema:
$ref: "#/components/schemas/InstallSessionResponse"
"401":
description: Invalid or missing install token
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/install/llm/test:
post:
operationId: testInstallLlmCredentials
tags: [Install]
summary: Validate install LLM credentials
description: Validates an LLM API key without persisting it. Requires the one-time install token.
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/InstallLlmTestInput"
responses:
"200":
description: Credentials validated successfully
content:
application/json:
schema:
$ref: "#/components/schemas/InstallLlmValidationResponse"
"401":
description: Invalid or missing install token
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"422":
description: Credential validation failed
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/install/llm:
put:
operationId: putInstallLlm
tags: [Install]
summary: Save install LLM settings
description: Records the LLM providers and API keys chosen during the browser install. Requires the one-time install token.
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/InstallLlmProvidersInput"
responses:
"204":
description: LLM settings recorded
"401":
description: Invalid or missing install token
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"422":
description: Invalid install input
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/install/server:
put:
operationId: putInstallServer
tags: [Install]
summary: Save install server configuration
description: Records the canonical server URL confirmed by the operator. Requires the one-time install token.
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/InstallServerConfigInput"
responses:
"204":
description: Server configuration recorded
"401":
description: Invalid or missing install token
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"422":
description: Invalid canonical URL
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/install/github/token/test:
post:
operationId: testInstallGithubToken
tags: [Install]
summary: Validate install GitHub token
description: Validates a GitHub personal access token without persisting it. Requires the one-time install token.
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/InstallGithubTokenTestInput"
responses:
"200":
description: GitHub token validated successfully
content:
application/json:
schema:
$ref: "#/components/schemas/InstallGithubTokenTestResponse"
"401":
description: Invalid or missing install token
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"422":
description: GitHub token validation failed
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/install/github/token:
put:
operationId: putInstallGithubToken
tags: [Install]
summary: Save install GitHub token
description: Records the GitHub personal access token chosen during the browser install. Requires the one-time install token.
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/InstallGithubTokenInput"
responses:
"204":
description: GitHub token recorded
"401":
description: Invalid or missing install token
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"422":
description: Invalid install input
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/install/github/app/manifest:
post:
operationId: createInstallGithubAppManifest
tags: [Install]
summary: Build install GitHub App manifest
description: Builds the GitHub App manifest and stores the temporary callback state for the browser install. Requires the one-time install token.
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/InstallGithubAppManifestInput"
responses:
"200":
description: GitHub App manifest ready for browser handoff
content:
application/json:
schema:
$ref: "#/components/schemas/InstallGithubAppManifestResponse"
"401":
description: Invalid or missing install token
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"422":
description: Invalid install input or missing prior steps
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/install/github/app/redirect:
get:
operationId: completeInstallGithubAppRedirect
tags: [Install]
summary: Complete install GitHub App redirect
description: Manifest-conversion callback target used by GitHub during browser install. Authorized by the callback `state` query parameter rather than the install token.
security: []
parameters:
- name: code
in: query
required: true
schema:
type: string
- name: state
in: query
required: true
schema:
type: string
responses:
"302":
description: Browser redirected back into the install SPA
"400":
description: Invalid or expired GitHub App callback state
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"502":
description: GitHub manifest conversion failed
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/install/finish:
post:
operationId: finishInstall
tags: [Install]
summary: Finalize browser install
description: Persists settings, runtime secrets, and install outputs, then schedules the install-mode process to exit cleanly. Requires the one-time install token.
security: []
responses:
"202":
description: Install persisted successfully; restart handoff in progress
content:
application/json:
schema:
$ref: "#/components/schemas/InstallFinishResponse"
"401":
description: Invalid or missing install token
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"422":
description: Install session is incomplete
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"500":
description: Install persistence failed
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/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 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
"400":
description: Invalid manifest or workflow
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"
/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 vault secrets
description: Returns workflow-visible vault secret names and timestamps. Secret values are never exposed.
responses:
"200":
description: Secret metadata list
content:
application/json:
schema:
$ref: "#/components/schemas/SecretListResponse"
post:
operationId: createSecret
tags: [Secrets]
summary: Store or update a vault secret
description: Stores a secret in the workflow-visible vault. Anything stored here may be used by workflows.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateSecretRequest"
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: deleteSecretByName
tags: [Secrets]
summary: Delete a vault secret
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/DeleteSecretRequest"
responses:
"204":
description: Secret deleted
"400":
description: Invalid secret name or request body
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 server settings view selected by the optional `view` query
parameter. `view=layer` (the default) returns the current sparse
redacted `SettingsLayer` payload. `view=resolved` returns the server's
dense resolved settings payload after applying the same redaction
policy.
parameters:
- $ref: "#/components/parameters/SettingsView"
responses:
"200":
description: Server settings
headers:
X-Fabro-Settings-View:
description: Present with value `resolved` when the response body is the dense resolved settings view.
schema:
type: string
enum: [resolved]
content:
application/json:
schema:
$ref: "#/components/schemas/ServerSettings"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: opaque
description: >
Raw dev token passed as `Authorization: Bearer fabro_dev_...` when
`server.auth.methods` includes `dev-token`.
SessionCookie:
type: apiKey
in: cookie
name: __fabro_session
description: >
Private session cookie issued after a successful web login. The server
verifies and decodes the cookie before authenticating the request.
parameters:
RunId:
name: id
in: path
required: true
description: Unique run identifier (ULID).
schema:
type: string
example: 01JNQVR7M0EJ5GKAT2SC4ERS1Z
SettingsView:
name: view
in: query
required: false
description: Selects the server settings representation to return.
schema:
type: string
enum: [layer, resolved]
default: layer
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:
InstallSessionResponse:
description: Current browser-install session snapshot with secrets redacted.
type: object
required:
- completed_steps
- prefill
properties:
completed_steps:
type: array
items:
type: string
llm:
oneOf:
- $ref: "#/components/schemas/InstallLlmSummary"
- type: "null"
server:
oneOf:
- $ref: "#/components/schemas/InstallServerConfigInput"
- type: "null"
github:
oneOf:
- $ref: "#/components/schemas/InstallGithubSummary"
- type: "null"
prefill:
$ref: "#/components/schemas/InstallPrefill"
InstallPrefill:
description: Server-detected defaults used to prefill the browser install wizard.
type: object
required:
- canonical_url
properties:
canonical_url:
type: string
format: uri
InstallLlmValidationResponse:
description: Successful response from install-time LLM credential validation.
type: object
required:
- ok
properties:
ok:
type: boolean
example: true
InstallLlmTestInput:
description: Input for install-time LLM credential validation.
type: object
required:
- provider
- api_key
properties:
provider:
type: string
example: anthropic
api_key:
type: string
openai_base_url:
type: string
format: uri
description: Optional override base URL used for OpenAI-style providers during install.
InstallLlmProvidersInput:
description: LLM providers selected during browser install.
type: object
required:
- providers
properties:
providers:
type: array
minItems: 1
items:
$ref: "#/components/schemas/InstallLlmProviderInput"
InstallLlmProviderInput:
description: One persisted LLM provider configuration collected during browser install.
type: object
required:
- provider
- api_key
properties:
provider:
type: string
example: anthropic
api_key:
type: string
openai_base_url:
type: string
format: uri
InstallLlmSummary:
description: Redacted summary of persisted LLM install choices.
type: object
properties:
providers:
type: array
items:
type: object
required:
- provider
- configured
properties:
provider:
type: string
configured:
type: boolean
openai_base_url:
type: string
format: uri
InstallServerConfigInput:
description: Canonical server URL confirmed during browser install.
type: object
required:
- canonical_url
properties:
canonical_url:
type: string
format: uri
InstallGithubTokenTestInput:
description: Input for install-time GitHub token validation.
type: object
required:
- token
properties:
token:
type: string
InstallGithubTokenTestResponse:
description: Successful response from install-time GitHub token validation.
type: object
required:
- username
properties:
username:
type: string
InstallGithubTokenInput:
description: GitHub personal access token chosen during browser install.
type: object
required:
- token
- username
properties:
token:
type: string
username:
type: string
InstallGithubAppManifestInput:
description: Input required to build the browser-install GitHub App manifest.
type: object
required:
- owner
- app_name
- allowed_username
properties:
owner:
type: string
description: >
Either `personal` or `org:<slug>`.
app_name:
type: string
allowed_username:
type: string
InstallGithubAppManifestResponse:
description: Browser handoff payload for the GitHub App creation flow.
type: object
required:
- manifest
- github_form_action
properties:
manifest:
type: object
additionalProperties: true
github_form_action:
type: string
format: uri
InstallGithubSummary:
description: Redacted summary of the GitHub install strategy selected during browser install.
type: object
required:
- strategy
properties:
strategy:
type: string
enum: [token, app]
username:
type: string
owner:
type: string
app_name:
type: string
slug:
type: string
allowed_username:
type: string
InstallFinishResponse:
description: Response returned after install outputs are persisted successfully.
type: object
required:
- status
- restart_url
- dev_token
properties:
status:
type: string
enum: [completing]
restart_url:
type: string
format: uri
dev_token:
type: string
# ── 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", "null"]
format: int64
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", "null"]
format: double
description: Cost per million input tokens in USD.
example: 15.0
output_cost_per_mtok:
type: ["number", "null"]
format: double
description: Cost per million output tokens in USD.
example: 75.0
cache_input_cost_per_mtok:
type: ["number", "null"]
format: double
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", "null"]
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", "null"]
format: double
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
- skip
description: Whether the model responded successfully, failed, or was skipped because its provider is not configured.
error_message:
type: ["string", "null"]
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", "null"]
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", "null"]
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", "null"]
source:
type: ["string", "null"]
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", "null"]
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
RenderWorkflowGraphDirection:
type: string
enum:
- lr
- tb
PreflightWorkflowSummary:
type: object
required:
- name
- nodes
- edges
- goal
- diagnostics
properties:
name:
type: string
graph_path:
type: ["string", "null"]
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", "null"]
edge:
type: ["array", "null"]
minItems: 2
maxItems: 2
items:
type: string
fix:
type: ["string", "null"]
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", "null"]
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:
oneOf:
- $ref: "#/components/schemas/StatusReason"
- type: "null"
pending_control:
oneOf:
- $ref: "#/components/schemas/RunControlAction"
- type: "null"
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", "null"]
format: double
description: Timeout for the question when configured by the workflow.
example: 30
context_display:
type: ["string", "null"]
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"
ActorKind:
description: High-level category of an event actor.
type: string
enum:
- user
- agent
- system
ActorRef:
description: >
Optional primary actor associated with a run event. Present on control
actions and durable agent output where a stable user or agent identity
matters; omitted on routine runtime lifecycle events.
type: object
required:
- kind
properties:
kind:
$ref: "#/components/schemas/ActorKind"
id:
type: string
description: Stable actor identifier when available.
display:
type: string
description: Display-friendly label for the actor.
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", "null"]
node_label:
type: ["string", "null"]
stage_id:
type: ["string", "null"]
description: Stage execution identity, formatted as "{node_id}@{visit}".
parallel_group_id:
type: ["string", "null"]
description: >
Durable identity of one execution of a parallel node, formatted as
"{node_id}@{visit}".
parallel_branch_id:
type: ["string", "null"]
description: >
Durable identity of one branch within a parallel execution,
formatted as "{parallel_group_id}:{index}".
session_id:
type: ["string", "null"]
parent_session_id:
type: ["string", "null"]
tool_call_id:
type: ["string", "null"]
description: >
Stable identifier for a tool call, present on agent.tool.* events
and other durable events that directly describe the same tool
call.
actor:
oneOf:
- $ref: "#/components/schemas/ActorRef"
- type: "null"
event:
type: string
description: Event type discriminator.
example: stage.started
properties:
type: object
additionalProperties: true
additionalProperties: true
EventSeq:
description: Assigned sequence number component of a stored event envelope.
type: object
required:
- seq
properties:
seq:
type: integer
description: Assigned event sequence number.
example: 42
EventEnvelope:
description: >
Stored event envelope with assigned sequence number. On the wire the
envelope is flattened: seq sits alongside the RunEvent payload fields
at the top level of the JSON object.
allOf:
- $ref: "#/components/schemas/EventSeq"
- $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", "null"]
description: Optional lowercase hex SHA-256 checksum for the file contents.
example: 3f785df4c5b7d3f1f4c1f0ecb0f55f1d9f6f6a3d9f0a8a98f7a74f29d1f81a2c
expected_bytes:
type: ["integer", "null"]
format: int64
minimum: 0
description: Optional exact byte length expected for the file part.
example: 1234
content_type:
type: ["string", "null"]
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", "null"]
failure_reason:
type: ["string", "null"]
timestamp:
type: string
format: date-time
NodeState:
description: Internal node projection state.
type: object
properties:
prompt:
type: ["string", "null"]
response:
type: ["string", "null"]
status:
oneOf:
- $ref: "#/components/schemas/NodeStatusRecord"
- type: "null"
provider_used: {}
diff:
type: ["string", "null"]
script_invocation: {}
script_timing: {}
parallel_results: {}
stdout:
type: ["string", "null"]
stderr:
type: ["string", "null"]
RunProjection:
description: Raw internal run projection derived from the event log.
type: object
required:
- nodes
properties:
run:
type: ["object", "null"]
additionalProperties: true
graph_source:
type: ["string", "null"]
start:
type: ["object", "null"]
additionalProperties: 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", "null"]
additionalProperties: true
retro:
type: ["object", "null"]
additionalProperties: true
retro_prompt:
type: ["string", "null"]
retro_response:
type: ["string", "null"]
sandbox:
type: ["object", "null"]
additionalProperties: true
final_patch:
type: ["string", "null"]
pull_request:
type: ["object", "null"]
additionalProperties: 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", "null"]
workflow_slug:
type: ["string", "null"]
goal:
type: ["string", "null"]
labels:
type: object
additionalProperties:
type: string
host_repo_path:
type: ["string", "null"]
start_time:
type: ["string", "null"]
format: date-time
status:
type: ["string", "null"]
status_reason:
type: ["string", "null"]
pending_control:
oneOf:
- $ref: "#/components/schemas/RunControlAction"
- type: "null"
duration_ms:
type: ["integer", "null"]
format: int64
minimum: 0
total_usd_micros:
type: ["integer", "null"]
format: int64
# ── Run Board Schemas ────────────────────────────────────────────────
BoardColumn:
description: Board column status for a run in the list view.
type: string
enum:
- working
- initializing
- 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", "null"]
format: int64
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", "null"]
format: int64
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", "null"]
format: int64
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 ─────────────────────────────────────────────────
ServerSettings:
description: |
Redacted server settings payload.
The `/api/v1/settings` endpoint supports two response shapes:
- `view=layer` (default): the sparse redacted `SettingsLayer` shape
- `view=resolved`: the dense resolved `Settings` shape
Both views drop the same exact operational path:
- `server.listen`
For non-redacted `InterpString` fields, the wire payload preserves the
unresolved source/template string rather than any environment-resolved
secret value.
type: object
additionalProperties: true
RunSettings:
description: |
The merged, persisted v2 `[run]` subtree for a specific run, serialized
as the wrapping `SettingsFile` shape (so `settings.run.*` holds the run
config). Matches `fabro_types::settings::SettingsFile` minus secret
subtrees, identical to ServerSettings' redaction rules.
See `lib/crates/fabro-types/src/settings/run.rs` for the full type.
type: object
additionalProperties: true
SystemInfoResponse:
description: Runtime information for the active Fabro server process.
type: object
properties:
version:
type: string
description: Server version string.
git_sha:
type: ["string", "null"]
description: Build git SHA when available.
build_date:
type: ["string", "null"]
description: Build date when available.
profile:
type: ["string", "null"]
description: Cargo build profile (e.g. `release`, `debug`) 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.
features:
$ref: "#/components/schemas/SystemFeatures"
SystemFeatures:
description: Server-level capability flags.
type: object
properties:
session_sandboxes:
type: boolean
description: Whether session sandboxes are enabled.
retros:
type: boolean
description: Whether workflow retros are enabled.
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", "null"]
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", "null"]
format: int64
description: Number of active items when applicable.
size_bytes:
type: integer
format: int64
description: Total bytes used by the category.
reclaimable_bytes:
type: ["integer", "null"]
format: int64
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", "null"]
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.
# ── 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
properties:
status:
type: string
description: Health status indicator.
example: ok
SecretType:
description: The way a secret is consumed by the sandbox.
type: string
enum:
- environment
- file
- credential
CreateSecretRequest:
description: Request to store or update a secret.
type: object
required:
- name
- value
- type
properties:
name:
type: string
description: Secret name or destination path for file secrets.
value:
type: string
description: The secret value to store.
type:
$ref: "#/components/schemas/SecretType"
description:
type: string
description: Optional operator-facing description of the secret.
DeleteSecretRequest:
description: Request to delete a secret by name.
type: object
required:
- name
properties:
name:
type: string
description: Secret name or destination path for file secrets.
SecretMetadata:
description: Metadata for a stored secret (value is never exposed).
type: object
required:
- name
- type
- created_at
- updated_at
properties:
name:
type: string
description: Secret key name or destination path.
example: ANTHROPIC_API_KEY
type:
$ref: "#/components/schemas/SecretType"
description:
type: string
description: Optional operator-facing description of the secret.
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", "null"]
description: Default branch name, if accessible.
example: main
private:
type: ["boolean", "null"]
description: Whether the repository is private, if accessible.
permissions:
type: ["object", "null"]
description: Detected permission levels.
properties:
pull:
type: boolean
push:
type: boolean
admin:
type: boolean
install_url:
type: ["string", "null"]
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", "null"]
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