mirror of
https://github.com/fabro-sh/fabro.git
synced 2026-08-28 05:27:41 +00:00
5fc9157017
## Summary Removes Fabro's automatic retro generation stage so workflow runs go directly from execution to finalization and optional PR creation. This drops the retro-specific crate, events, projection fields, config/API knobs, and user-facing docs in favor of the existing durable run observability surfaces. ## What Changed - Deleted the `fabro-retro` crate and the workflow `retro` pipeline phase, with finalization now consuming `Executed` state directly. - Removed retro configuration and API surface area, including `--no-retro`, `[run.execution].retros`, manifest `no_retro`, `features.retros`, and run projection `retro*` fields. - Retired typed `retro.*` events while keeping historical event logs readable by deserializing retired retro event names as `Unknown`. - Stopped appending retro sections to generated PR bodies and updated docs, marketing copy, screenshots, and navigation to point users toward observability/event-stream inspection. ## Testing Not run during PR creation; this branch already contained the implementation commit. --- [](https://github.com/EveryInc/compound-engineering-plugin) 🤖 Generated with GPT-5 (unknown context, reasoning unspecified) via [Codex](https://openai.com/codex)
8960 lines
259 KiB
YAML
8960 lines
259 KiB
YAML
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: Integrations
|
|
description: External provider callbacks and integration endpoints
|
|
- name: Auth
|
|
description: Browser authentication and demo-mode controls
|
|
- 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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"422":
|
|
description: Credential validation failed
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"422":
|
|
description: Invalid install input
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"422":
|
|
description: Invalid canonical URL
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/install/object-store/test:
|
|
post:
|
|
operationId: testInstallObjectStore
|
|
tags: [Install]
|
|
summary: Validate install object-store configuration
|
|
description: Validates the browser-install object-store selection without persisting it. Requires the one-time install token.
|
|
security: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/InstallObjectStoreInput"
|
|
responses:
|
|
"200":
|
|
description: Object-store configuration validated successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/InstallObjectStoreValidationResponse"
|
|
"401":
|
|
description: Invalid or missing install token
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"422":
|
|
description: Object-store validation failed
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/install/object-store:
|
|
put:
|
|
operationId: putInstallObjectStore
|
|
tags: [Install]
|
|
summary: Save install object-store configuration
|
|
description: Records the object-store mode selected during browser install. Requires the one-time install token.
|
|
security: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/InstallObjectStoreInput"
|
|
responses:
|
|
"204":
|
|
description: Object-store configuration recorded
|
|
"401":
|
|
description: Invalid or missing install token
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"422":
|
|
description: Invalid install input
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/install/sandbox/test:
|
|
post:
|
|
operationId: testInstallSandbox
|
|
tags: [Install]
|
|
summary: Validate install sandbox configuration
|
|
description: Validates the browser-install sandbox-provider selection without persisting it. For Daytona, performs a cheap authenticated call against the Daytona SDK to verify the API key. For Docker, returns ok without further checks. Requires the one-time install token.
|
|
security: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/InstallSandboxInput"
|
|
responses:
|
|
"200":
|
|
description: Sandbox configuration validated successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/InstallSandboxValidationResponse"
|
|
"401":
|
|
description: Invalid or missing install token
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"422":
|
|
description: Sandbox validation failed
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/install/sandbox:
|
|
put:
|
|
operationId: putInstallSandbox
|
|
tags: [Install]
|
|
summary: Save install sandbox configuration
|
|
description: Records the sandbox provider selected during browser install. Requires the one-time install token.
|
|
security: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/InstallSandboxInput"
|
|
responses:
|
|
"204":
|
|
description: Sandbox configuration recorded
|
|
"401":
|
|
description: Invalid or missing install token
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"422":
|
|
description: Invalid install input
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"422":
|
|
description: GitHub token validation failed
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"422":
|
|
description: Invalid install input
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"422":
|
|
description: Invalid install input or missing prior steps
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"502":
|
|
description: GitHub manifest conversion failed
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"422":
|
|
description: Install session is incomplete
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"500":
|
|
description: Install persistence failed
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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/webhooks/github:
|
|
post:
|
|
operationId: receiveGithubWebhook
|
|
tags: [Integrations]
|
|
summary: Receive GitHub Webhook
|
|
description: Receives GitHub App webhook deliveries. Requests are authenticated by `X-Hub-Signature-256`, not API bearer auth.
|
|
security: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: true
|
|
responses:
|
|
"200":
|
|
description: Webhook accepted
|
|
"401":
|
|
description: Missing or invalid webhook signature
|
|
|
|
/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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
# ── Auth ─────────────────────────────────────────────────────────────
|
|
|
|
/api/v1/auth/config:
|
|
get:
|
|
operationId: getAuthConfig
|
|
tags: [Auth]
|
|
summary: Retrieve auth configuration
|
|
description: Returns the browser login methods enabled for this server.
|
|
security: []
|
|
responses:
|
|
"200":
|
|
description: Enabled authentication methods
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AuthConfigResponse"
|
|
|
|
/api/v1/auth/me:
|
|
get:
|
|
operationId: getAuthMe
|
|
tags: [Auth]
|
|
summary: Retrieve current browser user
|
|
description: Returns the authenticated browser session user and demo-mode state.
|
|
responses:
|
|
"200":
|
|
description: Current authenticated browser user
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AuthMeResponse"
|
|
"401":
|
|
description: Not authenticated
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/api/v1/demo/toggle:
|
|
post:
|
|
operationId: toggleDemo
|
|
tags: [Auth]
|
|
summary: Toggle browser demo mode
|
|
description: Enables or disables demo-mode routing for the current browser session.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/DemoToggleRequest"
|
|
responses:
|
|
"200":
|
|
description: Demo-mode state updated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/DemoToggleResponse"
|
|
"401":
|
|
description: Not authenticated
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/auth/login/dev-token:
|
|
post:
|
|
operationId: loginDevToken
|
|
tags: [Auth]
|
|
summary: Login with development token
|
|
description: Creates a browser session from an enabled development token.
|
|
security: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/DevTokenLoginRequest"
|
|
responses:
|
|
"200":
|
|
description: Browser session created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/DevTokenLoginResponse"
|
|
"401":
|
|
description: Invalid or disabled development token
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"409":
|
|
description: Session secret is not configured
|
|
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. Archived runs are hidden by default; pass `include_archived=true` to include them in the response.
|
|
parameters:
|
|
- $ref: "#/components/parameters/PageLimit"
|
|
- $ref: "#/components/parameters/PageOffset"
|
|
- $ref: "#/components/parameters/IncludeArchived"
|
|
responses:
|
|
"200":
|
|
description: Paginated durable run summaries
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PaginatedRunList"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/api/v1/runs/resolve:
|
|
get:
|
|
operationId: resolveRun
|
|
tags: [Runs]
|
|
summary: Resolve Run Selector
|
|
description: Resolves a run selector to one durable run summary using server-owned selector semantics.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunSelector"
|
|
responses:
|
|
"200":
|
|
description: Durable run summary
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RunSummary"
|
|
"400":
|
|
description: Selector is invalid or ambiguous
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"404":
|
|
description: No run matched the selector
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/api/v1/preflight:
|
|
post:
|
|
operationId: runPreflight
|
|
tags: [Runs]
|
|
summary: Validate Workflow Manifest
|
|
description: Validates runtime readiness for 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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/api/v1/validate:
|
|
post:
|
|
operationId: validateRunManifest
|
|
tags: [Runs]
|
|
summary: Validate Workflow Manifest
|
|
description: Validates workflow structure and diagnostics without runtime readiness checks.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RunManifest"
|
|
responses:
|
|
"200":
|
|
description: Validation result
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ValidateResponse"
|
|
"400":
|
|
description: Invalid manifest or workflow
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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/RunSummary"
|
|
"404":
|
|
description: Run not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
delete:
|
|
operationId: deleteRun
|
|
tags: [Runs]
|
|
summary: Delete Run
|
|
description: Deletes durable store state, local run scratch data, and the run-owned sandbox unless sandbox preservation is enabled. Active runs require `force=true`.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
- $ref: "#/components/parameters/ForceRunDelete"
|
|
responses:
|
|
"200":
|
|
description: Run deleted and sandbox preservation details returned
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/DeleteRunResponse"
|
|
"204":
|
|
description: Run deleted or already absent
|
|
"404":
|
|
description: Run not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"409":
|
|
description: Run is active and requires `force=true`
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"409":
|
|
description: Run is not running
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/api/v1/runs/{id}/steer:
|
|
post:
|
|
operationId: steerRun
|
|
tags: [Human-in-the-Loop]
|
|
summary: Steer Run
|
|
description: |
|
|
Send a mid-run steering message to the live agent session(s) of a
|
|
running run. Set `interrupt=true` to atomically interrupt the active
|
|
API-mode agent round first, then deliver this message as the next
|
|
user turn. Without `interrupt=true`, the message is appended to the
|
|
steering queue and may buffer until the next API-mode agent session.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SteerRunRequest"
|
|
responses:
|
|
"202":
|
|
description: Steer accepted and forwarded to the worker
|
|
"400":
|
|
description: Invalid request body
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"404":
|
|
description: Run not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"409":
|
|
description: |
|
|
Run is not currently steerable. Returned when the run is in a
|
|
terminal state, blocked (use the answer endpoint instead), or
|
|
all currently running agent stages are CLI-mode.
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"503":
|
|
description: Worker control channel unavailable
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/api/v1/runs/{id}/interrupt:
|
|
post:
|
|
operationId: interruptRun
|
|
tags: [Human-in-the-Loop]
|
|
summary: Interrupt Run
|
|
description: |
|
|
Interrupt the active API-mode agent round without sending steering
|
|
text. The agent keeps its steering lease and waits for a later steer
|
|
message before starting another LLM round.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
responses:
|
|
"202":
|
|
description: Interrupt accepted and forwarded to the worker
|
|
"404":
|
|
description: Run not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"409":
|
|
description: |
|
|
Run is not currently interruptible. Returned when the run is in a
|
|
terminal state, blocked (use the answer endpoint instead), has no
|
|
active API-mode agent session, or all currently running agent
|
|
stages are CLI-mode.
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"503":
|
|
description: Worker control channel unavailable
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"409":
|
|
description: Run is not in submitted status
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"409":
|
|
description: Run is not running
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"409":
|
|
description: Run is not paused
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/api/v1/runs/{id}/archive:
|
|
post:
|
|
operationId: archiveRun
|
|
tags: [Runs]
|
|
summary: Archive Run
|
|
description: >
|
|
Marks a terminal run (`succeeded`, `failed`, or `dead`) as `archived`.
|
|
Archived runs are hidden from default listings and are read-only until
|
|
unarchived. Idempotent on already-archived runs. Returns 409 if the run
|
|
is not terminal.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
responses:
|
|
"200":
|
|
description: Run archived (or already archived)
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RunStatusResponse"
|
|
"404":
|
|
description: Run not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"409":
|
|
description: Run is not terminal and cannot be archived
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/api/v1/runs/{id}/rewind:
|
|
post:
|
|
operationId: rewindRun
|
|
tags: [Runs]
|
|
summary: Rewind Run
|
|
description: >
|
|
Creates a new run from an earlier checkpoint of a terminal source run,
|
|
archives the source run, and records `run.superseded_by` on the source
|
|
after archive succeeds. Returns 207 when the new run was created but
|
|
the source archive step failed.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RewindRequest"
|
|
responses:
|
|
"200":
|
|
description: Source archived and new run created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RewindResponse"
|
|
"207":
|
|
description: New run created but source archive failed
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RewindResponse"
|
|
"400":
|
|
description: Invalid rewind target
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"404":
|
|
description: Run not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"409":
|
|
description: Source run is archived or is not terminal
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"501":
|
|
description: Operation unsupported for this run
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/api/v1/runs/{id}/fork:
|
|
post:
|
|
operationId: forkRun
|
|
tags: [Runs]
|
|
summary: Fork Run
|
|
description: >
|
|
Creates a new run from a checkpoint of the source run. The source run
|
|
is left untouched.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ForkRequest"
|
|
responses:
|
|
"200":
|
|
description: New run created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ForkResponse"
|
|
"400":
|
|
description: Invalid fork target
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"404":
|
|
description: Run not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"409":
|
|
description: Source run is archived
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"501":
|
|
description: Operation unsupported for this run
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/api/v1/runs/{id}/timeline:
|
|
get:
|
|
operationId: getRunTimeline
|
|
tags: [Runs]
|
|
summary: Get Run Timeline
|
|
description: >
|
|
Returns checkpoint timeline entries from durable run-store checkpoints.
|
|
Metadata branches are write-only archives and are not read by this endpoint.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
responses:
|
|
"200":
|
|
description: Run checkpoint timeline
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/TimelineEntryResponse"
|
|
"404":
|
|
description: Run not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"501":
|
|
description: Operation unsupported for this run
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/api/v1/runs/{id}/unarchive:
|
|
post:
|
|
operationId: unarchiveRun
|
|
tags: [Runs]
|
|
summary: Unarchive Run
|
|
description: >
|
|
Restores an archived run to its prior terminal status. Idempotent on
|
|
runs that are terminal but not archived (returns the current status
|
|
without emitting an event). Returns 409 if the run is active.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
responses:
|
|
"200":
|
|
description: Run unarchived (or already not archived)
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RunStatusResponse"
|
|
"404":
|
|
description: Run not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"409":
|
|
description: Run is active and cannot be unarchived
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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"
|
|
- name: direction
|
|
in: query
|
|
required: false
|
|
description: Optional Graphviz rank direction override for the rendered graph.
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- LR
|
|
- TB
|
|
- BT
|
|
- RL
|
|
responses:
|
|
"200":
|
|
description: SVG image of the workflow graph
|
|
content:
|
|
image/svg+xml:
|
|
schema:
|
|
type: string
|
|
"404":
|
|
description: Run not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/api/v1/runs/{id}/graph/source:
|
|
get:
|
|
operationId: retrieveRunGraphSource
|
|
tags: [Runs]
|
|
summary: Retrieve Graphviz DOT source
|
|
description: Returns the raw Graphviz DOT source for the workflow graph (the contents of the workflow's `.fabro` file).
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
responses:
|
|
"200":
|
|
description: Graphviz DOT source
|
|
content:
|
|
text/vnd.graphviz:
|
|
schema:
|
|
type: string
|
|
"404":
|
|
description: Run not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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. Archived runs are hidden by default; pass `include_archived=true` to include them under the `archived` column.
|
|
parameters:
|
|
- $ref: "#/components/parameters/PageLimit"
|
|
- $ref: "#/components/parameters/PageOffset"
|
|
- $ref: "#/components/parameters/IncludeArchived"
|
|
responses:
|
|
"200":
|
|
description: Paginated list of runs for the board view
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PaginatedBoardRunList"
|
|
|
|
/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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/api/v1/runs/{id}/logs:
|
|
get:
|
|
operationId: getRunLogs
|
|
tags: [Run Internals]
|
|
summary: Get Run Logs
|
|
description: Returns the worker tracing log for a run when it is available.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
responses:
|
|
"200":
|
|
description: Per-run worker tracing log
|
|
content:
|
|
text/plain; charset=utf-8:
|
|
schema:
|
|
type: string
|
|
"404":
|
|
description: Run not found, or no run log has been written yet
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/api/v1/runs/{id}/pull_request:
|
|
post:
|
|
operationId: createRunPullRequest
|
|
tags: [Runs]
|
|
summary: Create Run Pull Request
|
|
description: Creates a pull request for a completed run on GitHub and persists the record on the server.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CreateRunPullRequestRequest"
|
|
responses:
|
|
"200":
|
|
description: Pull request created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PullRequestRecord"
|
|
"400":
|
|
description: Pull request creation does not apply to this run
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"404":
|
|
description: Run not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"409":
|
|
description: >-
|
|
Pull request already exists for this run. Clients can GET
|
|
/runs/{id}/pull_request to retrieve the stored record.
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"502":
|
|
description: GitHub rejected the pull request creation request
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"503":
|
|
description: GitHub integration is unavailable on the server
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
get:
|
|
operationId: getRunPullRequest
|
|
tags: [Runs]
|
|
summary: Get Run Pull Request
|
|
description: Returns the stored pull request record for a run plus live GitHub details.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
responses:
|
|
"200":
|
|
description: Pull request detail
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PullRequestDetail"
|
|
"400":
|
|
description: Pull request lookup does not apply to this run
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"404":
|
|
description: Run or stored pull request record not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"502":
|
|
description: Stored pull request record exists but GitHub could not find it
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"503":
|
|
description: GitHub integration is unavailable on the server
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/api/v1/runs/{id}/pull_request/merge:
|
|
post:
|
|
operationId: mergeRunPullRequest
|
|
tags: [Runs]
|
|
summary: Merge Run Pull Request
|
|
description: Merges the stored pull request for a run on GitHub.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/MergeRunPullRequestRequest"
|
|
responses:
|
|
"200":
|
|
description: Pull request merged
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/MergeRunPullRequestResponse"
|
|
"400":
|
|
description: Pull request merge does not apply to this run
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"404":
|
|
description: Run or stored pull request record not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"502":
|
|
description: GitHub rejected the merge request
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"503":
|
|
description: GitHub integration is unavailable on the server
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/api/v1/runs/{id}/pull_request/close:
|
|
post:
|
|
operationId: closeRunPullRequest
|
|
tags: [Runs]
|
|
summary: Close Run Pull Request
|
|
description: Closes the stored pull request for a run on GitHub.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
responses:
|
|
"200":
|
|
description: Pull request closed
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloseRunPullRequestResponse"
|
|
"400":
|
|
description: Pull request close does not apply to this run
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"404":
|
|
description: Run or stored pull request record not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"502":
|
|
description: GitHub rejected the close request
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"503":
|
|
description: GitHub integration is unavailable on the server
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"404":
|
|
description: Run not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/api/v1/runs/{id}/stages/{stageId}/logs/output:
|
|
get:
|
|
operationId: getRunStageCommandLog
|
|
tags: [Run Internals]
|
|
summary: Tail Command Log
|
|
description: Returns a byte-offset slice of a command stage output log. Bytes are base64-encoded and are not snapped to UTF-8 boundaries.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
- $ref: "#/components/parameters/StageId"
|
|
- $ref: "#/components/parameters/CommandLogOffset"
|
|
- $ref: "#/components/parameters/CommandLogLimit"
|
|
responses:
|
|
"200":
|
|
description: Command log bytes.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CommandLogResponse"
|
|
"400":
|
|
description: Invalid stage, offset, or limit.
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"404":
|
|
description: Run or stage not found.
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"404":
|
|
description: Run not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"409":
|
|
description: Question no longer exists or already answered
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/api/v1/runs/{id}/stages/{stageId}/events:
|
|
get:
|
|
operationId: listStageEvents
|
|
tags: [Run Internals]
|
|
summary: List Stage Events
|
|
description: Returns a paginated JSON list of stored run events scoped to a single stage visit.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
- $ref: "#/components/parameters/StageId"
|
|
- $ref: "#/components/parameters/SinceSeq"
|
|
- $ref: "#/components/parameters/EventLimit"
|
|
responses:
|
|
"200":
|
|
description: Paginated list of stage events
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PaginatedEventList"
|
|
"404":
|
|
description: Run not found.
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/api/v1/runs/{id}/files:
|
|
get:
|
|
operationId: listRunFiles
|
|
tags: [Run Outputs]
|
|
summary: List Run Files Changed
|
|
description: |
|
|
Returns the set of file changes produced by a run as a list of before/after diffs.
|
|
|
|
While the run's sandbox is reachable, diffs are resolved live against the sandbox working tree at the current HEAD. Degraded responses keep the same `data: FileDiff[]` shape. File contents are null on every entry; non-sensitive non-flagged entries include `unified_patch`, while sensitive / binary / symlink / submodule / truncated entries render through the same placeholder flags used by the live path.
|
|
|
|
Responses are bounded by per-file (256 KiB / 20k lines), per-run aggregate (5 MiB), and per-request (200 files) caps. Files exceeding a cap are returned with `truncated: true` and empty `contents`. Sensitive paths (credentials, keys) are elided with `sensitive: true` and empty `contents`.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
- $ref: "#/components/parameters/PageLimit"
|
|
- $ref: "#/components/parameters/PageOffset"
|
|
- name: from_sha
|
|
in: query
|
|
required: false
|
|
description: Reserved for future use. Only the default value is accepted in the current API version; any other value returns 400.
|
|
schema:
|
|
type: string
|
|
pattern: "^[0-9a-f]{7,40}$"
|
|
- name: to_sha
|
|
in: query
|
|
required: false
|
|
description: Reserved for future use. Only the default value is accepted in the current API version; any other value returns 400.
|
|
schema:
|
|
type: string
|
|
pattern: "^[0-9a-f]{7,40}$"
|
|
responses:
|
|
"200":
|
|
description: File diffs for the run
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PaginatedRunFileList"
|
|
"400":
|
|
description: Malformed query parameter (invalid SHA format, or non-default value for `from_sha`/`to_sha`).
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"404":
|
|
description: Run not found (or caller lacks access; returned as 404 to prevent enumeration).
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"503":
|
|
description: Transient sandbox subprocess failure (timeout, process kill). Safe to retry.
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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"
|
|
- $ref: "#/components/parameters/ArtifactRetry"
|
|
- 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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"404":
|
|
description: Run not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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"
|
|
- $ref: "#/components/parameters/ArtifactRetry"
|
|
responses:
|
|
"200":
|
|
description: Artifact contents
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
"400":
|
|
description: Missing filename or retry
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"404":
|
|
description: Run, stage, or artifact not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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 persisted dense `WorkflowSettings` snapshot used to launch this run.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
responses:
|
|
"200":
|
|
description: Run settings
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkflowSettings"
|
|
"404":
|
|
description: Run not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"409":
|
|
description: Run has no active sandbox
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"409":
|
|
description: Run has no active sandbox or provider does not support SSH
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"409":
|
|
description: Run has no active sandbox
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"409":
|
|
description: Run has no active sandbox
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"409":
|
|
description: Run has no active sandbox
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
# ── Workflows ────────────────────────────────────────────────────────
|
|
|
|
/api/v1/workflows:
|
|
get:
|
|
operationId: listWorkflows
|
|
tags: [Workflows]
|
|
summary: List workflows
|
|
description: Returns workflow definitions available to the browser workflow pages. Real-mode servers may return 501 until workflow cataloging is implemented.
|
|
parameters:
|
|
- $ref: "#/components/parameters/PageLimit"
|
|
- $ref: "#/components/parameters/PageOffset"
|
|
responses:
|
|
"200":
|
|
description: Paginated workflow summaries
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PaginatedWorkflowListResponse"
|
|
"501":
|
|
description: Workflow cataloging is not implemented in real mode
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/api/v1/workflows/{name}:
|
|
get:
|
|
operationId: retrieveWorkflow
|
|
tags: [Workflows]
|
|
summary: Retrieve workflow
|
|
description: Returns a single workflow definition and its dense settings snapshot.
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
required: true
|
|
description: Workflow slug or name.
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Workflow details
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkflowDetailResponse"
|
|
"404":
|
|
description: Workflow not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"501":
|
|
description: Workflow cataloging is not implemented in real mode
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/api/v1/workflows/{name}/runs:
|
|
get:
|
|
operationId: listWorkflowRuns
|
|
tags: [Workflows]
|
|
summary: List workflow runs
|
|
description: Returns durable runs associated with one workflow.
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
required: true
|
|
description: Workflow slug or name.
|
|
schema:
|
|
type: string
|
|
- $ref: "#/components/parameters/PageLimit"
|
|
- $ref: "#/components/parameters/PageOffset"
|
|
responses:
|
|
"200":
|
|
description: Paginated durable runs for the workflow
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PaginatedRunList"
|
|
"404":
|
|
description: Workflow not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"501":
|
|
description: Workflow cataloging is not implemented in real mode
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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/repair/runs:
|
|
get:
|
|
operationId: getSystemRepairRuns
|
|
tags: [System]
|
|
summary: List Run Repair Issues
|
|
description: Lists cataloged runs that cannot be loaded from durable storage.
|
|
responses:
|
|
"200":
|
|
description: Run repair issues
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SystemRepairRunsResponse"
|
|
|
|
/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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"404":
|
|
description: Secret not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"500":
|
|
description: Secret store write failed
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"404":
|
|
description: Model not found
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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
|
|
headers:
|
|
x-request-id:
|
|
$ref: "#/components/headers/XRequestId"
|
|
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's current in-memory settings view as the typed
|
|
`ServerSettings` payload.
|
|
responses:
|
|
"200":
|
|
description: Server settings
|
|
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
|
|
|
|
RunSelector:
|
|
name: selector
|
|
in: query
|
|
required: true
|
|
description: Run selector, such as a run ID prefix, workflow slug, or workflow name.
|
|
schema:
|
|
type: string
|
|
example: nightly-build
|
|
|
|
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
|
|
|
|
CommandLogOffset:
|
|
name: offset
|
|
in: query
|
|
required: false
|
|
description: Byte offset to start reading from. Defaults to `0`.
|
|
schema:
|
|
type: integer
|
|
minimum: 0
|
|
default: 0
|
|
example: 65536
|
|
|
|
CommandLogLimit:
|
|
name: limit
|
|
in: query
|
|
required: false
|
|
description: Maximum bytes to return. Defaults to 65536 and is capped at 1048576.
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 1048576
|
|
default: 65536
|
|
example: 65536
|
|
|
|
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
|
|
|
|
ArtifactRetry:
|
|
name: retry
|
|
in: query
|
|
required: true
|
|
description: Retry attempt number for the artifact.
|
|
schema:
|
|
type: integer
|
|
format: int32
|
|
minimum: 0
|
|
example: 1
|
|
|
|
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
|
|
|
|
IncludeArchived:
|
|
name: include_archived
|
|
in: query
|
|
required: false
|
|
description: Whether to include archived runs in the response. Defaults to `false`.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: false
|
|
|
|
ForceRunDelete:
|
|
name: force
|
|
in: query
|
|
required: false
|
|
description: Whether to force deletion of an active run. Defaults to `false`.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: false
|
|
|
|
ModelProviderFilter:
|
|
name: provider
|
|
in: query
|
|
required: false
|
|
description: Filter models by provider name. Invalid values return `400`.
|
|
schema:
|
|
$ref: "#/components/schemas/Provider"
|
|
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
|
|
|
|
headers:
|
|
XRequestId:
|
|
description: >
|
|
Server-generated request identifier emitted on every response and
|
|
referenced on standard error responses for correlating client errors
|
|
with server logs.
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
|
|
schemas:
|
|
AuthConfigResponse:
|
|
description: Browser login methods enabled by server auth settings.
|
|
type: object
|
|
required:
|
|
- methods
|
|
properties:
|
|
methods:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: ["dev-token", "github"]
|
|
|
|
AuthMeResponse:
|
|
description: Current authenticated browser user and session state.
|
|
type: object
|
|
required:
|
|
- user
|
|
- provider
|
|
- demoMode
|
|
properties:
|
|
user:
|
|
$ref: "#/components/schemas/AuthSessionUser"
|
|
provider:
|
|
type: string
|
|
example: dev-token
|
|
demoMode:
|
|
type: boolean
|
|
|
|
AuthSessionUser:
|
|
description: Browser session user profile.
|
|
type: object
|
|
required:
|
|
- login
|
|
- name
|
|
- email
|
|
- avatarUrl
|
|
- userUrl
|
|
properties:
|
|
login:
|
|
type: string
|
|
name:
|
|
type: string
|
|
email:
|
|
type: string
|
|
idpIssuer:
|
|
type: string
|
|
idpSubject:
|
|
type: string
|
|
avatarUrl:
|
|
type: string
|
|
userUrl:
|
|
type: string
|
|
|
|
DemoToggleRequest:
|
|
description: Desired browser demo-mode state.
|
|
type: object
|
|
required:
|
|
- enabled
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
|
|
DemoToggleResponse:
|
|
description: Updated browser demo-mode state.
|
|
type: object
|
|
required:
|
|
- enabled
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
|
|
DevTokenLoginRequest:
|
|
description: Browser login payload for development-token auth.
|
|
type: object
|
|
required:
|
|
- token
|
|
properties:
|
|
token:
|
|
type: string
|
|
|
|
DevTokenLoginResponse:
|
|
description: Browser development-token login result.
|
|
type: object
|
|
required:
|
|
- ok
|
|
properties:
|
|
ok:
|
|
type: boolean
|
|
|
|
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"
|
|
object_store:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/InstallObjectStoreSummary"
|
|
- type: "null"
|
|
sandbox:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/InstallSandboxSummary"
|
|
- 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
|
|
- object_store_local_root
|
|
properties:
|
|
canonical_url:
|
|
type: string
|
|
format: uri
|
|
object_store_local_root:
|
|
type: string
|
|
|
|
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. Supported providers in install v1 are `anthropic`, `openai`, and `gemini`.
|
|
type: object
|
|
required:
|
|
- provider
|
|
- api_key
|
|
properties:
|
|
provider:
|
|
type: string
|
|
example: anthropic
|
|
api_key:
|
|
type: string
|
|
|
|
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. Supported providers in install v1 are `anthropic`, `openai`, and `gemini`.
|
|
type: object
|
|
required:
|
|
- provider
|
|
- api_key
|
|
properties:
|
|
provider:
|
|
type: string
|
|
example: anthropic
|
|
api_key:
|
|
type: string
|
|
|
|
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
|
|
|
|
InstallServerConfigInput:
|
|
description: Canonical server URL confirmed during browser install.
|
|
type: object
|
|
required:
|
|
- canonical_url
|
|
properties:
|
|
canonical_url:
|
|
type: string
|
|
format: uri
|
|
|
|
InstallObjectStoreValidationResponse:
|
|
description: Successful response from install-time object-store validation.
|
|
type: object
|
|
required:
|
|
- ok
|
|
properties:
|
|
ok:
|
|
type: boolean
|
|
example: true
|
|
|
|
InstallObjectStoreInput:
|
|
description: Object-store mode selected during browser install.
|
|
type: object
|
|
required:
|
|
- provider
|
|
properties:
|
|
provider:
|
|
type: string
|
|
enum: [local, s3]
|
|
root:
|
|
type: string
|
|
bucket:
|
|
type: string
|
|
region:
|
|
type: string
|
|
credential_mode:
|
|
type: string
|
|
enum: [runtime, access_key]
|
|
access_key_id:
|
|
type: string
|
|
secret_access_key:
|
|
type: string
|
|
|
|
InstallObjectStoreSummary:
|
|
description: Redacted summary of the object-store mode selected during browser install.
|
|
type: object
|
|
required:
|
|
- provider
|
|
properties:
|
|
provider:
|
|
type: string
|
|
enum: [local, s3]
|
|
root:
|
|
type: string
|
|
bucket:
|
|
type: string
|
|
region:
|
|
type: string
|
|
credential_mode:
|
|
type: string
|
|
enum: [runtime, access_key]
|
|
manual_credentials_saved:
|
|
type: boolean
|
|
|
|
InstallSandboxValidationResponse:
|
|
description: Successful response from install-time sandbox validation.
|
|
type: object
|
|
required:
|
|
- ok
|
|
properties:
|
|
ok:
|
|
type: boolean
|
|
example: true
|
|
|
|
InstallSandboxInput:
|
|
description: Sandbox provider selected during browser install. `api_key` is required for Daytona and ignored for Docker.
|
|
type: object
|
|
required:
|
|
- provider
|
|
properties:
|
|
provider:
|
|
type: string
|
|
enum: [docker, daytona]
|
|
api_key:
|
|
type: string
|
|
|
|
InstallSandboxSummary:
|
|
description: Redacted summary of the sandbox provider selected during browser install.
|
|
type: object
|
|
required:
|
|
- provider
|
|
properties:
|
|
provider:
|
|
type: string
|
|
enum: [docker, daytona]
|
|
api_key_saved:
|
|
type: boolean
|
|
|
|
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:
|
|
$ref: "#/components/schemas/InstallGithubAppOwner"
|
|
app_name:
|
|
type: string
|
|
allowed_username:
|
|
type: string
|
|
|
|
InstallGithubAppOwner:
|
|
description: Owner of the GitHub App being created during browser install.
|
|
type: object
|
|
required:
|
|
- kind
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum: [personal, org]
|
|
slug:
|
|
type: string
|
|
description: Required when `kind` is `org`; the organization slug.
|
|
|
|
InstallGithubAppManifestResponse:
|
|
description: Browser handoff payload for the GitHub App creation flow.
|
|
type: object
|
|
required:
|
|
- manifest
|
|
- github_form_action
|
|
- state
|
|
properties:
|
|
manifest:
|
|
type: object
|
|
additionalProperties: true
|
|
github_form_action:
|
|
type: string
|
|
format: uri
|
|
state:
|
|
description: |
|
|
CSRF token the browser must echo back to GitHub as a hidden
|
|
`state` form field alongside `manifest`. GitHub preserves it on
|
|
the redirect to `redirect_url` so the server can match the
|
|
callback to this pending install.
|
|
type: string
|
|
|
|
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:
|
|
$ref: "#/components/schemas/InstallGithubAppOwner"
|
|
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
|
|
properties:
|
|
status:
|
|
type: string
|
|
enum: [completing]
|
|
restart_url:
|
|
type: string
|
|
format: uri
|
|
dev_token:
|
|
type: string
|
|
description: |
|
|
Dev token used to bootstrap login. Only included when the operator
|
|
chose the personal access token flow; GitHub App installs rely on
|
|
OAuth and do not receive a dev token.
|
|
|
|
# ── 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/RunSummary"
|
|
meta:
|
|
$ref: "#/components/schemas/PaginationMeta"
|
|
|
|
PaginatedBoardRunList:
|
|
description: Paginated list of board runs with shared canonical fields plus board metadata.
|
|
type: object
|
|
required:
|
|
- columns
|
|
- data
|
|
- meta
|
|
properties:
|
|
columns:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/BoardColumnDefinition"
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/RunListItem"
|
|
meta:
|
|
$ref: "#/components/schemas/PaginationMeta"
|
|
|
|
WorkflowScheduleSummary:
|
|
description: Workflow schedule summary shown in workflow lists.
|
|
type: object
|
|
required:
|
|
- expression
|
|
properties:
|
|
expression:
|
|
type: string
|
|
next_run:
|
|
type: ["string", "null"]
|
|
format: date-time
|
|
|
|
WorkflowLastRunSummary:
|
|
description: Most recent run timestamp for a workflow.
|
|
type: object
|
|
properties:
|
|
ran_at:
|
|
type: ["string", "null"]
|
|
format: date-time
|
|
|
|
WorkflowListItem:
|
|
description: Workflow summary shown in workflow list pages.
|
|
type: object
|
|
required:
|
|
- name
|
|
- slug
|
|
- filename
|
|
properties:
|
|
name:
|
|
type: string
|
|
slug:
|
|
type: string
|
|
filename:
|
|
type: string
|
|
last_run:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/WorkflowLastRunSummary"
|
|
- type: "null"
|
|
schedule:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/WorkflowScheduleSummary"
|
|
- type: "null"
|
|
|
|
PaginatedWorkflowListResponse:
|
|
description: Paginated list of workflows.
|
|
type: object
|
|
required:
|
|
- data
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/WorkflowListItem"
|
|
pagination:
|
|
$ref: "#/components/schemas/PaginationMeta"
|
|
|
|
WorkflowDetailResponse:
|
|
description: Workflow definition and dense settings snapshot.
|
|
type: object
|
|
required:
|
|
- name
|
|
- slug
|
|
- description
|
|
- filename
|
|
- settings
|
|
- graph
|
|
properties:
|
|
name:
|
|
type: string
|
|
slug:
|
|
type: string
|
|
description:
|
|
type: string
|
|
filename:
|
|
type: string
|
|
settings:
|
|
$ref: "#/components/schemas/WorkflowSettings"
|
|
graph:
|
|
type: string
|
|
|
|
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"
|
|
|
|
Provider:
|
|
description: LLM provider identifier.
|
|
type: string
|
|
enum:
|
|
- anthropic
|
|
- openai
|
|
- gemini
|
|
- kimi
|
|
- zai
|
|
- minimax
|
|
- inception
|
|
- openai_compatible
|
|
|
|
ModelLimits:
|
|
description: Token limits for a model.
|
|
type: object
|
|
required:
|
|
- context_window
|
|
- max_output
|
|
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
|
|
- effort
|
|
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.
|
|
effort:
|
|
type: boolean
|
|
description: Whether the model supports direct reasoning effort controls.
|
|
|
|
ModelCosts:
|
|
description: Pricing per million tokens in USD.
|
|
type: object
|
|
required:
|
|
- input_cost_per_mtok
|
|
- output_cost_per_mtok
|
|
- cache_input_cost_per_mtok
|
|
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
|
|
- training
|
|
- knowledge_cutoff
|
|
- features
|
|
- costs
|
|
- estimated_output_tps
|
|
- aliases
|
|
- default
|
|
- configured
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique model identifier.
|
|
example: "claude-opus-4-6"
|
|
provider:
|
|
$ref: "#/components/schemas/Provider"
|
|
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"
|
|
knowledge_cutoff:
|
|
type: ["string", "null"]
|
|
description: Public knowledge cutoff label, if known.
|
|
example: "May 2025"
|
|
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.
|
|
configured:
|
|
type: boolean
|
|
description: |
|
|
Whether credential material is present for this model's provider on the
|
|
server (vault entry or environment variable). Does NOT imply the
|
|
credential is valid or that requests will succeed; call
|
|
`POST /models/{id}/test` to verify usability.
|
|
|
|
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"
|
|
|
|
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. `archived` is a terminal status reached by
|
|
an explicit user action on a previously terminal (`succeeded`, `failed`,
|
|
or `dead`) run; archived runs are hidden from default listings and are
|
|
read-only until unarchived.
|
|
oneOf:
|
|
- $ref: "#/components/schemas/RunStatusSubmitted"
|
|
- $ref: "#/components/schemas/RunStatusQueued"
|
|
- $ref: "#/components/schemas/RunStatusStarting"
|
|
- $ref: "#/components/schemas/RunStatusRunning"
|
|
- $ref: "#/components/schemas/RunStatusBlocked"
|
|
- $ref: "#/components/schemas/RunStatusPaused"
|
|
- $ref: "#/components/schemas/RunStatusRemoving"
|
|
- $ref: "#/components/schemas/RunStatusSucceeded"
|
|
- $ref: "#/components/schemas/RunStatusFailed"
|
|
- $ref: "#/components/schemas/RunStatusDead"
|
|
- $ref: "#/components/schemas/RunStatusArchived"
|
|
discriminator:
|
|
propertyName: kind
|
|
mapping:
|
|
submitted: "#/components/schemas/RunStatusSubmitted"
|
|
queued: "#/components/schemas/RunStatusQueued"
|
|
starting: "#/components/schemas/RunStatusStarting"
|
|
running: "#/components/schemas/RunStatusRunning"
|
|
blocked: "#/components/schemas/RunStatusBlocked"
|
|
paused: "#/components/schemas/RunStatusPaused"
|
|
removing: "#/components/schemas/RunStatusRemoving"
|
|
succeeded: "#/components/schemas/RunStatusSucceeded"
|
|
failed: "#/components/schemas/RunStatusFailed"
|
|
dead: "#/components/schemas/RunStatusDead"
|
|
archived: "#/components/schemas/RunStatusArchived"
|
|
|
|
RunStatusSubmitted:
|
|
type: object
|
|
required:
|
|
- kind
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum:
|
|
- submitted
|
|
|
|
RunStatusQueued:
|
|
type: object
|
|
required:
|
|
- kind
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum:
|
|
- queued
|
|
|
|
RunStatusStarting:
|
|
type: object
|
|
required:
|
|
- kind
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum:
|
|
- starting
|
|
|
|
RunStatusRunning:
|
|
type: object
|
|
required:
|
|
- kind
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum:
|
|
- running
|
|
|
|
RunStatusBlocked:
|
|
type: object
|
|
required:
|
|
- kind
|
|
- blocked_reason
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum:
|
|
- blocked
|
|
blocked_reason:
|
|
$ref: "#/components/schemas/BlockedReason"
|
|
|
|
RunStatusPaused:
|
|
type: object
|
|
required:
|
|
- kind
|
|
- prior_block
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum:
|
|
- paused
|
|
prior_block:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/BlockedReason"
|
|
- type: "null"
|
|
|
|
RunStatusRemoving:
|
|
type: object
|
|
required:
|
|
- kind
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum:
|
|
- removing
|
|
|
|
RunStatusSucceeded:
|
|
type: object
|
|
required:
|
|
- kind
|
|
- reason
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum:
|
|
- succeeded
|
|
reason:
|
|
$ref: "#/components/schemas/SuccessReason"
|
|
|
|
RunStatusFailed:
|
|
type: object
|
|
required:
|
|
- kind
|
|
- reason
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum:
|
|
- failed
|
|
reason:
|
|
$ref: "#/components/schemas/FailureReason"
|
|
|
|
RunStatusDead:
|
|
type: object
|
|
required:
|
|
- kind
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum:
|
|
- dead
|
|
|
|
RunStatusArchived:
|
|
type: object
|
|
required:
|
|
- kind
|
|
- prior
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum:
|
|
- archived
|
|
prior:
|
|
$ref: "#/components/schemas/TerminalStatus"
|
|
|
|
TerminalStatus:
|
|
description: Terminal run status captured inside an archived run.
|
|
oneOf:
|
|
- $ref: "#/components/schemas/RunStatusSucceeded"
|
|
- $ref: "#/components/schemas/RunStatusFailed"
|
|
- $ref: "#/components/schemas/RunStatusDead"
|
|
discriminator:
|
|
propertyName: kind
|
|
mapping:
|
|
succeeded: "#/components/schemas/RunStatusSucceeded"
|
|
failed: "#/components/schemas/RunStatusFailed"
|
|
dead: "#/components/schemas/RunStatusDead"
|
|
|
|
SuccessReason:
|
|
description: Reason attached to a successful terminal run status.
|
|
type: string
|
|
enum:
|
|
- completed
|
|
- partial_success
|
|
|
|
FailureReason:
|
|
description: Reason attached to a failed terminal run status.
|
|
type: string
|
|
enum:
|
|
- workflow_error
|
|
- cancelled
|
|
- terminated
|
|
- transient_infra
|
|
- budget_exhausted
|
|
- launch_failed
|
|
- bootstrap_failed
|
|
- sandbox_init_failed
|
|
|
|
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/GitContext"
|
|
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"
|
|
|
|
GitContext:
|
|
description: Observable git state captured before the run starts.
|
|
type: object
|
|
required:
|
|
- origin_url
|
|
- branch
|
|
- dirty
|
|
- push_outcome
|
|
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", "null"]
|
|
description: Current commit SHA, when known.
|
|
example: abc123def
|
|
dirty:
|
|
$ref: "#/components/schemas/DirtyStatus"
|
|
push_outcome:
|
|
$ref: "#/components/schemas/PreRunPushOutcome"
|
|
|
|
PreRunPushOutcome:
|
|
description: Outcome of the CLI's best-effort pre-run push.
|
|
oneOf:
|
|
- $ref: "#/components/schemas/PreRunPushOutcomeNotAttempted"
|
|
- $ref: "#/components/schemas/PreRunPushOutcomeSucceeded"
|
|
- $ref: "#/components/schemas/PreRunPushOutcomeFailed"
|
|
- $ref: "#/components/schemas/PreRunPushOutcomeSkippedNoRemote"
|
|
- $ref: "#/components/schemas/PreRunPushOutcomeSkippedRemoteMismatch"
|
|
discriminator:
|
|
propertyName: type
|
|
mapping:
|
|
not_attempted: "#/components/schemas/PreRunPushOutcomeNotAttempted"
|
|
succeeded: "#/components/schemas/PreRunPushOutcomeSucceeded"
|
|
failed: "#/components/schemas/PreRunPushOutcomeFailed"
|
|
skipped_no_remote: "#/components/schemas/PreRunPushOutcomeSkippedNoRemote"
|
|
skipped_remote_mismatch: "#/components/schemas/PreRunPushOutcomeSkippedRemoteMismatch"
|
|
|
|
PreRunPushOutcomeNotAttempted:
|
|
type: object
|
|
required:
|
|
- type
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum:
|
|
- not_attempted
|
|
|
|
PreRunPushOutcomeSucceeded:
|
|
type: object
|
|
required:
|
|
- type
|
|
- remote
|
|
- branch
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum:
|
|
- succeeded
|
|
remote:
|
|
type: string
|
|
branch:
|
|
type: string
|
|
|
|
PreRunPushOutcomeFailed:
|
|
type: object
|
|
required:
|
|
- type
|
|
- remote
|
|
- branch
|
|
- message
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum:
|
|
- failed
|
|
remote:
|
|
type: string
|
|
branch:
|
|
type: string
|
|
message:
|
|
type: string
|
|
|
|
PreRunPushOutcomeSkippedNoRemote:
|
|
type: object
|
|
required:
|
|
- type
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum:
|
|
- skipped_no_remote
|
|
|
|
PreRunPushOutcomeSkippedRemoteMismatch:
|
|
type: object
|
|
required:
|
|
- type
|
|
- remote
|
|
- repo_origin_url
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum:
|
|
- skipped_remote_mismatch
|
|
remote:
|
|
type: string
|
|
repo_origin_url:
|
|
type: string
|
|
|
|
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
|
|
docker_image:
|
|
type: string
|
|
description: Per-run Docker sandbox image override.
|
|
verbose:
|
|
type: boolean
|
|
dry_run:
|
|
type: boolean
|
|
auto_approve:
|
|
type: boolean
|
|
preserve_sandbox:
|
|
type: boolean
|
|
worktree_mode:
|
|
type: string
|
|
description: |
|
|
Override `run.sandbox.local.worktree_mode` (e.g. `never` for
|
|
`--in-place`).
|
|
label:
|
|
type: array
|
|
items:
|
|
type: string
|
|
input:
|
|
type: array
|
|
description: Raw repeated CLI input overrides, each in `KEY=VALUE` form.
|
|
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"
|
|
|
|
ValidateResponse:
|
|
type: object
|
|
required:
|
|
- ok
|
|
- workflow
|
|
properties:
|
|
ok:
|
|
type: boolean
|
|
description: Whether validation passed with no error diagnostics.
|
|
workflow:
|
|
$ref: "#/components/schemas/PreflightWorkflowSummary"
|
|
|
|
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
|
|
|
|
SteerRunRequest:
|
|
description: Request body for steering a running run mid-execution.
|
|
type: object
|
|
required:
|
|
- text
|
|
properties:
|
|
text:
|
|
type: string
|
|
description: The steering message text to deliver as a user turn.
|
|
minLength: 1
|
|
maxLength: 8192
|
|
example: Try a different approach
|
|
interrupt:
|
|
type: boolean
|
|
description: |
|
|
When true, apply a worker-control interrupt first, then deliver
|
|
this text as steering in the same control operation. When false
|
|
(default), append to the steering queue and let the agent pick it
|
|
up at the next turn boundary.
|
|
default: false
|
|
|
|
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 the status kind is `queued`.
|
|
example: 3
|
|
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"
|
|
web_url:
|
|
type: string
|
|
format: uri
|
|
description: |
|
|
Public URL where the run can be viewed in the web UI. Present when
|
|
the server has the web UI enabled (`server.web.enabled = true`) and
|
|
`server.web.url` is non-empty; absent otherwise.
|
|
example: "http://localhost:3000/runs/01JNQVR7M0EJ5GKAT2SC4ERS1Z"
|
|
|
|
DeleteRunResponse:
|
|
description: Returned when a run is deleted but its sandbox is intentionally preserved.
|
|
type: object
|
|
required: [deleted, sandbox_preserved, sandbox]
|
|
properties:
|
|
deleted:
|
|
type: boolean
|
|
sandbox_preserved:
|
|
type: boolean
|
|
sandbox:
|
|
$ref: "#/components/schemas/DeleteRunSandbox"
|
|
|
|
DeleteRunSandbox:
|
|
type: object
|
|
required: [provider, identifier]
|
|
properties:
|
|
provider:
|
|
type: string
|
|
identifier:
|
|
type: string
|
|
|
|
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. The
|
|
`kind` discriminator determines which answer shape is submitted.
|
|
oneOf:
|
|
- $ref: "#/components/schemas/SubmitAnswerYesRequest"
|
|
- $ref: "#/components/schemas/SubmitAnswerNoRequest"
|
|
- $ref: "#/components/schemas/SubmitAnswerSelectedRequest"
|
|
- $ref: "#/components/schemas/SubmitAnswerMultiSelectedRequest"
|
|
- $ref: "#/components/schemas/SubmitAnswerTextRequest"
|
|
discriminator:
|
|
propertyName: kind
|
|
mapping:
|
|
"yes": "#/components/schemas/SubmitAnswerYesRequest"
|
|
"no": "#/components/schemas/SubmitAnswerNoRequest"
|
|
selected: "#/components/schemas/SubmitAnswerSelectedRequest"
|
|
multi_selected: "#/components/schemas/SubmitAnswerMultiSelectedRequest"
|
|
text: "#/components/schemas/SubmitAnswerTextRequest"
|
|
|
|
SubmitAnswerYesRequest:
|
|
type: object
|
|
required:
|
|
- kind
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum: ["yes"]
|
|
description: Affirmative answer for yes/no and confirmation questions.
|
|
|
|
SubmitAnswerNoRequest:
|
|
type: object
|
|
required:
|
|
- kind
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum: ["no"]
|
|
description: Negative answer for yes/no questions.
|
|
|
|
SubmitAnswerSelectedRequest:
|
|
type: object
|
|
required:
|
|
- kind
|
|
- option_key
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum: [selected]
|
|
description: Single selected option answer.
|
|
option_key:
|
|
type: string
|
|
description: Key of the selected option.
|
|
example: option_a
|
|
|
|
SubmitAnswerMultiSelectedRequest:
|
|
type: object
|
|
required:
|
|
- kind
|
|
- option_keys
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum: [multi_selected]
|
|
description: Multiple selected option answer.
|
|
option_keys:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Keys of selected options.
|
|
example: ["option_a", "option_b"]
|
|
|
|
SubmitAnswerTextRequest:
|
|
type: object
|
|
required:
|
|
- kind
|
|
- text
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum: [text]
|
|
description: Freeform text answer.
|
|
text:
|
|
type: string
|
|
description: Freeform answer text.
|
|
example: "Yes, proceed with the changes."
|
|
|
|
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.
|
|
code:
|
|
type: string
|
|
description: Optional machine-readable error code for structured client handling.
|
|
example: access_token_expired
|
|
request_id:
|
|
type: string
|
|
format: uuid
|
|
description: Server-generated request identifier; matches the x-request-id response header.
|
|
|
|
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"
|
|
request_id:
|
|
type: string
|
|
format: uuid
|
|
description: Server-generated request identifier; matches the x-request-id response header.
|
|
leftover_env_keys:
|
|
type: array
|
|
description: >-
|
|
Optional list of runtime env keys that were written before an install
|
|
failure. Currently populated by `POST /install/finish` failure
|
|
responses only.
|
|
items:
|
|
type: string
|
|
removed_env_keys:
|
|
type: array
|
|
description: >-
|
|
Optional list of runtime env keys that were actually removed before
|
|
an install failure. Currently populated by `POST /install/finish`
|
|
failure responses only.
|
|
items:
|
|
type: string
|
|
|
|
AuthMethod:
|
|
description: Runtime user authentication method.
|
|
type: string
|
|
enum:
|
|
- github
|
|
- dev_token
|
|
|
|
SystemActorKind:
|
|
type: string
|
|
enum:
|
|
- engine
|
|
- watchdog
|
|
- timeout
|
|
|
|
IdpIdentity:
|
|
type: object
|
|
required:
|
|
- issuer
|
|
- subject
|
|
properties:
|
|
issuer:
|
|
type: string
|
|
subject:
|
|
type: string
|
|
|
|
RunServerProvenance:
|
|
type: object
|
|
required:
|
|
- version
|
|
properties:
|
|
version:
|
|
type: string
|
|
|
|
RunClientProvenance:
|
|
type: object
|
|
properties:
|
|
user_agent:
|
|
type: string
|
|
name:
|
|
type: string
|
|
version:
|
|
type: string
|
|
|
|
RunProvenance:
|
|
type: object
|
|
properties:
|
|
server:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/RunServerProvenance"
|
|
- type: "null"
|
|
client:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/RunClientProvenance"
|
|
- type: "null"
|
|
subject:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/Principal"
|
|
- type: "null"
|
|
|
|
Principal:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/PrincipalUser"
|
|
- $ref: "#/components/schemas/PrincipalWorker"
|
|
- $ref: "#/components/schemas/PrincipalWebhook"
|
|
- $ref: "#/components/schemas/PrincipalSlack"
|
|
- $ref: "#/components/schemas/PrincipalAgent"
|
|
- $ref: "#/components/schemas/PrincipalSystem"
|
|
- $ref: "#/components/schemas/PrincipalAnonymous"
|
|
discriminator:
|
|
propertyName: kind
|
|
mapping:
|
|
user: "#/components/schemas/PrincipalUser"
|
|
worker: "#/components/schemas/PrincipalWorker"
|
|
webhook: "#/components/schemas/PrincipalWebhook"
|
|
slack: "#/components/schemas/PrincipalSlack"
|
|
agent: "#/components/schemas/PrincipalAgent"
|
|
system: "#/components/schemas/PrincipalSystem"
|
|
anonymous: "#/components/schemas/PrincipalAnonymous"
|
|
|
|
PrincipalUser:
|
|
type: object
|
|
required:
|
|
- kind
|
|
- identity
|
|
- login
|
|
- auth_method
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum: [user]
|
|
identity:
|
|
$ref: "#/components/schemas/IdpIdentity"
|
|
login:
|
|
type: string
|
|
auth_method:
|
|
$ref: "#/components/schemas/AuthMethod"
|
|
|
|
PrincipalWorker:
|
|
type: object
|
|
required:
|
|
- kind
|
|
- run_id
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum: [worker]
|
|
run_id:
|
|
type: string
|
|
|
|
PrincipalWebhook:
|
|
type: object
|
|
required:
|
|
- kind
|
|
- delivery_id
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum: [webhook]
|
|
delivery_id:
|
|
type: string
|
|
|
|
PrincipalSlack:
|
|
type: object
|
|
required:
|
|
- kind
|
|
- team_id
|
|
- user_id
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum: [slack]
|
|
team_id:
|
|
type: string
|
|
user_id:
|
|
type: string
|
|
user_name:
|
|
type: ["string", "null"]
|
|
|
|
PrincipalAgent:
|
|
type: object
|
|
required:
|
|
- kind
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum: [agent]
|
|
session_id:
|
|
type: ["string", "null"]
|
|
parent_session_id:
|
|
type: ["string", "null"]
|
|
model:
|
|
type: ["string", "null"]
|
|
|
|
PrincipalSystem:
|
|
type: object
|
|
required:
|
|
- kind
|
|
- system_kind
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum: [system]
|
|
system_kind:
|
|
$ref: "#/components/schemas/SystemActorKind"
|
|
|
|
PrincipalAnonymous:
|
|
type: object
|
|
required:
|
|
- kind
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum: [anonymous]
|
|
|
|
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/Principal"
|
|
- type: "null"
|
|
event:
|
|
type: string
|
|
description: Event type discriminator.
|
|
example: stage.started
|
|
properties:
|
|
type: object
|
|
additionalProperties: true
|
|
additionalProperties: true
|
|
|
|
RunSupersededByProps:
|
|
description: Properties for the `run.superseded_by` audit event emitted on a rewound source run after archive succeeds.
|
|
type: object
|
|
required:
|
|
- new_run_id
|
|
- target_checkpoint_ordinal
|
|
- target_node_id
|
|
- target_visit
|
|
properties:
|
|
new_run_id:
|
|
type: string
|
|
target_checkpoint_ordinal:
|
|
type: integer
|
|
minimum: 1
|
|
target_node_id:
|
|
type: string
|
|
target_visit:
|
|
type: integer
|
|
minimum: 1
|
|
|
|
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
|
|
|
|
CommandTermination:
|
|
description: Terminal state for a command execution.
|
|
type: string
|
|
enum:
|
|
- exited
|
|
- timed_out
|
|
- cancelled
|
|
|
|
CommandLogResponse:
|
|
description: Byte-offset command log slice.
|
|
type: object
|
|
required:
|
|
- offset
|
|
- next_offset
|
|
- total_bytes
|
|
- bytes_base64
|
|
- eof
|
|
- cas_ref
|
|
- live_streaming
|
|
properties:
|
|
offset:
|
|
type: integer
|
|
minimum: 0
|
|
description: Actual byte offset used for this slice.
|
|
example: 0
|
|
next_offset:
|
|
type: integer
|
|
minimum: 0
|
|
description: Byte offset for the next tail request.
|
|
example: 4096
|
|
total_bytes:
|
|
type: integer
|
|
minimum: 0
|
|
description: Total bytes currently available for the output log.
|
|
example: 8192
|
|
bytes_base64:
|
|
type: string
|
|
description: Base64-encoded raw log bytes.
|
|
example: aGVsbG8K
|
|
eof:
|
|
type: boolean
|
|
description: Whether the output log is finalized.
|
|
example: false
|
|
cas_ref:
|
|
oneOf:
|
|
- type: string
|
|
pattern: '^blob://sha256/[0-9a-f]{64}$'
|
|
- type: "null"
|
|
description: Final CAS reference once the command has completed.
|
|
live_streaming:
|
|
type: boolean
|
|
description: Whether the sandbox provided live output while the command was running.
|
|
example: true
|
|
|
|
ArtifactEntry:
|
|
description: A single artifact file for a stage.
|
|
type: object
|
|
required:
|
|
- filename
|
|
- retry
|
|
- size
|
|
properties:
|
|
filename:
|
|
type: string
|
|
description: Artifact filename.
|
|
example: src/lib.rs
|
|
retry:
|
|
type: integer
|
|
format: int32
|
|
minimum: 0
|
|
description: Retry attempt number.
|
|
example: 1
|
|
size:
|
|
type: integer
|
|
format: int64
|
|
minimum: 0
|
|
description: Artifact size in bytes.
|
|
example: 1234
|
|
|
|
ArtifactListResponse:
|
|
description: List of artifact files 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
|
|
minimum: 0
|
|
description: Retry attempt number.
|
|
relative_path:
|
|
type: string
|
|
description: Artifact path relative to the stage artifact capture directory.
|
|
size:
|
|
type: integer
|
|
format: int64
|
|
minimum: 0
|
|
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"
|
|
|
|
BlockedReason:
|
|
description: Specific reason a run is blocked on external intervention.
|
|
type: string
|
|
enum:
|
|
- human_input_required
|
|
|
|
RunControlAction:
|
|
description: Run control action requested by the API.
|
|
type: string
|
|
enum:
|
|
- cancel
|
|
- pause
|
|
- unpause
|
|
|
|
StageOutcome:
|
|
description: Terminal execution outcome of a workflow stage.
|
|
type: string
|
|
enum:
|
|
- succeeded
|
|
- partially_succeeded
|
|
- failed
|
|
- skipped
|
|
|
|
StageCompletion:
|
|
description: Terminal completion metadata for a projected workflow stage.
|
|
type: object
|
|
required:
|
|
- outcome
|
|
- timestamp
|
|
properties:
|
|
outcome:
|
|
$ref: "#/components/schemas/StageOutcome"
|
|
notes:
|
|
type: ["string", "null"]
|
|
failure_reason:
|
|
type: ["string", "null"]
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
|
|
StageProjection:
|
|
description: Observable projection data for one workflow stage execution.
|
|
type: object
|
|
required:
|
|
- first_event_seq
|
|
properties:
|
|
first_event_seq:
|
|
type: integer
|
|
format: uint32
|
|
minimum: 1
|
|
prompt:
|
|
type: ["string", "null"]
|
|
response:
|
|
type: ["string", "null"]
|
|
completion:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/StageCompletion"
|
|
- type: "null"
|
|
provider_used:
|
|
type: ["object", "null"]
|
|
description: Provider and model metadata recorded for the stage attempt.
|
|
diff:
|
|
type: ["string", "null"]
|
|
script_invocation:
|
|
type: ["object", "null"]
|
|
description: Command and environment recorded when the stage script ran.
|
|
script_timing:
|
|
type: ["object", "null"]
|
|
description: Wall-clock and step timing metadata for the stage script.
|
|
parallel_results:
|
|
type: ["array", "null"]
|
|
items:
|
|
type: object
|
|
description: Per-branch result objects produced by a parallel stage.
|
|
output:
|
|
type: ["string", "null"]
|
|
output_bytes:
|
|
type: ["integer", "null"]
|
|
minimum: 0
|
|
live_streaming:
|
|
type: ["boolean", "null"]
|
|
termination:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/CommandTermination"
|
|
- type: "null"
|
|
started_at:
|
|
type: ["string", "null"]
|
|
format: date-time
|
|
description: Wall-clock time the latest attempt of this stage started, if known.
|
|
duration_ms:
|
|
type: ["integer", "null"]
|
|
format: uint64
|
|
minimum: 0
|
|
description: Wall-clock duration of the stage's latest terminal attempt, if known.
|
|
state:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/StageState"
|
|
- type: "null"
|
|
description: Lifecycle state of the stage projection.
|
|
|
|
InterviewOption:
|
|
description: Option stored with an interview question in the event log.
|
|
type: object
|
|
required:
|
|
- key
|
|
- label
|
|
properties:
|
|
key:
|
|
type: string
|
|
label:
|
|
type: string
|
|
|
|
InterviewQuestionRecord:
|
|
description: Storage shape of an interview question recorded in the event log.
|
|
type: object
|
|
required:
|
|
- id
|
|
- text
|
|
- stage
|
|
- question_type
|
|
- allow_freeform
|
|
properties:
|
|
id:
|
|
type: string
|
|
text:
|
|
type: string
|
|
stage:
|
|
type: string
|
|
question_type:
|
|
$ref: "#/components/schemas/QuestionType"
|
|
options:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/InterviewOption"
|
|
allow_freeform:
|
|
type: boolean
|
|
timeout_seconds:
|
|
type: ["number", "null"]
|
|
format: double
|
|
context_display:
|
|
type: ["string", "null"]
|
|
|
|
PendingInterviewRecord:
|
|
description: Pending interview question plus the time it entered the unresolved set.
|
|
type: object
|
|
required:
|
|
- question
|
|
properties:
|
|
question:
|
|
$ref: "#/components/schemas/InterviewQuestionRecord"
|
|
started_at:
|
|
type: ["string", "null"]
|
|
format: date-time
|
|
|
|
DirtyStatus:
|
|
type: string
|
|
enum:
|
|
- clean
|
|
- dirty
|
|
- unknown
|
|
|
|
ForkSourceRef:
|
|
description: Source checkpoint used to initialize a forked or rewound run.
|
|
type: object
|
|
required:
|
|
- source_run_id
|
|
- checkpoint_sha
|
|
properties:
|
|
source_run_id:
|
|
type: string
|
|
checkpoint_sha:
|
|
type: string
|
|
|
|
RunSpec:
|
|
description: Durable workflow run specification reconstructed from run.created events.
|
|
type: object
|
|
required:
|
|
- run_id
|
|
- settings
|
|
- graph
|
|
- in_place
|
|
properties:
|
|
run_id:
|
|
type: string
|
|
settings:
|
|
$ref: "#/components/schemas/WorkflowSettings"
|
|
graph:
|
|
type: object
|
|
additionalProperties: true
|
|
workflow_slug:
|
|
type: ["string", "null"]
|
|
source_directory:
|
|
type: ["string", "null"]
|
|
labels:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
provenance:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/RunProvenance"
|
|
- type: "null"
|
|
manifest_blob:
|
|
type: ["string", "null"]
|
|
definition_blob:
|
|
type: ["string", "null"]
|
|
git:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/GitContext"
|
|
- type: "null"
|
|
fork_source_ref:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/ForkSourceRef"
|
|
- type: "null"
|
|
in_place:
|
|
type: boolean
|
|
|
|
RunProjection:
|
|
description: Raw internal run projection derived from the event log.
|
|
type: object
|
|
required:
|
|
- stages
|
|
properties:
|
|
spec:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/RunSpec"
|
|
- type: "null"
|
|
graph_source:
|
|
type: ["string", "null"]
|
|
start:
|
|
type: ["object", "null"]
|
|
additionalProperties: true
|
|
status:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/RunStatus"
|
|
- type: "null"
|
|
status_updated_at:
|
|
oneOf:
|
|
- type: string
|
|
format: date-time
|
|
- type: "null"
|
|
last_event_at:
|
|
oneOf:
|
|
- type: string
|
|
format: date-time
|
|
- type: "null"
|
|
pending_control:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/RunControlAction"
|
|
- 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
|
|
sandbox:
|
|
type: ["object", "null"]
|
|
additionalProperties: true
|
|
final_patch:
|
|
type: ["string", "null"]
|
|
diff_summary:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/DiffSummary"
|
|
- type: "null"
|
|
pull_request:
|
|
type: ["object", "null"]
|
|
additionalProperties: true
|
|
superseded_by:
|
|
type: ["string", "null"]
|
|
pending_interviews:
|
|
type: object
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/PendingInterviewRecord"
|
|
stages:
|
|
type: object
|
|
description: Map from StageId (`node_id@visit`) to stage projection data.
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/StageProjection"
|
|
|
|
RunSummary:
|
|
description: Durable run summary derived from the backing store.
|
|
type: object
|
|
required:
|
|
- run_id
|
|
- goal
|
|
- title
|
|
- labels
|
|
- status
|
|
- repository
|
|
- created_at
|
|
properties:
|
|
run_id:
|
|
type: string
|
|
workflow_name:
|
|
type: ["string", "null"]
|
|
workflow_slug:
|
|
type: ["string", "null"]
|
|
goal:
|
|
type: string
|
|
title:
|
|
type: string
|
|
labels:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
source_directory:
|
|
type: ["string", "null"]
|
|
in_place:
|
|
type: boolean
|
|
repo_origin_url:
|
|
type: ["string", "null"]
|
|
repository:
|
|
$ref: "#/components/schemas/RepositoryReference"
|
|
start_time:
|
|
type: ["string", "null"]
|
|
format: date-time
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
last_event_at:
|
|
type: ["string", "null"]
|
|
format: date-time
|
|
status:
|
|
$ref: "#/components/schemas/RunStatus"
|
|
pending_control:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/RunControlAction"
|
|
- type: "null"
|
|
duration_ms:
|
|
type: ["integer", "null"]
|
|
format: int64
|
|
minimum: 0
|
|
elapsed_secs:
|
|
type: ["number", "null"]
|
|
total_usd_micros:
|
|
type: ["integer", "null"]
|
|
format: int64
|
|
superseded_by:
|
|
type: ["string", "null"]
|
|
diff_summary:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/DiffSummary"
|
|
- type: "null"
|
|
pull_request:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/PullRequestRecord"
|
|
- type: "null"
|
|
|
|
ForkRequest:
|
|
description: Request body for creating a new run from a source run checkpoint.
|
|
type: object
|
|
properties:
|
|
target:
|
|
type: ["string", "null"]
|
|
description: Optional checkpoint target such as `@2`, `build`, or `build@1`. Defaults to the latest checkpoint.
|
|
|
|
ForkResponse:
|
|
description: Response returned after creating a forked run.
|
|
type: object
|
|
required:
|
|
- source_run_id
|
|
- new_run_id
|
|
- target
|
|
properties:
|
|
source_run_id:
|
|
type: string
|
|
new_run_id:
|
|
type: string
|
|
target:
|
|
type: string
|
|
|
|
RewindRequest:
|
|
description: Request body for creating a replacement run from a source run checkpoint.
|
|
type: object
|
|
properties:
|
|
target:
|
|
type: ["string", "null"]
|
|
description: Optional checkpoint target such as `@2`, `build`, or `build@1`. Defaults to the latest checkpoint.
|
|
|
|
RewindResponse:
|
|
description: Response returned after rewind creates a new run.
|
|
type: object
|
|
required:
|
|
- source_run_id
|
|
- new_run_id
|
|
- target
|
|
- archived
|
|
properties:
|
|
source_run_id:
|
|
type: string
|
|
new_run_id:
|
|
type: string
|
|
target:
|
|
type: string
|
|
archived:
|
|
type: boolean
|
|
archive_error:
|
|
type: ["string", "null"]
|
|
|
|
TimelineEntryResponse:
|
|
description: Checkpoint timeline entry for a run.
|
|
type: object
|
|
required:
|
|
- ordinal
|
|
- node_name
|
|
- visit
|
|
- checkpoint_seq
|
|
properties:
|
|
ordinal:
|
|
type: integer
|
|
minimum: 1
|
|
node_name:
|
|
type: string
|
|
visit:
|
|
type: integer
|
|
minimum: 1
|
|
checkpoint_seq:
|
|
type: integer
|
|
minimum: 1
|
|
run_commit_sha:
|
|
type: ["string", "null"]
|
|
|
|
# ── Run Board Schemas ────────────────────────────────────────────────
|
|
|
|
BoardColumn:
|
|
description: Board column status for a run in the list view.
|
|
type: string
|
|
enum:
|
|
- queued
|
|
- initializing
|
|
- running
|
|
- blocked
|
|
- succeeded
|
|
- failed
|
|
- archived
|
|
|
|
BoardColumnDefinition:
|
|
type: object
|
|
required:
|
|
- id
|
|
- name
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/BoardColumn"
|
|
name:
|
|
type: string
|
|
|
|
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
|
|
- reasoning_tokens
|
|
- cache_read_tokens
|
|
- cache_write_tokens
|
|
properties:
|
|
input_tokens:
|
|
type: integer
|
|
format: int64
|
|
description: Number of input tokens consumed.
|
|
example: 28640
|
|
output_tokens:
|
|
type: integer
|
|
format: int64
|
|
description: Number of output tokens generated.
|
|
example: 8750
|
|
total_tokens:
|
|
type: integer
|
|
format: int64
|
|
description: Total billable tokens aggregated across categories.
|
|
example: 37390
|
|
reasoning_tokens:
|
|
type: integer
|
|
format: int64
|
|
description: Number of reasoning tokens.
|
|
example: 1200
|
|
cache_read_tokens:
|
|
type: integer
|
|
format: int64
|
|
description: Number of cache read tokens.
|
|
example: 4800
|
|
cache_write_tokens:
|
|
type: integer
|
|
format: int64
|
|
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
|
|
html_url:
|
|
type: string
|
|
format: uri
|
|
description: Stored GitHub pull request URL.
|
|
example: https://github.com/fabro-sh/fabro/pull/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"
|
|
|
|
PullRequestRecord:
|
|
description: Persisted record of a pull request created for a run.
|
|
type: object
|
|
required:
|
|
- html_url
|
|
- number
|
|
- owner
|
|
- repo
|
|
- base_branch
|
|
- head_branch
|
|
- title
|
|
properties:
|
|
html_url:
|
|
type: string
|
|
format: uri
|
|
example: https://github.com/fabro-sh/fabro/pull/123
|
|
number:
|
|
type: integer
|
|
example: 123
|
|
owner:
|
|
type: string
|
|
example: fabro-sh
|
|
repo:
|
|
type: string
|
|
example: fabro
|
|
base_branch:
|
|
type: string
|
|
example: main
|
|
head_branch:
|
|
type: string
|
|
example: fabro/run/demo
|
|
title:
|
|
type: string
|
|
example: Move PR commands server-side
|
|
|
|
PullRequestUser:
|
|
description: GitHub user summary for a pull request.
|
|
type: object
|
|
required:
|
|
- login
|
|
properties:
|
|
login:
|
|
type: string
|
|
example: octocat
|
|
|
|
PullRequestRef:
|
|
description: Git reference summary for a pull request.
|
|
type: object
|
|
required:
|
|
- ref
|
|
properties:
|
|
ref:
|
|
type: string
|
|
example: fabro/run/demo
|
|
|
|
PullRequestDetail:
|
|
description: Stored pull request record plus live GitHub fields.
|
|
type: object
|
|
required:
|
|
- record
|
|
- number
|
|
- title
|
|
- state
|
|
- draft
|
|
- merged
|
|
- additions
|
|
- deletions
|
|
- changed_files
|
|
- html_url
|
|
- user
|
|
- head
|
|
- base
|
|
- created_at
|
|
- updated_at
|
|
properties:
|
|
record:
|
|
$ref: "#/components/schemas/PullRequestRecord"
|
|
number:
|
|
type: integer
|
|
example: 123
|
|
title:
|
|
type: string
|
|
example: Move PR commands server-side
|
|
body:
|
|
type: ["string", "null"]
|
|
example: |
|
|
## Summary
|
|
- Move PR commands server-side
|
|
state:
|
|
type: string
|
|
example: open
|
|
draft:
|
|
type: boolean
|
|
example: false
|
|
merged:
|
|
type: boolean
|
|
example: false
|
|
merged_at:
|
|
type: ["string", "null"]
|
|
format: date-time
|
|
example: "2026-04-23T15:45:00Z"
|
|
mergeable:
|
|
type: ["boolean", "null"]
|
|
example: true
|
|
additions:
|
|
type: integer
|
|
example: 234
|
|
deletions:
|
|
type: integer
|
|
example: 67
|
|
changed_files:
|
|
type: integer
|
|
example: 5
|
|
html_url:
|
|
type: string
|
|
format: uri
|
|
example: https://github.com/fabro-sh/fabro/pull/123
|
|
user:
|
|
$ref: "#/components/schemas/PullRequestUser"
|
|
head:
|
|
$ref: "#/components/schemas/PullRequestRef"
|
|
base:
|
|
$ref: "#/components/schemas/PullRequestRef"
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
example: "2026-04-23T15:40:00Z"
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
example: "2026-04-23T15:45:00Z"
|
|
|
|
CreateRunPullRequestRequest:
|
|
description: Request body for creating a run pull request.
|
|
type: object
|
|
required:
|
|
- force
|
|
properties:
|
|
force:
|
|
type: boolean
|
|
description: Create the pull request even if the run did not finish with succeeded or partially_succeeded.
|
|
example: false
|
|
model:
|
|
type: ["string", "null"]
|
|
description: Optional model override for generating the pull request description.
|
|
example: claude-sonnet-4-6
|
|
|
|
MergeMethod:
|
|
description: GitHub merge method for a pull request.
|
|
type: string
|
|
enum:
|
|
- merge
|
|
- squash
|
|
- rebase
|
|
|
|
MergeRunPullRequestRequest:
|
|
description: Request body for merging a run pull request.
|
|
type: object
|
|
required:
|
|
- method
|
|
properties:
|
|
method:
|
|
$ref: "#/components/schemas/MergeMethod"
|
|
|
|
MergeRunPullRequestResponse:
|
|
description: Response body for merging a run pull request.
|
|
type: object
|
|
required:
|
|
- number
|
|
- html_url
|
|
- method
|
|
properties:
|
|
number:
|
|
type: integer
|
|
example: 123
|
|
html_url:
|
|
type: string
|
|
format: uri
|
|
example: https://github.com/fabro-sh/fabro/pull/123
|
|
method:
|
|
$ref: "#/components/schemas/MergeMethod"
|
|
|
|
CloseRunPullRequestResponse:
|
|
description: Response body for closing a run pull request.
|
|
type: object
|
|
required:
|
|
- number
|
|
- html_url
|
|
properties:
|
|
number:
|
|
type: integer
|
|
example: 123
|
|
html_url:
|
|
type: string
|
|
format: uri
|
|
example: https://github.com/fabro-sh/fabro/pull/123
|
|
|
|
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
|
|
properties:
|
|
id:
|
|
type: ["string", "null"]
|
|
description: Sandbox identifier.
|
|
example: sb-a1b2c3d4
|
|
working_directory:
|
|
type: ["string", "null"]
|
|
description: Path where the run executed inside the sandbox.
|
|
example: /workspace
|
|
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
|
|
- reasoning_tokens
|
|
- cache_read_tokens
|
|
- cache_write_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 workflow node in a billing stage row.
|
|
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: Canonical run summary shown in the board view, extended with board-specific metadata.
|
|
type: object
|
|
required:
|
|
- run_id
|
|
- goal
|
|
- title
|
|
- status
|
|
- labels
|
|
- repository
|
|
- created_at
|
|
- column
|
|
properties:
|
|
run_id:
|
|
type: string
|
|
description: Unique run identifier (ULID).
|
|
example: 01JNQVR7M0EJ5GKAT2SC4ERS1Z
|
|
workflow_name:
|
|
type: ["string", "null"]
|
|
workflow_slug:
|
|
type: ["string", "null"]
|
|
goal:
|
|
type: string
|
|
repository:
|
|
$ref: "#/components/schemas/RepositoryReference"
|
|
title:
|
|
type: string
|
|
description: Human-readable title describing the run's goal.
|
|
example: Add rate limiting to auth endpoints
|
|
status:
|
|
$ref: "#/components/schemas/RunStatus"
|
|
labels:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
source_directory:
|
|
type: ["string", "null"]
|
|
in_place:
|
|
type: boolean
|
|
repo_origin_url:
|
|
type: ["string", "null"]
|
|
start_time:
|
|
type: ["string", "null"]
|
|
format: date-time
|
|
pending_control:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/RunControlAction"
|
|
- type: "null"
|
|
duration_ms:
|
|
type: ["integer", "null"]
|
|
format: int64
|
|
minimum: 0
|
|
elapsed_secs:
|
|
type: ["number", "null"]
|
|
total_usd_micros:
|
|
type: ["integer", "null"]
|
|
format: int64
|
|
column:
|
|
$ref: "#/components/schemas/BoardColumn"
|
|
pull_request:
|
|
$ref: "#/components/schemas/RunPullRequest"
|
|
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"
|
|
last_event_at:
|
|
type: ["string", "null"]
|
|
format: date-time
|
|
description: Timestamp of the most recent event applied to the run's projection. Null until the first event is recorded.
|
|
|
|
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 ─────────────────────────────────────────────
|
|
|
|
StageState:
|
|
description: Lifecycle projection state of a workflow stage.
|
|
type: string
|
|
enum:
|
|
- pending
|
|
- running
|
|
- retrying
|
|
- succeeded
|
|
- partially_succeeded
|
|
- failed
|
|
- skipped
|
|
- cancelled
|
|
|
|
StageHandler:
|
|
description: Canonical workflow stage handler kind.
|
|
type: string
|
|
enum:
|
|
- start
|
|
- exit
|
|
- agent
|
|
- prompt
|
|
- command
|
|
- human
|
|
- conditional
|
|
- parallel
|
|
- parallel.fan_in
|
|
- stack.manager_loop
|
|
- wait
|
|
|
|
RunStage:
|
|
description: A single stage in a run's workflow graph.
|
|
type: object
|
|
required:
|
|
- id
|
|
- name
|
|
- handler
|
|
- status
|
|
- node_id
|
|
- visit
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: StageId in "node_id@visit" form, e.g. verify@2.
|
|
example: verify@2
|
|
name:
|
|
type: string
|
|
description: Human-readable stage name.
|
|
example: Propose Changes
|
|
handler:
|
|
$ref: "#/components/schemas/StageHandler"
|
|
status:
|
|
$ref: "#/components/schemas/StageState"
|
|
duration_secs:
|
|
type: number
|
|
description: Time spent in this stage, in seconds.
|
|
example: 154.0
|
|
node_id:
|
|
type: string
|
|
description: Node id in the workflow graph; multiple stages with different visits share the same node_id.
|
|
example: verify
|
|
visit:
|
|
type: integer
|
|
format: uint32
|
|
minimum: 1
|
|
description: 1-based visit count; bumped each time the workflow re-enters this node.
|
|
example: 2
|
|
started_at:
|
|
type: ["string", "null"]
|
|
format: date-time
|
|
description: Wall-clock time the latest attempt of this stage started, if known.
|
|
example: "2026-04-29T12:34:56Z"
|
|
|
|
# ── 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", "null"]
|
|
description: "Full contents at this side. Live path: empty string for added/deleted/binary/sensitive/symlink/submodule/truncated entries (the placeholder flags drive rendering). Degraded path: null for every entry (including placeholder-flagged ones), because the server only holds a checkpoint patch and cannot reconstruct full file bytes — distinguish degraded from live by `meta.degraded`."
|
|
example: 'import { parseArgs } from "node:util";'
|
|
|
|
FileDiff:
|
|
description: |
|
|
A before/after pair showing changes to a single file.
|
|
|
|
Contents conventions for non-modify cases:
|
|
- Added: `old_file.contents` is empty string; `new_file` holds the added contents.
|
|
- Deleted: `new_file.contents` is empty string; `old_file` holds the removed contents.
|
|
- Renamed (no content change): both sides hold identical contents; `old_file.name != new_file.name`.
|
|
- Symlink / submodule / binary / sensitive / truncated: contents are empty strings; consumers must render a placeholder based on the flag set.
|
|
- Degraded responses: contents are null on every entry; regular text diffs include `unified_patch`.
|
|
type: object
|
|
required:
|
|
- old_file
|
|
- new_file
|
|
properties:
|
|
old_file:
|
|
$ref: "#/components/schemas/DiffFile"
|
|
new_file:
|
|
$ref: "#/components/schemas/DiffFile"
|
|
change_kind:
|
|
type: string
|
|
description: Optional classification of the change. Clients that don't recognize a value should fall back to inspecting the old/new contents.
|
|
enum:
|
|
- added
|
|
- modified
|
|
- deleted
|
|
- renamed
|
|
- symlink
|
|
- submodule
|
|
example: modified
|
|
truncated:
|
|
type: boolean
|
|
description: When `true`, `new_file.contents` and `old_file.contents` are empty strings because the file exceeded a cap (see `truncation_reason`).
|
|
example: false
|
|
truncation_reason:
|
|
type: string
|
|
description: Reason this file's contents were omitted. Absent when `truncated` is `false` or omitted.
|
|
enum:
|
|
- file_too_large
|
|
- budget_exhausted
|
|
binary:
|
|
type: boolean
|
|
description: When `true`, the file is non-textual; `contents` on both sides are empty strings.
|
|
example: false
|
|
sensitive:
|
|
type: boolean
|
|
description: When `true`, the file path matched the server's sensitive-path denylist; `contents` on both sides are empty strings regardless of truncation or binary flags.
|
|
example: false
|
|
unified_patch:
|
|
type: ["string", "null"]
|
|
description: Per-file unified-patch text (the `diff --git` section verbatim). Populated only for regular non-flagged text-diff entries in degraded mode. Absent for sensitive, binary, symlink, submodule, truncated, and live-path entries.
|
|
|
|
DiffStats:
|
|
description: |
|
|
Aggregate `+/-` line counts across all files in a diff. Binary, sensitive, symlink, and submodule
|
|
files contribute 0/0 since they have no line-level diff. Both fields
|
|
are 0 for empty / pre-start envelopes.
|
|
type: object
|
|
required:
|
|
- additions
|
|
- deletions
|
|
properties:
|
|
additions:
|
|
type: integer
|
|
description: Total lines added.
|
|
example: 567
|
|
deletions:
|
|
type: integer
|
|
description: Total lines deleted.
|
|
example: 234
|
|
|
|
DiffSummary:
|
|
description: Cheap aggregate file and line counts for a run diff.
|
|
type: object
|
|
required:
|
|
- files_changed
|
|
- additions
|
|
- deletions
|
|
properties:
|
|
files_changed:
|
|
type: integer
|
|
description: Total number of changed files, including binary files.
|
|
example: 42
|
|
additions:
|
|
type: integer
|
|
description: Total lines added across text files.
|
|
example: 567
|
|
deletions:
|
|
type: integer
|
|
description: Total lines deleted across text files.
|
|
example: 234
|
|
|
|
RunFilesMeta:
|
|
description: |
|
|
Metadata for a `PaginatedRunFileList` response.
|
|
|
|
Replaces `PaginationMeta` on the files endpoint — the naturally-bounded list does not use cursor pagination but exposes caps and a degraded-response path instead.
|
|
type: object
|
|
required:
|
|
- truncated
|
|
- total_changed
|
|
- stats
|
|
properties:
|
|
stats:
|
|
$ref: "#/components/schemas/DiffStats"
|
|
truncated:
|
|
type: boolean
|
|
description: True when any cap (file count, per-file size, or aggregate size) was hit for this response.
|
|
example: false
|
|
files_omitted_by_budget:
|
|
type: integer
|
|
description: Number of files dropped because the aggregate 5 MiB budget was exhausted. Zero or absent when no files were dropped for budget reasons.
|
|
example: 0
|
|
total_changed:
|
|
type: integer
|
|
description: Total files changed in the run (before caps were applied). May exceed `data.length` when truncation occurred.
|
|
example: 3
|
|
to_sha:
|
|
type: string
|
|
description: Head SHA the diff (or patch) was resolved against.
|
|
pattern: "^[0-9a-f]{7,40}$"
|
|
example: "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
|
|
to_sha_committed_at:
|
|
type: string
|
|
format: date-time
|
|
description: Commit time of `to_sha`, used by the UI for the "Checkpoint Xm ago" freshness label on Running runs.
|
|
degraded:
|
|
type: boolean
|
|
description: When `true`, every entry in `data` has null `contents` on both sides; non-sensitive non-flagged entries also include `unified_patch`. Entries flagged `sensitive` / `binary` / `symlink` / `submodule` / `truncated` render via the same placeholders used in the live path (the flags drive rendering; contents are null in degraded mode regardless). The data shape is otherwise identical to the live path.
|
|
example: false
|
|
degraded_reason:
|
|
type: string
|
|
description: Why the response degraded. Absent when `degraded` is `false` or omitted.
|
|
enum:
|
|
- sandbox_unreachable
|
|
- sandbox_gone
|
|
- provider_unsupported
|
|
|
|
PaginatedRunFileList:
|
|
description: |
|
|
List of file diffs produced by a run, with metadata describing truncation and degraded-response state.
|
|
|
|
Naturally bounded: at most 200 files per response. Consumers should inspect `meta.truncated` rather than assuming `data.length` equals the run's total change count.
|
|
type: object
|
|
required:
|
|
- data
|
|
- meta
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/FileDiff"
|
|
meta:
|
|
$ref: "#/components/schemas/RunFilesMeta"
|
|
|
|
# ── Billing Schemas ──────────────────────────────────────────────────
|
|
|
|
RunBillingStage:
|
|
description: Token counts and billed totals for one workflow node within a run. Rows are grouped by node; billing and runtime sum every visit of that node.
|
|
type: object
|
|
required:
|
|
- stage
|
|
- model
|
|
- billing
|
|
- runtime_secs
|
|
properties:
|
|
stage:
|
|
$ref: "#/components/schemas/BillingStageRef"
|
|
model:
|
|
description: Latest usage-bearing visit model for this node; null when no visit used an LLM model.
|
|
oneOf:
|
|
- $ref: "#/components/schemas/ModelReference"
|
|
- type: "null"
|
|
billing:
|
|
$ref: "#/components/schemas/BilledTokenCounts"
|
|
runtime_secs:
|
|
type: number
|
|
description: Wall-clock runtime in seconds, summed across every visit of this node.
|
|
example: 154.0
|
|
started_at:
|
|
type: ["string", "null"]
|
|
format: date-time
|
|
description: Wall-clock time the latest attempt of this stage started, if known.
|
|
example: "2026-04-29T12:34:56Z"
|
|
state:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/StageState"
|
|
- type: "null"
|
|
description: Lifecycle state of the stage. Use to detect in-flight rows for client-side runtime ticking.
|
|
|
|
RunBillingTotals:
|
|
description: Aggregate billing totals across all stages of a run.
|
|
type: object
|
|
required:
|
|
- runtime_secs
|
|
- input_tokens
|
|
- output_tokens
|
|
- total_tokens
|
|
- reasoning_tokens
|
|
- cache_read_tokens
|
|
- cache_write_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 usage-bearing stage visits 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-node billing breakdown. Each row sums billing and runtime across all visits of that node.
|
|
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: Current in-memory server settings view.
|
|
type: object
|
|
required: [server, features]
|
|
properties:
|
|
server:
|
|
$ref: "#/components/schemas/ServerNamespace"
|
|
features:
|
|
$ref: "#/components/schemas/FeaturesNamespace"
|
|
|
|
ServerNamespace:
|
|
type: object
|
|
required:
|
|
- listen
|
|
- api
|
|
- web
|
|
- auth
|
|
- ip_allowlist
|
|
- storage
|
|
- artifacts
|
|
- slatedb
|
|
- scheduler
|
|
- logging
|
|
- integrations
|
|
properties:
|
|
listen:
|
|
$ref: "#/components/schemas/ServerListenSettings"
|
|
api:
|
|
$ref: "#/components/schemas/ServerApiSettings"
|
|
web:
|
|
$ref: "#/components/schemas/ServerWebSettings"
|
|
auth:
|
|
$ref: "#/components/schemas/ServerAuthSettings"
|
|
ip_allowlist:
|
|
$ref: "#/components/schemas/ServerIpAllowlistSettings"
|
|
storage:
|
|
$ref: "#/components/schemas/ServerStorageSettings"
|
|
artifacts:
|
|
$ref: "#/components/schemas/ServerArtifactsSettings"
|
|
slatedb:
|
|
$ref: "#/components/schemas/ServerSlateDbSettings"
|
|
scheduler:
|
|
$ref: "#/components/schemas/ServerSchedulerSettings"
|
|
logging:
|
|
$ref: "#/components/schemas/ServerLoggingSettings"
|
|
integrations:
|
|
$ref: "#/components/schemas/ServerIntegrationsSettings"
|
|
|
|
FeaturesNamespace:
|
|
type: object
|
|
required: [session_sandboxes]
|
|
properties:
|
|
session_sandboxes:
|
|
type: boolean
|
|
|
|
ServerListenSettings:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/ServerListenTcpSettings"
|
|
- $ref: "#/components/schemas/ServerListenUnixSettings"
|
|
|
|
ServerListenTcpSettings:
|
|
type: object
|
|
required: [type, address]
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [tcp]
|
|
address:
|
|
type: string
|
|
|
|
ServerListenUnixSettings:
|
|
type: object
|
|
required: [type, path]
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [unix]
|
|
path:
|
|
type: string
|
|
|
|
ServerApiSettings:
|
|
type: object
|
|
required: [url]
|
|
properties:
|
|
url:
|
|
type: ["string", "null"]
|
|
|
|
ServerWebSettings:
|
|
type: object
|
|
required: [enabled, url]
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
url:
|
|
type: string
|
|
|
|
ServerAuthSettings:
|
|
type: object
|
|
required: [methods, github]
|
|
properties:
|
|
methods:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/ServerAuthMethod"
|
|
github:
|
|
$ref: "#/components/schemas/ServerAuthGithubSettings"
|
|
|
|
ServerAuthMethod:
|
|
type: string
|
|
enum: [dev-token, github]
|
|
|
|
ServerAuthGithubSettings:
|
|
type: object
|
|
required: [allowed_usernames]
|
|
properties:
|
|
allowed_usernames:
|
|
type: array
|
|
items:
|
|
type: string
|
|
|
|
ServerIpAllowlistSettings:
|
|
type: object
|
|
required: [entries, trusted_proxy_count]
|
|
properties:
|
|
entries:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/IpAllowEntry"
|
|
trusted_proxy_count:
|
|
type: integer
|
|
|
|
ServerIpAllowlistOverrideSettings:
|
|
type: object
|
|
required: [entries, trusted_proxy_count]
|
|
properties:
|
|
entries:
|
|
type: ["array", "null"]
|
|
items:
|
|
$ref: "#/components/schemas/IpAllowEntry"
|
|
trusted_proxy_count:
|
|
type: ["integer", "null"]
|
|
|
|
IpAllowEntry:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/LiteralIpAllowEntry"
|
|
- $ref: "#/components/schemas/GitHubMetaHooksEntry"
|
|
|
|
LiteralIpAllowEntry:
|
|
type: object
|
|
required: [Literal]
|
|
properties:
|
|
Literal:
|
|
type: string
|
|
|
|
GitHubMetaHooksEntry:
|
|
type: string
|
|
enum: [GitHubMetaHooks]
|
|
|
|
ServerStorageSettings:
|
|
type: object
|
|
required: [root]
|
|
properties:
|
|
root:
|
|
type: string
|
|
|
|
ServerArtifactsSettings:
|
|
type: object
|
|
required: [prefix, store]
|
|
properties:
|
|
prefix:
|
|
type: string
|
|
store:
|
|
$ref: "#/components/schemas/ObjectStoreSettings"
|
|
|
|
ServerSlateDbSettings:
|
|
type: object
|
|
required: [prefix, store, flush_interval, disk_cache]
|
|
properties:
|
|
prefix:
|
|
type: string
|
|
store:
|
|
$ref: "#/components/schemas/ObjectStoreSettings"
|
|
flush_interval:
|
|
type: string
|
|
disk_cache:
|
|
type: boolean
|
|
|
|
ObjectStoreSettings:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/ObjectStoreLocalSettings"
|
|
- $ref: "#/components/schemas/ObjectStoreS3Settings"
|
|
|
|
ObjectStoreLocalSettings:
|
|
type: object
|
|
required: [type, root]
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [local]
|
|
root:
|
|
type: string
|
|
|
|
ObjectStoreS3Settings:
|
|
type: object
|
|
required: [type, bucket, region, endpoint, path_style]
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [s3]
|
|
bucket:
|
|
type: string
|
|
region:
|
|
type: string
|
|
endpoint:
|
|
type: ["string", "null"]
|
|
path_style:
|
|
type: boolean
|
|
|
|
ServerSchedulerSettings:
|
|
type: object
|
|
required: [max_concurrent_runs]
|
|
properties:
|
|
max_concurrent_runs:
|
|
type: integer
|
|
|
|
ServerLoggingSettings:
|
|
type: object
|
|
required: [level, destination]
|
|
properties:
|
|
level:
|
|
type: ["string", "null"]
|
|
destination:
|
|
$ref: "#/components/schemas/LogDestination"
|
|
|
|
LogDestination:
|
|
type: string
|
|
enum: [file, stdout]
|
|
|
|
ServerIntegrationsSettings:
|
|
type: object
|
|
required: [github, slack, discord, teams]
|
|
properties:
|
|
github:
|
|
$ref: "#/components/schemas/GithubIntegrationSettings"
|
|
slack:
|
|
$ref: "#/components/schemas/SlackIntegrationSettings"
|
|
discord:
|
|
$ref: "#/components/schemas/DiscordIntegrationSettings"
|
|
teams:
|
|
$ref: "#/components/schemas/TeamsIntegrationSettings"
|
|
|
|
GithubIntegrationSettings:
|
|
type: object
|
|
required:
|
|
- enabled
|
|
- strategy
|
|
- app_id
|
|
- client_id
|
|
- slug
|
|
- webhooks
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
strategy:
|
|
$ref: "#/components/schemas/GithubIntegrationStrategy"
|
|
app_id:
|
|
type: ["string", "null"]
|
|
client_id:
|
|
type: ["string", "null"]
|
|
slug:
|
|
type: ["string", "null"]
|
|
webhooks:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/IntegrationWebhooksSettings"
|
|
- type: "null"
|
|
|
|
GithubIntegrationStrategy:
|
|
type: string
|
|
enum: [token, app]
|
|
|
|
SlackIntegrationSettings:
|
|
type: object
|
|
required: [enabled, default_channel]
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
default_channel:
|
|
type: ["string", "null"]
|
|
|
|
DiscordIntegrationSettings:
|
|
type: object
|
|
required: [enabled]
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
|
|
TeamsIntegrationSettings:
|
|
type: object
|
|
required: [enabled]
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
|
|
IntegrationWebhooksSettings:
|
|
type: object
|
|
required: [strategy, ip_allowlist]
|
|
properties:
|
|
strategy:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/WebhookStrategy"
|
|
- type: "null"
|
|
ip_allowlist:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/ServerIpAllowlistOverrideSettings"
|
|
- type: "null"
|
|
|
|
WebhookStrategy:
|
|
type: string
|
|
enum: [tailscale_funnel, server_url]
|
|
|
|
WorkflowSettings:
|
|
description: |
|
|
The persisted dense `WorkflowSettings` snapshot used for a specific run.
|
|
This matches the resolved run settings recorded at launch time.
|
|
type: object
|
|
required:
|
|
- project
|
|
- workflow
|
|
- run
|
|
properties:
|
|
project:
|
|
$ref: "#/components/schemas/ProjectNamespace"
|
|
workflow:
|
|
$ref: "#/components/schemas/WorkflowNamespace"
|
|
run:
|
|
$ref: "#/components/schemas/RunNamespace"
|
|
|
|
InterpString:
|
|
description: Resolved config string that may contain env interpolation tokens.
|
|
type: string
|
|
|
|
StringMap:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
|
|
TomlValue:
|
|
description: Arbitrary TOML-compatible value.
|
|
|
|
ProjectNamespace:
|
|
type: object
|
|
required: [name, description, directory, metadata]
|
|
properties:
|
|
name:
|
|
type: ["string", "null"]
|
|
description:
|
|
type: ["string", "null"]
|
|
directory:
|
|
type: string
|
|
metadata:
|
|
$ref: "#/components/schemas/StringMap"
|
|
|
|
WorkflowNamespace:
|
|
type: object
|
|
required: [name, description, graph, metadata]
|
|
properties:
|
|
name:
|
|
type: ["string", "null"]
|
|
description:
|
|
type: ["string", "null"]
|
|
graph:
|
|
type: string
|
|
metadata:
|
|
$ref: "#/components/schemas/StringMap"
|
|
|
|
RunNamespace:
|
|
type: object
|
|
required:
|
|
- goal
|
|
- working_dir
|
|
- metadata
|
|
- inputs
|
|
- model
|
|
- git
|
|
- prepare
|
|
- execution
|
|
- checkpoint
|
|
- sandbox
|
|
- notifications
|
|
- interviews
|
|
- agent
|
|
- hooks
|
|
- scm
|
|
- pull_request
|
|
- artifacts
|
|
- integrations
|
|
properties:
|
|
goal:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/RunGoal"
|
|
- type: "null"
|
|
working_dir:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/InterpString"
|
|
- type: "null"
|
|
metadata:
|
|
$ref: "#/components/schemas/StringMap"
|
|
inputs:
|
|
type: object
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/TomlValue"
|
|
model:
|
|
$ref: "#/components/schemas/RunModelSettings"
|
|
git:
|
|
$ref: "#/components/schemas/RunGitSettings"
|
|
prepare:
|
|
$ref: "#/components/schemas/RunPrepareSettings"
|
|
execution:
|
|
$ref: "#/components/schemas/RunExecutionSettings"
|
|
checkpoint:
|
|
$ref: "#/components/schemas/RunCheckpointSettings"
|
|
sandbox:
|
|
$ref: "#/components/schemas/RunSandboxSettings"
|
|
notifications:
|
|
type: object
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/NotificationRouteSettings"
|
|
interviews:
|
|
$ref: "#/components/schemas/RunInterviewsSettings"
|
|
agent:
|
|
$ref: "#/components/schemas/RunAgentSettings"
|
|
hooks:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/HookDefinition"
|
|
scm:
|
|
$ref: "#/components/schemas/RunScmSettings"
|
|
pull_request:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/PullRequestSettings"
|
|
- type: "null"
|
|
artifacts:
|
|
$ref: "#/components/schemas/ArtifactsSettings"
|
|
integrations:
|
|
$ref: "#/components/schemas/RunIntegrationsSettings"
|
|
|
|
RunIntegrationsSettings:
|
|
type: object
|
|
required: [github]
|
|
properties:
|
|
github:
|
|
$ref: "#/components/schemas/RunIntegrationsGithubSettings"
|
|
|
|
RunIntegrationsGithubSettings:
|
|
type: object
|
|
required: [permissions]
|
|
properties:
|
|
permissions:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
|
|
RunGoal:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/RunGoalInline"
|
|
- $ref: "#/components/schemas/RunGoalFile"
|
|
|
|
RunGoalInline:
|
|
type: object
|
|
required: [type, value]
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [inline]
|
|
value:
|
|
$ref: "#/components/schemas/InterpString"
|
|
|
|
RunGoalFile:
|
|
type: object
|
|
required: [type, value]
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [file]
|
|
value:
|
|
$ref: "#/components/schemas/InterpString"
|
|
|
|
ModelRef:
|
|
type: string
|
|
|
|
RunModelSettings:
|
|
type: object
|
|
required: [provider, name, fallbacks]
|
|
properties:
|
|
provider:
|
|
type: ["string", "null"]
|
|
name:
|
|
type: ["string", "null"]
|
|
fallbacks:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/ModelRef"
|
|
|
|
RunGitSettings:
|
|
type: object
|
|
required: [author]
|
|
properties:
|
|
author:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/GitAuthorSettings"
|
|
- type: "null"
|
|
|
|
GitAuthorSettings:
|
|
type: object
|
|
required: [name, email]
|
|
properties:
|
|
name:
|
|
type: ["string", "null"]
|
|
email:
|
|
type: ["string", "null"]
|
|
|
|
RunPrepareSettings:
|
|
type: object
|
|
required: [commands, timeout_ms]
|
|
properties:
|
|
commands:
|
|
type: array
|
|
items:
|
|
type: string
|
|
timeout_ms:
|
|
type: integer
|
|
format: int64
|
|
|
|
RunExecutionSettings:
|
|
type: object
|
|
required: [mode, approval]
|
|
properties:
|
|
mode:
|
|
$ref: "#/components/schemas/RunMode"
|
|
approval:
|
|
$ref: "#/components/schemas/ApprovalMode"
|
|
|
|
RunMode:
|
|
type: string
|
|
enum: [normal, dry_run]
|
|
|
|
ApprovalMode:
|
|
type: string
|
|
enum: [prompt, auto]
|
|
|
|
RunCheckpointSettings:
|
|
type: object
|
|
required: [exclude_globs]
|
|
properties:
|
|
exclude_globs:
|
|
type: array
|
|
items:
|
|
type: string
|
|
|
|
RunSandboxSettings:
|
|
type: object
|
|
required: [provider, preserve, stop_on_terminal, devcontainer, env, local, docker, daytona]
|
|
properties:
|
|
provider:
|
|
type: string
|
|
preserve:
|
|
type: boolean
|
|
stop_on_terminal:
|
|
type: boolean
|
|
devcontainer:
|
|
type: boolean
|
|
env:
|
|
type: object
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/InterpString"
|
|
local:
|
|
$ref: "#/components/schemas/LocalSandboxSettings"
|
|
docker:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/DockerSettings"
|
|
- type: "null"
|
|
daytona:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/DaytonaSettings"
|
|
- type: "null"
|
|
|
|
LocalSandboxSettings:
|
|
type: object
|
|
required: [worktree_mode]
|
|
properties:
|
|
worktree_mode:
|
|
$ref: "#/components/schemas/WorktreeMode"
|
|
|
|
WorktreeMode:
|
|
type: string
|
|
enum: [always, clean, dirty, never]
|
|
|
|
DockerSettings:
|
|
type: object
|
|
required: [image, network_mode, memory_limit, cpu_quota, env_vars, skip_clone]
|
|
properties:
|
|
image:
|
|
type: string
|
|
network_mode:
|
|
type: ["string", "null"]
|
|
memory_limit:
|
|
type: ["integer", "null"]
|
|
format: int64
|
|
cpu_quota:
|
|
type: ["integer", "null"]
|
|
format: int64
|
|
env_vars:
|
|
type: object
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/InterpString"
|
|
skip_clone:
|
|
type: boolean
|
|
|
|
DaytonaSettings:
|
|
type: object
|
|
required: [auto_stop_interval, labels, snapshot, network, skip_clone]
|
|
properties:
|
|
auto_stop_interval:
|
|
type: ["integer", "null"]
|
|
format: int32
|
|
labels:
|
|
$ref: "#/components/schemas/StringMap"
|
|
snapshot:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/DaytonaSnapshotSettings"
|
|
- type: "null"
|
|
network:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/DaytonaNetworkLayer"
|
|
- type: "null"
|
|
skip_clone:
|
|
type: boolean
|
|
|
|
DaytonaSnapshotSettings:
|
|
type: object
|
|
required: [name, cpu, memory_gb, disk_gb, dockerfile]
|
|
properties:
|
|
name:
|
|
type: string
|
|
cpu:
|
|
type: ["integer", "null"]
|
|
format: int32
|
|
memory_gb:
|
|
type: ["integer", "null"]
|
|
format: int32
|
|
disk_gb:
|
|
type: ["integer", "null"]
|
|
format: int32
|
|
dockerfile:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/DockerfileSource"
|
|
- type: "null"
|
|
|
|
DockerfileSource:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/DockerfileSourceInline"
|
|
- $ref: "#/components/schemas/DockerfileSourcePath"
|
|
|
|
DockerfileSourceInline:
|
|
type: object
|
|
required: [type, value]
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [inline]
|
|
value:
|
|
type: string
|
|
|
|
DockerfileSourcePath:
|
|
type: object
|
|
required: [type, path]
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [path]
|
|
path:
|
|
type: string
|
|
|
|
DaytonaNetworkLayer:
|
|
description: Daytona network access policy.
|
|
oneOf:
|
|
- type: string
|
|
enum: [block, allow_all]
|
|
- type: object
|
|
required: [allow_list]
|
|
properties:
|
|
allow_list:
|
|
type: object
|
|
required: [allow_list]
|
|
properties:
|
|
allow_list:
|
|
type: array
|
|
items:
|
|
type: string
|
|
|
|
NotificationRouteSettings:
|
|
type: object
|
|
required: [enabled, provider, events, slack, discord, teams]
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
provider:
|
|
type: ["string", "null"]
|
|
events:
|
|
type: array
|
|
items:
|
|
type: string
|
|
slack:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/NotificationProviderSettings"
|
|
- type: "null"
|
|
discord:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/NotificationProviderSettings"
|
|
- type: "null"
|
|
teams:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/NotificationProviderSettings"
|
|
- type: "null"
|
|
|
|
NotificationProviderSettings:
|
|
type: object
|
|
required: [channel]
|
|
properties:
|
|
channel:
|
|
type: ["string", "null"]
|
|
|
|
RunInterviewsSettings:
|
|
type: object
|
|
required: [provider, slack, discord, teams]
|
|
properties:
|
|
provider:
|
|
type: ["string", "null"]
|
|
slack:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/InterviewProviderSettings"
|
|
- type: "null"
|
|
discord:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/InterviewProviderSettings"
|
|
- type: "null"
|
|
teams:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/InterviewProviderSettings"
|
|
- type: "null"
|
|
|
|
InterviewProviderSettings:
|
|
type: object
|
|
required: [channel]
|
|
properties:
|
|
channel:
|
|
type: ["string", "null"]
|
|
|
|
RunAgentSettings:
|
|
type: object
|
|
required: [permissions, mcps]
|
|
properties:
|
|
permissions:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/AgentPermissions"
|
|
- type: "null"
|
|
mcps:
|
|
type: object
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/McpServerSettings"
|
|
|
|
AgentPermissions:
|
|
type: string
|
|
enum: [read-only, read-write, full]
|
|
|
|
McpServerSettings:
|
|
type: object
|
|
required: [name, transport, startup_timeout_secs, tool_timeout_secs]
|
|
properties:
|
|
name:
|
|
type: string
|
|
transport:
|
|
$ref: "#/components/schemas/McpTransport"
|
|
startup_timeout_secs:
|
|
type: integer
|
|
format: int64
|
|
tool_timeout_secs:
|
|
type: integer
|
|
format: int64
|
|
|
|
McpTransport:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/McpTransportStdio"
|
|
- $ref: "#/components/schemas/McpTransportHttp"
|
|
- $ref: "#/components/schemas/McpTransportSandbox"
|
|
|
|
McpTransportStdio:
|
|
type: object
|
|
required: [type, command, env]
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [stdio]
|
|
command:
|
|
type: array
|
|
items:
|
|
type: string
|
|
env:
|
|
$ref: "#/components/schemas/StringMap"
|
|
|
|
McpTransportHttp:
|
|
type: object
|
|
required: [type, url, headers]
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [http]
|
|
url:
|
|
type: string
|
|
headers:
|
|
$ref: "#/components/schemas/StringMap"
|
|
|
|
McpTransportSandbox:
|
|
type: object
|
|
required: [type, command, port, env]
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [sandbox]
|
|
command:
|
|
type: array
|
|
items:
|
|
type: string
|
|
port:
|
|
type: integer
|
|
format: int32
|
|
env:
|
|
$ref: "#/components/schemas/StringMap"
|
|
|
|
HookDefinition:
|
|
type: object
|
|
required: [name, event, command, matcher, blocking, timeout_ms, sandbox]
|
|
properties:
|
|
name:
|
|
type: ["string", "null"]
|
|
event:
|
|
$ref: "#/components/schemas/HookEvent"
|
|
command:
|
|
type: ["string", "null"]
|
|
type:
|
|
type: ["string", "null"]
|
|
enum: [command, http, prompt, agent, null]
|
|
url:
|
|
type: ["string", "null"]
|
|
headers:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/StringMap"
|
|
- type: "null"
|
|
allowed_env_vars:
|
|
type: array
|
|
items:
|
|
type: string
|
|
tls:
|
|
$ref: "#/components/schemas/TlsMode"
|
|
prompt:
|
|
type: ["string", "null"]
|
|
model:
|
|
type: ["string", "null"]
|
|
max_tool_rounds:
|
|
type: ["integer", "null"]
|
|
format: int32
|
|
matcher:
|
|
type: ["string", "null"]
|
|
blocking:
|
|
type: ["boolean", "null"]
|
|
timeout_ms:
|
|
type: ["integer", "null"]
|
|
format: int64
|
|
sandbox:
|
|
type: ["boolean", "null"]
|
|
|
|
HookEvent:
|
|
type: string
|
|
enum:
|
|
- run_start
|
|
- run_complete
|
|
- run_failed
|
|
- stage_start
|
|
- stage_complete
|
|
- stage_failed
|
|
- stage_retrying
|
|
- edge_selected
|
|
- parallel_start
|
|
- parallel_complete
|
|
- sandbox_ready
|
|
- sandbox_cleanup
|
|
- checkpoint_saved
|
|
- pre_tool_use
|
|
- post_tool_use
|
|
- post_tool_use_failure
|
|
|
|
TlsMode:
|
|
type: string
|
|
enum: [verify, no_verify, off]
|
|
|
|
RunScmSettings:
|
|
type: object
|
|
required: [provider, owner, repository, github]
|
|
properties:
|
|
provider:
|
|
type: ["string", "null"]
|
|
owner:
|
|
type: ["string", "null"]
|
|
repository:
|
|
type: ["string", "null"]
|
|
github:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/ScmGitHubSettings"
|
|
- type: "null"
|
|
|
|
ScmGitHubSettings:
|
|
type: object
|
|
|
|
PullRequestSettings:
|
|
type: object
|
|
required: [enabled, draft, auto_merge, merge_strategy]
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
draft:
|
|
type: boolean
|
|
auto_merge:
|
|
type: boolean
|
|
merge_strategy:
|
|
$ref: "#/components/schemas/MergeMethod"
|
|
|
|
ArtifactsSettings:
|
|
type: object
|
|
required: [include]
|
|
properties:
|
|
include:
|
|
type: array
|
|
items:
|
|
type: string
|
|
|
|
SystemInfoResponse:
|
|
description: Runtime information for the active Fabro server process.
|
|
type: object
|
|
properties:
|
|
version:
|
|
type: string
|
|
description: Server version string.
|
|
server_url:
|
|
type: string
|
|
description: Configured public server URL for browser and CLI authentication flows.
|
|
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.
|
|
|
|
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.
|
|
|
|
SystemRepairRunsResponse:
|
|
description: Runs that need manual repair or deletion because they cannot be loaded.
|
|
type: object
|
|
required: [runs, total_count]
|
|
properties:
|
|
runs:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/SystemRepairRunIssue"
|
|
total_count:
|
|
type: integer
|
|
format: int64
|
|
description: Count of run repair issues.
|
|
|
|
SystemRepairRunIssue:
|
|
description: One cataloged run that cannot be loaded from durable storage.
|
|
type: object
|
|
required: [run_id, created_at, error]
|
|
properties:
|
|
run_id:
|
|
type: string
|
|
description: Run identifier.
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp encoded in the run identifier.
|
|
error:
|
|
type: string
|
|
description: Error produced while loading the run projection.
|
|
|
|
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
|