mirror of
https://github.com/fabro-sh/fabro.git
synced 2026-09-05 08:10:39 +00:00
4976358260
The API was returning human-readable strings like "2h ago" and "in 4 hours" instead of real timestamps. The frontend now formats these for display using timeAgo() and a new timeUntil() helper. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
3173 lines
94 KiB
YAML
3173 lines
94 KiB
YAML
openapi: "3.1.0"
|
|
info:
|
|
title: Arc Run API
|
|
version: "0.1.0"
|
|
description: HTTP API for managing Arc workflow run executions.
|
|
|
|
tags:
|
|
- name: Discovery
|
|
description: API discovery and health
|
|
- name: Runs
|
|
description: Run management operations
|
|
- name: Human-in-the-Loop
|
|
description: Questions, answers, and steering for runs
|
|
- name: Run Outputs
|
|
description: Files and verifications produced by runs
|
|
- name: Run Internals
|
|
description: Internal run details (stages, turns, context, configuration)
|
|
- name: Workflows
|
|
description: Workflow definitions and execution
|
|
- name: Verifications
|
|
description: Verification categories and controls
|
|
- name: Usage
|
|
description: Token and cost usage
|
|
- name: Insights
|
|
description: SQL query editor and history
|
|
- name: Sessions
|
|
description: Interactive chat sessions
|
|
- name: Retros
|
|
description: Run retrospectives
|
|
- name: Projects
|
|
description: Project and branch management
|
|
- name: Settings
|
|
description: Platform configuration
|
|
|
|
security:
|
|
- BearerAuth: []
|
|
- mTLS: []
|
|
|
|
paths:
|
|
# ── Discovery ────────────────────────────────────────────────────────
|
|
|
|
/:
|
|
get:
|
|
operationId: getRoot
|
|
tags: [Discovery]
|
|
summary: API Discovery
|
|
description: Returns discovery URLs for the API.
|
|
security: []
|
|
responses:
|
|
"200":
|
|
description: Discovery URLs
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RootResponse"
|
|
|
|
/health:
|
|
get:
|
|
operationId: getHealth
|
|
tags: [Discovery]
|
|
summary: Health Check
|
|
description: Returns service health status. Used by load balancers and monitoring.
|
|
security: []
|
|
responses:
|
|
"200":
|
|
description: Service is healthy
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/HealthResponse"
|
|
|
|
/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
|
|
|
|
/user:
|
|
get:
|
|
operationId: getUser
|
|
tags: [Discovery]
|
|
summary: Current User
|
|
description: Returns info about the authenticated user.
|
|
responses:
|
|
"200":
|
|
description: User info
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/UserResponse"
|
|
"401":
|
|
description: Not authenticated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
# ── Runs ──────────────────────────────────────────────────────────────
|
|
|
|
/runs:
|
|
get:
|
|
operationId: listRuns
|
|
tags: [Runs]
|
|
summary: List Runs
|
|
description: Returns a paginated list of runs for the board view, ordered by recency.
|
|
parameters:
|
|
- $ref: "#/components/parameters/PageLimit"
|
|
- $ref: "#/components/parameters/PageOffset"
|
|
responses:
|
|
"200":
|
|
description: Paginated list of runs for the board view
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PaginatedRunList"
|
|
post:
|
|
operationId: startRun
|
|
tags: [Runs]
|
|
summary: Start Run
|
|
description: Queues a new workflow run from a DOT graph source. The run is created in `queued` status and will be picked up by the scheduler.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/StartRunRequest"
|
|
responses:
|
|
"201":
|
|
description: Run created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RunStatusResponse"
|
|
"400":
|
|
description: Invalid DOT source
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/runs/{id}:
|
|
get:
|
|
operationId: retrieveRun
|
|
tags: [Runs]
|
|
summary: Retrieve Run
|
|
description: Returns the current status of a run, including error details and queue position if applicable.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
responses:
|
|
"200":
|
|
description: Run status
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RunStatusResponse"
|
|
"404":
|
|
description: Run not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/runs/{id}/cancel:
|
|
post:
|
|
operationId: cancelRun
|
|
tags: [Runs]
|
|
summary: Cancel Run
|
|
description: Cancels a running or queued run. Returns 409 if the run has already completed or been cancelled.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
responses:
|
|
"200":
|
|
description: Run cancelled
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RunStatusResponse"
|
|
"404":
|
|
description: Run not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"409":
|
|
description: Run is not running
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/runs/{id}/graph:
|
|
get:
|
|
operationId: retrieveRunGraph
|
|
tags: [Runs]
|
|
summary: Render SVG
|
|
description: Renders the workflow graph as an SVG image using Graphviz.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
responses:
|
|
"200":
|
|
description: SVG image of the workflow graph
|
|
content:
|
|
image/svg+xml:
|
|
schema:
|
|
type: string
|
|
"404":
|
|
description: Run not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"502":
|
|
description: Graphviz not available
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/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:
|
|
- type: object
|
|
additionalProperties: true
|
|
- type: "null"
|
|
"404":
|
|
description: Run not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/runs/{id}/context:
|
|
get:
|
|
operationId: retrieveRunContext
|
|
tags: [Run Internals]
|
|
summary: Retrieve Run Context
|
|
description: Returns the key-value context map accumulated during the run. Empty if the run has not started.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
responses:
|
|
"200":
|
|
description: Context key-value map
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: true
|
|
"404":
|
|
description: Run not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/runs/{id}/events:
|
|
get:
|
|
operationId: streamRunEvents
|
|
tags: [Runs]
|
|
summary: Stream Run Events
|
|
description: Opens a server-sent event (SSE) stream for real-time run updates. Returns 410 if the stream has been closed.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
responses:
|
|
"200":
|
|
description: Server-sent event stream
|
|
content:
|
|
text/event-stream:
|
|
schema:
|
|
type: string
|
|
"404":
|
|
description: Run not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"410":
|
|
description: Event stream closed
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/runs/{id}/questions:
|
|
get:
|
|
operationId: listRunQuestions
|
|
tags: [Human-in-the-Loop]
|
|
summary: List Run Questions
|
|
description: Returns pending human-in-the-loop questions for a run. Questions are generated when the workflow needs user input to proceed.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
- $ref: "#/components/parameters/PageLimit"
|
|
- $ref: "#/components/parameters/PageOffset"
|
|
responses:
|
|
"200":
|
|
description: Array of pending questions
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PaginatedApiQuestionList"
|
|
"404":
|
|
description: Run not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/runs/{id}/questions/{qid}/answer:
|
|
post:
|
|
operationId: submitRunAnswer
|
|
tags: [Human-in-the-Loop]
|
|
summary: Submit Run Answer
|
|
description: Submits an answer to a pending question. The answer can be freeform text or a selected option key, depending on the question type.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
- $ref: "#/components/parameters/QuestionId"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SubmitAnswerRequest"
|
|
responses:
|
|
"204":
|
|
description: Answer accepted
|
|
"400":
|
|
description: Invalid option key
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"404":
|
|
description: Run not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
"409":
|
|
description: Question no longer exists or already answered
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/runs/{id}/retro:
|
|
get:
|
|
operationId: retrieveRetro
|
|
tags: [Retros]
|
|
summary: Retrieve Retro
|
|
description: Returns the retrospective analysis for a completed run, or null if the retro has not been generated yet.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
responses:
|
|
"200":
|
|
description: Retro data (null if not yet available)
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- type: object
|
|
additionalProperties: true
|
|
- type: "null"
|
|
"404":
|
|
description: Run not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/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.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
- $ref: "#/components/parameters/PageLimit"
|
|
- $ref: "#/components/parameters/PageOffset"
|
|
responses:
|
|
"200":
|
|
description: Array of run stages
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PaginatedRunStageList"
|
|
"404":
|
|
description: Run not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/runs/{id}/stages/{stageId}/turns:
|
|
get:
|
|
operationId: listStageTurns
|
|
tags: [Run Internals]
|
|
summary: List Stage Turns
|
|
description: Returns a paginated list of conversation turns within a specific stage, including system prompts, assistant responses, and tool invocations.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
- $ref: "#/components/parameters/StageId"
|
|
- $ref: "#/components/parameters/PageLimit"
|
|
- $ref: "#/components/parameters/PageOffset"
|
|
responses:
|
|
"200":
|
|
description: Paginated list of conversation turns
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PaginatedStageTurnList"
|
|
"404":
|
|
description: Run or stage not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/runs/{id}/compare:
|
|
get:
|
|
operationId: retrieveRunDiff
|
|
tags: [Run Outputs]
|
|
summary: List Run Compare
|
|
description: Returns file-level diffs produced by the run, optionally filtered to a specific checkpoint.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
- $ref: "#/components/parameters/CheckpointFilter"
|
|
responses:
|
|
"200":
|
|
description: File changes with checkpoint metadata
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RunCompare"
|
|
"404":
|
|
description: Run not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/runs/{id}/usage:
|
|
get:
|
|
operationId: retrieveRunUsage
|
|
tags: [Run Outputs]
|
|
summary: Retrieve Run Usage
|
|
description: Returns token and cost usage broken down by stage and model for a specific run.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
responses:
|
|
"200":
|
|
description: Usage data
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RunUsage"
|
|
"404":
|
|
description: Run not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/runs/{id}/verifications:
|
|
get:
|
|
operationId: listRunVerifications
|
|
tags: [Run Outputs]
|
|
summary: List Run Verifications
|
|
description: Returns verification results for a run, organized by category with individual control statuses.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
- $ref: "#/components/parameters/PageLimit"
|
|
- $ref: "#/components/parameters/PageOffset"
|
|
responses:
|
|
"200":
|
|
description: Array of verification categories with controls
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PaginatedRunVerificationList"
|
|
"404":
|
|
description: Run not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/runs/{id}/configuration:
|
|
get:
|
|
operationId: retrieveRunConfiguration
|
|
tags: [Run Internals]
|
|
summary: Retrieve Run Configuration
|
|
description: Returns the TOML configuration file content used to launch this run.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
responses:
|
|
"200":
|
|
description: Configuration content
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
"404":
|
|
description: Run not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/runs/{id}/steer:
|
|
post:
|
|
operationId: steerRun
|
|
tags: [Human-in-the-Loop]
|
|
summary: Steer Run
|
|
description: Sends inline guidance to a running agent, targeting a specific file and line. The guidance is delivered asynchronously.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SteerRequest"
|
|
responses:
|
|
"202":
|
|
description: Steering accepted for processing
|
|
"404":
|
|
description: Run not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/runs/{id}/preview:
|
|
post:
|
|
operationId: generatePreviewUrl
|
|
tags: [Human-in-the-Loop]
|
|
summary: Preview URL
|
|
description: Generates a time-limited preview URL for a port exposed by the run's sandbox environment.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RunId"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PreviewUrlRequest"
|
|
responses:
|
|
"201":
|
|
description: Preview URL created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PreviewUrlResponse"
|
|
"404":
|
|
description: Run not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
# ── Workflows ─────────────────────────────────────────────────────────
|
|
|
|
/workflows:
|
|
get:
|
|
operationId: listWorkflows
|
|
tags: [Workflows]
|
|
summary: List Workflows
|
|
description: Returns a paginated list of workflow definitions available for execution.
|
|
parameters:
|
|
- $ref: "#/components/parameters/PageLimit"
|
|
- $ref: "#/components/parameters/PageOffset"
|
|
responses:
|
|
"200":
|
|
description: Paginated list of workflows
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PaginatedWorkflowList"
|
|
|
|
/workflows/{name}:
|
|
get:
|
|
operationId: retrieveWorkflow
|
|
tags: [Workflows]
|
|
summary: Retrieve Workflow
|
|
description: Returns the full detail of a workflow including its DOT graph, TOML config, and description.
|
|
parameters:
|
|
- $ref: "#/components/parameters/WorkflowName"
|
|
responses:
|
|
"200":
|
|
description: Workflow detail
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkflowDetail"
|
|
"404":
|
|
description: Workflow not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/workflows/{name}/runs:
|
|
get:
|
|
operationId: listWorkflowRuns
|
|
tags: [Workflows]
|
|
summary: List Workflow Runs
|
|
description: Returns a paginated list of runs filtered to a specific workflow.
|
|
parameters:
|
|
- $ref: "#/components/parameters/WorkflowName"
|
|
- $ref: "#/components/parameters/PageLimit"
|
|
- $ref: "#/components/parameters/PageOffset"
|
|
responses:
|
|
"200":
|
|
description: Paginated list of runs
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PaginatedRunList"
|
|
"404":
|
|
description: Workflow not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
post:
|
|
operationId: startWorkflowRun
|
|
tags: [Workflows]
|
|
summary: Start Workflow Run
|
|
description: Queues a new run of the specified workflow using its stored DOT graph.
|
|
parameters:
|
|
- $ref: "#/components/parameters/WorkflowName"
|
|
responses:
|
|
"201":
|
|
description: Run created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RunStatusResponse"
|
|
"404":
|
|
description: Workflow not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
# ── Verifications ─────────────────────────────────────────────────────
|
|
|
|
/verifications:
|
|
get:
|
|
operationId: listVerifications
|
|
tags: [Verifications]
|
|
summary: List Verifications
|
|
description: Returns all verification categories with their controls and performance metrics.
|
|
responses:
|
|
"200":
|
|
description: Array of verification categories
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PaginatedVerificationCategoryList"
|
|
|
|
/verifications/{slug}:
|
|
get:
|
|
operationId: retrieveVerification
|
|
tags: [Verifications]
|
|
summary: Retrieve Verification
|
|
description: Returns detailed information about a specific verification control, including performance data, recent results, and sibling controls in the same category.
|
|
parameters:
|
|
- $ref: "#/components/parameters/VerificationSlug"
|
|
responses:
|
|
"200":
|
|
description: Verification control detail
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/VerificationDetailResponse"
|
|
"404":
|
|
description: Control not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
# ── Retros ────────────────────────────────────────────────────────────
|
|
|
|
/retros:
|
|
get:
|
|
operationId: listRetros
|
|
tags: [Retros]
|
|
summary: List Retros
|
|
description: Returns a paginated list of run retrospectives ordered by recency, with smoothness ratings and summary statistics.
|
|
parameters:
|
|
- $ref: "#/components/parameters/PageLimit"
|
|
- $ref: "#/components/parameters/PageOffset"
|
|
responses:
|
|
"200":
|
|
description: Paginated list of retros
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PaginatedRetroList"
|
|
|
|
# ── Sessions ──────────────────────────────────────────────────────────
|
|
|
|
/sessions:
|
|
get:
|
|
operationId: listSessions
|
|
tags: [Sessions]
|
|
summary: List Sessions
|
|
description: Returns sessions ordered by recency (newest first).
|
|
parameters:
|
|
- $ref: "#/components/parameters/PageLimit"
|
|
- $ref: "#/components/parameters/PageOffset"
|
|
responses:
|
|
"200":
|
|
description: Paginated list of sessions
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PaginatedSessionList"
|
|
post:
|
|
operationId: createSession
|
|
tags: [Sessions]
|
|
summary: Create Session
|
|
description: Start a new interactive chat session. The initial user prompt is required; a model may optionally be specified.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CreateSessionRequest"
|
|
responses:
|
|
"201":
|
|
description: Session created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CreateSessionResponse"
|
|
|
|
/sessions/{id}:
|
|
get:
|
|
operationId: retrieveSession
|
|
tags: [Sessions]
|
|
summary: Retrieve Session
|
|
description: Returns the full session detail including all conversation turns.
|
|
parameters:
|
|
- $ref: "#/components/parameters/SessionId"
|
|
responses:
|
|
"200":
|
|
description: Session detail
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SessionDetail"
|
|
"404":
|
|
description: Session not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/sessions/{id}/messages:
|
|
post:
|
|
operationId: sendSessionMessage
|
|
tags: [Sessions]
|
|
summary: Send Session Message
|
|
description: Append a user message to an existing session. The server will process it and produce assistant and tool turns asynchronously via the event stream.
|
|
parameters:
|
|
- $ref: "#/components/parameters/SessionId"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SendMessageRequest"
|
|
responses:
|
|
"202":
|
|
description: Message accepted for processing
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SendMessageResponse"
|
|
"404":
|
|
description: Session not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/sessions/{id}/events:
|
|
get:
|
|
operationId: streamSessionEvents
|
|
tags: [Sessions]
|
|
summary: Stream Session Events
|
|
description: |
|
|
Opens a server-sent event (SSE) stream for real-time session updates.
|
|
|
|
Each SSE frame includes a sequential numeric `id:` field that supports
|
|
resumption via the `Last-Event-ID` request header.
|
|
|
|
The stream emits the following SSE event types:
|
|
|
|
- `event: assistant_turn` — data: `AssistantTurn` JSON object
|
|
- `event: tool_turn` — data: `ToolTurn` JSON object
|
|
- `event: done` — data: `{}` (stream complete)
|
|
- `event: error` — data: `{"message": "..."}` (error occurred)
|
|
|
|
Each SSE frame has an `id:` line (sequential integer), an `event:` line (the event type),
|
|
and a `data:` line (the JSON payload).
|
|
parameters:
|
|
- $ref: "#/components/parameters/SessionId"
|
|
- name: Last-Event-ID
|
|
in: header
|
|
required: false
|
|
description: >
|
|
SSE reconnection header. When provided, the server resumes the
|
|
stream after the event with this ID. IDs are 0-based sequential
|
|
integers assigned to each emitted SSE frame.
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Server-sent event stream
|
|
content:
|
|
text/event-stream:
|
|
schema:
|
|
type: string
|
|
"404":
|
|
description: Session not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
# ── Insights ──────────────────────────────────────────────────────────
|
|
|
|
/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"
|
|
|
|
/insights/queries/{id}:
|
|
put:
|
|
operationId: updateSavedQuery
|
|
tags: [Insights]
|
|
summary: Update Saved Query
|
|
description: Replaces the name and SQL of an existing saved query.
|
|
parameters:
|
|
- $ref: "#/components/parameters/InsightQueryId"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SaveQueryRequest"
|
|
responses:
|
|
"200":
|
|
description: Query updated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SavedQuery"
|
|
"404":
|
|
description: Query not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
delete:
|
|
operationId: deleteSavedQuery
|
|
tags: [Insights]
|
|
summary: Delete Saved Query
|
|
description: Permanently removes a saved query.
|
|
parameters:
|
|
- $ref: "#/components/parameters/InsightQueryId"
|
|
responses:
|
|
"204":
|
|
description: Query deleted
|
|
"404":
|
|
description: Query not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/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"
|
|
|
|
/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"
|
|
|
|
# ── Usage ────────────────────────────────────────────────────────────
|
|
|
|
/usage:
|
|
get:
|
|
operationId: getAggregateUsage
|
|
tags: [Usage]
|
|
summary: Aggregate Usage
|
|
description: Returns aggregate token/cost usage across all completed runs since server start.
|
|
responses:
|
|
"200":
|
|
description: Aggregate usage data
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AggregateUsage"
|
|
|
|
# ── Settings ──────────────────────────────────────────────────────────
|
|
|
|
/settings:
|
|
get:
|
|
operationId: retrieveServerSettings
|
|
tags: [Settings]
|
|
summary: Retrieve Server Settings
|
|
description: Returns all server settings organized into groups. Each group contains fields with their current values and input types.
|
|
responses:
|
|
"200":
|
|
description: Array of setting groups
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/SettingGroup"
|
|
|
|
# ── Projects ──────────────────────────────────────────────────────────
|
|
|
|
/projects:
|
|
get:
|
|
operationId: listProjects
|
|
tags: [Projects]
|
|
summary: List Projects
|
|
description: Returns a paginated list of registered projects (repositories).
|
|
parameters:
|
|
- $ref: "#/components/parameters/PageLimit"
|
|
- $ref: "#/components/parameters/PageOffset"
|
|
responses:
|
|
"200":
|
|
description: Paginated list of projects
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PaginatedProjectList"
|
|
|
|
/projects/{id}/branches:
|
|
get:
|
|
operationId: listBranches
|
|
tags: [Projects]
|
|
summary: List Branches
|
|
description: Returns a paginated list of branches for a specific project.
|
|
parameters:
|
|
- $ref: "#/components/parameters/ProjectId"
|
|
- $ref: "#/components/parameters/PageLimit"
|
|
- $ref: "#/components/parameters/PageOffset"
|
|
responses:
|
|
"200":
|
|
description: Paginated list of branches
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PaginatedBranchList"
|
|
"404":
|
|
description: Project not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
components:
|
|
securitySchemes:
|
|
BearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: >
|
|
Ed25519-signed JWT issued by arc-web. Required claims: iss ("arc-web"),
|
|
iat, exp. Optional sub claim (GitHub profile URL) identifies the user.
|
|
# OpenAPI 3.1 defines type: mutualTLS, but our parser (openapiv3) only
|
|
# supports 3.0 scheme types. We use apiKey as a placeholder; actual mTLS
|
|
# enforcement happens at the transport layer via client certificates.
|
|
mTLS:
|
|
type: apiKey
|
|
in: header
|
|
name: X-mTLS-Client-CN
|
|
description: >
|
|
Mutual TLS: client certificate signed by the configured CA. Identity
|
|
is extracted from the certificate's Common Name (CN). This scheme is
|
|
enforced at the transport layer, not via an HTTP header.
|
|
|
|
parameters:
|
|
RunId:
|
|
name: id
|
|
in: path
|
|
required: true
|
|
description: Unique run identifier (ULID).
|
|
schema:
|
|
type: string
|
|
example: 01JNQVR7M0EJ5GKAT2SC4ERS1Z
|
|
|
|
SessionId:
|
|
name: id
|
|
in: path
|
|
required: true
|
|
description: Unique session identifier.
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
|
|
|
|
StageId:
|
|
name: stageId
|
|
in: path
|
|
required: true
|
|
description: Identifier of a stage within a run's workflow graph.
|
|
schema:
|
|
type: string
|
|
example: propose-changes
|
|
|
|
QuestionId:
|
|
name: qid
|
|
in: path
|
|
required: true
|
|
description: Unique identifier of a pending question.
|
|
schema:
|
|
type: string
|
|
example: q-001
|
|
|
|
WorkflowName:
|
|
name: name
|
|
in: path
|
|
required: true
|
|
description: URL-safe slug identifying a workflow definition.
|
|
schema:
|
|
type: string
|
|
example: fix_build
|
|
|
|
VerificationSlug:
|
|
name: slug
|
|
in: path
|
|
required: true
|
|
description: URL-safe slug identifying a verification control.
|
|
schema:
|
|
type: string
|
|
example: motivation
|
|
|
|
InsightQueryId:
|
|
name: id
|
|
in: path
|
|
required: true
|
|
description: Unique identifier of a saved query.
|
|
schema:
|
|
type: string
|
|
example: "1"
|
|
|
|
ProjectId:
|
|
name: id
|
|
in: path
|
|
required: true
|
|
description: Unique identifier of a project (repository).
|
|
schema:
|
|
type: string
|
|
example: arc-web
|
|
|
|
CheckpointFilter:
|
|
name: checkpoint
|
|
in: query
|
|
required: false
|
|
description: Filter file diffs to a specific checkpoint. Defaults to all changes.
|
|
schema:
|
|
type: string
|
|
default: "all"
|
|
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
|
|
|
|
schemas:
|
|
# ── Pagination ───────────────────────────────────────────────────────
|
|
|
|
PaginationMeta:
|
|
description: Pagination metadata included in every paginated response.
|
|
type: object
|
|
required:
|
|
- has_more
|
|
properties:
|
|
has_more:
|
|
type: boolean
|
|
description: Whether additional pages of results are available.
|
|
example: true
|
|
|
|
PaginatedRunList:
|
|
description: Paginated list of runs.
|
|
type: object
|
|
required:
|
|
- data
|
|
- meta
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/RunListItem"
|
|
meta:
|
|
$ref: "#/components/schemas/PaginationMeta"
|
|
|
|
PaginatedWorkflowList:
|
|
description: Paginated list of workflows.
|
|
type: object
|
|
required:
|
|
- data
|
|
- meta
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/WorkflowListItem"
|
|
meta:
|
|
$ref: "#/components/schemas/PaginationMeta"
|
|
|
|
PaginatedRetroList:
|
|
description: Paginated list of run retrospectives.
|
|
type: object
|
|
required:
|
|
- data
|
|
- meta
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/RetroListItem"
|
|
meta:
|
|
$ref: "#/components/schemas/PaginationMeta"
|
|
|
|
PaginatedSessionList:
|
|
description: Paginated list of sessions.
|
|
type: object
|
|
required:
|
|
- data
|
|
- meta
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/SessionListItem"
|
|
meta:
|
|
$ref: "#/components/schemas/PaginationMeta"
|
|
|
|
PaginatedProjectList:
|
|
description: Paginated list of projects.
|
|
type: object
|
|
required:
|
|
- data
|
|
- meta
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Project"
|
|
meta:
|
|
$ref: "#/components/schemas/PaginationMeta"
|
|
|
|
PaginatedBranchList:
|
|
description: Paginated list of branches.
|
|
type: object
|
|
required:
|
|
- data
|
|
- meta
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Branch"
|
|
meta:
|
|
$ref: "#/components/schemas/PaginationMeta"
|
|
|
|
PaginatedSavedQueryList:
|
|
description: Paginated list of saved queries.
|
|
type: object
|
|
required:
|
|
- data
|
|
- meta
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/SavedQuery"
|
|
meta:
|
|
$ref: "#/components/schemas/PaginationMeta"
|
|
|
|
PaginatedHistoryEntryList:
|
|
description: Paginated list of query history entries.
|
|
type: object
|
|
required:
|
|
- data
|
|
- meta
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/HistoryEntry"
|
|
meta:
|
|
$ref: "#/components/schemas/PaginationMeta"
|
|
|
|
PaginatedStageTurnList:
|
|
description: Paginated list of stage turns.
|
|
type: object
|
|
required:
|
|
- data
|
|
- meta
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/StageTurn"
|
|
meta:
|
|
$ref: "#/components/schemas/PaginationMeta"
|
|
|
|
PaginatedApiQuestionList:
|
|
description: Paginated list of pending questions.
|
|
type: object
|
|
required:
|
|
- data
|
|
- meta
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/ApiQuestion"
|
|
meta:
|
|
$ref: "#/components/schemas/PaginationMeta"
|
|
|
|
PaginatedRunStageList:
|
|
description: Paginated list of run stages.
|
|
type: object
|
|
required:
|
|
- data
|
|
- meta
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/RunStage"
|
|
meta:
|
|
$ref: "#/components/schemas/PaginationMeta"
|
|
|
|
PaginatedRunVerificationList:
|
|
description: Paginated list of run verification categories.
|
|
type: object
|
|
required:
|
|
- data
|
|
- meta
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/RunVerification"
|
|
meta:
|
|
$ref: "#/components/schemas/PaginationMeta"
|
|
|
|
PaginatedVerificationCategoryList:
|
|
description: Paginated list of verification categories.
|
|
type: object
|
|
required:
|
|
- data
|
|
- meta
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/VerificationCategory"
|
|
meta:
|
|
$ref: "#/components/schemas/PaginationMeta"
|
|
|
|
# ── Run Schemas ──────────────────────────────────────────────────────
|
|
|
|
RunStatus:
|
|
description: Lifecycle status of a run.
|
|
type: string
|
|
enum:
|
|
- queued
|
|
- starting
|
|
- running
|
|
- completed
|
|
- failed
|
|
- cancelled
|
|
|
|
StartRunRequest:
|
|
description: Request body for starting a new run from a DOT graph source.
|
|
type: object
|
|
required:
|
|
- dot_source
|
|
properties:
|
|
dot_source:
|
|
type: string
|
|
description: DOT language source defining the workflow graph.
|
|
example: 'digraph { start [shape=Mdiamond]; exit [shape=Msquare]; start -> exit }'
|
|
|
|
RunStatusResponse:
|
|
description: Current status of a run with optional error and queue position.
|
|
type: object
|
|
required:
|
|
- id
|
|
- status
|
|
- created_at
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique run identifier (ULID).
|
|
example: 01JNQVR7M0EJ5GKAT2SC4ERS1Z
|
|
status:
|
|
$ref: "#/components/schemas/RunStatus"
|
|
error:
|
|
$ref: "#/components/schemas/RunError"
|
|
queue_position:
|
|
type: integer
|
|
description: Position in the queue (1-based). Only present when status is `queued`.
|
|
example: 3
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp when the run was created.
|
|
example: "2026-03-06T14:30:00Z"
|
|
|
|
ApiQuestionOption:
|
|
description: A selectable option for a multiple-choice or multi-select question.
|
|
type: object
|
|
required:
|
|
- key
|
|
- label
|
|
properties:
|
|
key:
|
|
type: string
|
|
description: Machine-readable option key used when submitting an answer.
|
|
example: option_a
|
|
label:
|
|
type: string
|
|
description: Human-readable label displayed to the user.
|
|
example: Accept changes
|
|
|
|
ApiQuestion:
|
|
description: A pending human-in-the-loop question generated by a workflow stage.
|
|
type: object
|
|
required:
|
|
- id
|
|
- text
|
|
- 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?
|
|
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
|
|
|
|
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.
|
|
type: object
|
|
properties:
|
|
value:
|
|
type: string
|
|
description: Freeform answer text.
|
|
example: "Yes, proceed with the changes."
|
|
selected_option_key:
|
|
type: string
|
|
description: Key of the selected option (for multiple-choice questions).
|
|
example: option_a
|
|
|
|
ErrorResponseEntry:
|
|
description: A single error entry in an error response.
|
|
type: object
|
|
required:
|
|
- status
|
|
- title
|
|
- detail
|
|
properties:
|
|
status:
|
|
type: string
|
|
description: HTTP status code as a string.
|
|
example: "404"
|
|
title:
|
|
type: string
|
|
description: Short error classification.
|
|
example: Not Found
|
|
detail:
|
|
type: string
|
|
description: Human-readable error description.
|
|
example: Run not found.
|
|
|
|
ErrorResponse:
|
|
description: Standard error response containing one or more error entries.
|
|
type: object
|
|
required:
|
|
- errors
|
|
properties:
|
|
errors:
|
|
type: array
|
|
description: List of error entries.
|
|
items:
|
|
$ref: "#/components/schemas/ErrorResponseEntry"
|
|
|
|
# ── Run Board Schemas ────────────────────────────────────────────────
|
|
|
|
BoardColumn:
|
|
description: Board column status for a run in the list view.
|
|
type: string
|
|
enum:
|
|
- working
|
|
- pending
|
|
- review
|
|
- merge
|
|
|
|
CheckRunStatus:
|
|
description: Status of a CI check run.
|
|
type: string
|
|
enum:
|
|
- success
|
|
- failure
|
|
- skipped
|
|
- pending
|
|
- queued
|
|
|
|
CheckRun:
|
|
description: A CI check run result associated with a run's pull request.
|
|
type: object
|
|
required:
|
|
- name
|
|
- status
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Name of the CI check.
|
|
example: unit-tests
|
|
status:
|
|
$ref: "#/components/schemas/CheckRunStatus"
|
|
duration_secs:
|
|
type: number
|
|
description: Duration of the check run in seconds.
|
|
example: 154.0
|
|
|
|
# ── Reusable Sub-Schemas ───────────────────────────────────────────
|
|
|
|
ModelReference:
|
|
description: Reference to a model by its identifier.
|
|
type: object
|
|
required:
|
|
- id
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Model identifier.
|
|
example: claude-opus-4-6
|
|
|
|
WorkflowReference:
|
|
description: Reference to a workflow by its slug.
|
|
type: object
|
|
required:
|
|
- slug
|
|
properties:
|
|
slug:
|
|
type: string
|
|
description: URL-safe workflow slug.
|
|
example: implement
|
|
|
|
RunReference:
|
|
description: Reference to a run with its title.
|
|
type: object
|
|
required:
|
|
- id
|
|
- title
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique run identifier.
|
|
example: run-047
|
|
title:
|
|
type: string
|
|
description: Human-readable run title.
|
|
example: "PR #312 — Add OAuth2 PKCE flow"
|
|
|
|
RepositoryReference:
|
|
description: Reference to a repository by name.
|
|
type: object
|
|
required:
|
|
- name
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Repository name.
|
|
example: api-server
|
|
|
|
CategoryReference:
|
|
description: Reference to a verification category by name.
|
|
type: object
|
|
required:
|
|
- name
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Category name.
|
|
example: Traceability
|
|
|
|
TokenUsage:
|
|
description: Token and cost usage totals.
|
|
type: object
|
|
required:
|
|
- input_tokens
|
|
- output_tokens
|
|
- cost
|
|
properties:
|
|
input_tokens:
|
|
type: integer
|
|
description: Number of input tokens consumed.
|
|
example: 28640
|
|
output_tokens:
|
|
type: integer
|
|
description: Number of output tokens generated.
|
|
example: 8750
|
|
cost:
|
|
type: number
|
|
description: Cost in USD.
|
|
example: 0.72
|
|
|
|
CodeLocation:
|
|
description: A file and line location in the codebase.
|
|
type: object
|
|
properties:
|
|
file:
|
|
type: string
|
|
description: File path.
|
|
example: src/middleware/rate-limit.ts
|
|
line:
|
|
type: integer
|
|
description: Line number in the file.
|
|
example: 42
|
|
|
|
RunError:
|
|
description: Error information for a failed run.
|
|
type: object
|
|
required:
|
|
- message
|
|
properties:
|
|
message:
|
|
type: string
|
|
description: Error message.
|
|
example: "Stage 'apply-changes' exceeded maximum retries."
|
|
|
|
RunPullRequest:
|
|
description: Pull request information for a run.
|
|
type: object
|
|
required:
|
|
- number
|
|
properties:
|
|
number:
|
|
type: integer
|
|
description: Pull request number.
|
|
example: 889
|
|
additions:
|
|
type: integer
|
|
description: Lines added.
|
|
example: 234
|
|
deletions:
|
|
type: integer
|
|
description: Lines deleted.
|
|
example: 67
|
|
comments:
|
|
type: integer
|
|
description: Number of review comments.
|
|
example: 4
|
|
checks:
|
|
type: array
|
|
description: CI check run results.
|
|
items:
|
|
$ref: "#/components/schemas/CheckRun"
|
|
|
|
RunTimings:
|
|
description: Timing information for a run.
|
|
type: object
|
|
required:
|
|
- elapsed_secs
|
|
properties:
|
|
elapsed_secs:
|
|
type: number
|
|
description: Wall-clock time elapsed in seconds.
|
|
example: 420.0
|
|
elapsed_warning:
|
|
type: boolean
|
|
description: Whether the elapsed time exceeds the expected threshold.
|
|
example: false
|
|
|
|
SandboxResources:
|
|
description: Compute resources allocated to a sandbox.
|
|
type: object
|
|
required:
|
|
- cpu
|
|
- memory
|
|
properties:
|
|
cpu:
|
|
type: integer
|
|
description: Number of CPU cores.
|
|
example: 4
|
|
memory:
|
|
type: integer
|
|
description: Memory in GB.
|
|
example: 8
|
|
|
|
RunSandbox:
|
|
description: Sandbox environment for a run.
|
|
type: object
|
|
required:
|
|
- id
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Sandbox identifier.
|
|
example: sb-a1b2c3d4
|
|
resources:
|
|
$ref: "#/components/schemas/SandboxResources"
|
|
|
|
RunQuestion:
|
|
description: A pending human-in-the-loop question summary.
|
|
type: object
|
|
required:
|
|
- text
|
|
properties:
|
|
text:
|
|
type: string
|
|
description: Question text.
|
|
example: Accept or push for another round?
|
|
|
|
AggregateUsageTotals:
|
|
description: Aggregate usage totals across all runs.
|
|
type: object
|
|
required:
|
|
- runs
|
|
- input_tokens
|
|
- output_tokens
|
|
- cost
|
|
- 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
|
|
cost:
|
|
type: number
|
|
description: Total cost in USD.
|
|
example: 20.34
|
|
runtime_secs:
|
|
type: number
|
|
description: Total runtime in seconds.
|
|
example: 3501.0
|
|
|
|
WorkflowSchedule:
|
|
description: Schedule configuration for a workflow.
|
|
type: object
|
|
required:
|
|
- expression
|
|
properties:
|
|
expression:
|
|
type: string
|
|
description: Cron-like schedule expression.
|
|
example: "0 */6 * * *"
|
|
next_run:
|
|
type: string
|
|
format: date-time
|
|
description: ISO 8601 timestamp of the next scheduled run.
|
|
example: "2025-09-15T18:00:00Z"
|
|
|
|
WorkflowLastRun:
|
|
description: Information about a workflow's most recent run.
|
|
type: object
|
|
required:
|
|
- ran_at
|
|
properties:
|
|
ran_at:
|
|
type: string
|
|
format: date-time
|
|
description: ISO 8601 timestamp of the most recent run.
|
|
example: "2025-09-15T12:00:00Z"
|
|
|
|
UsageStageRef:
|
|
description: Reference to a usage stage.
|
|
type: object
|
|
required:
|
|
- id
|
|
- name
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Stage identifier (slug).
|
|
example: propose-changes
|
|
name:
|
|
type: string
|
|
description: Human-readable stage name.
|
|
example: Propose Changes
|
|
|
|
# ── Run Board Schemas (updated) ─────────────────────────────────────
|
|
|
|
RunListItem:
|
|
description: Summary of a run shown in the board view.
|
|
type: object
|
|
required:
|
|
- id
|
|
- repository
|
|
- title
|
|
- workflow
|
|
- status
|
|
- created_at
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique run identifier (ULID).
|
|
example: 01JNQVR7M0EJ5GKAT2SC4ERS1Z
|
|
repository:
|
|
$ref: "#/components/schemas/RepositoryReference"
|
|
title:
|
|
type: string
|
|
description: Human-readable title describing the run's goal.
|
|
example: Add rate limiting to auth endpoints
|
|
workflow:
|
|
$ref: "#/components/schemas/WorkflowReference"
|
|
status:
|
|
$ref: "#/components/schemas/BoardColumn"
|
|
pull_request:
|
|
$ref: "#/components/schemas/RunPullRequest"
|
|
timings:
|
|
$ref: "#/components/schemas/RunTimings"
|
|
sandbox:
|
|
$ref: "#/components/schemas/RunSandbox"
|
|
question:
|
|
$ref: "#/components/schemas/RunQuestion"
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp when the run was created.
|
|
example: "2026-03-06T14:30:00Z"
|
|
|
|
# ── Stage / Turn Schemas ─────────────────────────────────────────────
|
|
|
|
StageStatus:
|
|
description: Execution status of a workflow stage.
|
|
type: string
|
|
enum:
|
|
- completed
|
|
- running
|
|
- pending
|
|
- failed
|
|
|
|
RunStage:
|
|
description: A single stage in a run's workflow graph.
|
|
type: object
|
|
required:
|
|
- id
|
|
- name
|
|
- status
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique stage identifier within the run.
|
|
example: propose-changes
|
|
name:
|
|
type: string
|
|
description: Human-readable stage name.
|
|
example: Propose Changes
|
|
status:
|
|
$ref: "#/components/schemas/StageStatus"
|
|
duration_secs:
|
|
type: number
|
|
description: Time spent in this stage, in seconds.
|
|
example: 154.0
|
|
dot_id:
|
|
type: string
|
|
description: Node identifier in the DOT graph source.
|
|
example: propose
|
|
|
|
ToolUse:
|
|
description: A single tool invocation with its input, result, and execution metadata.
|
|
type: object
|
|
required:
|
|
- id
|
|
- tool_name
|
|
- input
|
|
- result
|
|
- is_error
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique identifier for this tool invocation. Enables correlation in parallel tool use.
|
|
example: toolu_01A09q90qw90lq917835lq9
|
|
tool_name:
|
|
type: string
|
|
description: Name of the tool that was invoked.
|
|
example: read_file
|
|
input:
|
|
type: string
|
|
description: JSON-encoded input passed to the tool.
|
|
example: '{ "path": "src/routes/auth.ts" }'
|
|
result:
|
|
type: string
|
|
description: Output returned by the tool. Contains the error message when is_error is true.
|
|
example: 'import { Router } from "express";'
|
|
is_error:
|
|
type: boolean
|
|
description: Whether the tool invocation failed. When true, the result field contains the error message.
|
|
example: false
|
|
duration_ms:
|
|
type: integer
|
|
description: Wall-clock execution time of the tool invocation in milliseconds.
|
|
example: 142
|
|
|
|
StageTurn:
|
|
description: A single turn in a stage conversation — a system prompt, assistant response, or tool invocation block.
|
|
discriminator:
|
|
propertyName: kind
|
|
mapping:
|
|
system: "#/components/schemas/SystemStageTurn"
|
|
assistant: "#/components/schemas/AssistantStageTurn"
|
|
tool: "#/components/schemas/ToolStageTurn"
|
|
oneOf:
|
|
- $ref: "#/components/schemas/SystemStageTurn"
|
|
- $ref: "#/components/schemas/AssistantStageTurn"
|
|
- $ref: "#/components/schemas/ToolStageTurn"
|
|
|
|
SystemStageTurn:
|
|
description: A system prompt turn that sets the stage's instructions.
|
|
type: object
|
|
required:
|
|
- kind
|
|
- content
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum: [system]
|
|
content:
|
|
type: string
|
|
description: System prompt text.
|
|
example: You are a drift detection agent. Compare the production and staging environments.
|
|
tools:
|
|
type: array
|
|
description: Tool invocations (always empty for system turns).
|
|
items:
|
|
$ref: "#/components/schemas/ToolUse"
|
|
|
|
AssistantStageTurn:
|
|
description: An assistant response turn within a stage.
|
|
type: object
|
|
required:
|
|
- kind
|
|
- content
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum: [assistant]
|
|
content:
|
|
type: string
|
|
description: Assistant response text.
|
|
example: I'll start by loading the environment configurations for both production and staging.
|
|
tools:
|
|
type: array
|
|
description: Tool invocations (always empty for assistant turns).
|
|
items:
|
|
$ref: "#/components/schemas/ToolUse"
|
|
|
|
ToolStageTurn:
|
|
description: A tool invocation turn containing one or more tool calls.
|
|
type: object
|
|
required:
|
|
- kind
|
|
- tools
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum: [tool]
|
|
content:
|
|
type: string
|
|
description: Optional text content (usually null for tool turns).
|
|
tools:
|
|
type: array
|
|
description: Tool invocations executed in this turn.
|
|
items:
|
|
$ref: "#/components/schemas/ToolUse"
|
|
|
|
# ── Compare / Diff Schemas ───────────────────────────────────────────
|
|
|
|
FileCheckpoint:
|
|
description: A named checkpoint within a run, used to filter file diffs.
|
|
type: object
|
|
required:
|
|
- id
|
|
- label
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Checkpoint identifier.
|
|
example: cp-3
|
|
label:
|
|
type: string
|
|
description: Human-readable label for the checkpoint.
|
|
example: "Checkpoint 3 — Review Changes"
|
|
|
|
DiffFile:
|
|
description: A file's contents at one side of a diff.
|
|
type: object
|
|
required:
|
|
- name
|
|
- contents
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: File path relative to the repository root.
|
|
example: src/commands/run.ts
|
|
contents:
|
|
type: string
|
|
description: Full file contents. Empty string for newly created or deleted files.
|
|
example: 'import { parseArgs } from "node:util";'
|
|
|
|
FileDiff:
|
|
description: A before/after pair showing changes to a single file.
|
|
type: object
|
|
required:
|
|
- old_file
|
|
- new_file
|
|
properties:
|
|
old_file:
|
|
$ref: "#/components/schemas/DiffFile"
|
|
new_file:
|
|
$ref: "#/components/schemas/DiffFile"
|
|
|
|
DiffStats:
|
|
description: Aggregate line-change statistics for a diff.
|
|
type: object
|
|
required:
|
|
- additions
|
|
- deletions
|
|
properties:
|
|
additions:
|
|
type: integer
|
|
description: Total lines added.
|
|
example: 567
|
|
deletions:
|
|
type: integer
|
|
description: Total lines deleted.
|
|
example: 234
|
|
|
|
RunCompare:
|
|
description: File-level diff output for a run, with checkpoint filtering support.
|
|
type: object
|
|
required:
|
|
- checkpoints
|
|
- files
|
|
- stats
|
|
properties:
|
|
checkpoints:
|
|
type: array
|
|
description: Available checkpoints for filtering.
|
|
items:
|
|
$ref: "#/components/schemas/FileCheckpoint"
|
|
files:
|
|
type: array
|
|
description: File diffs, optionally filtered by checkpoint.
|
|
items:
|
|
$ref: "#/components/schemas/FileDiff"
|
|
stats:
|
|
$ref: "#/components/schemas/DiffStats"
|
|
|
|
# ── Usage Schemas ────────────────────────────────────────────────────
|
|
|
|
UsageStage:
|
|
description: Token and cost usage for a single stage within a run.
|
|
type: object
|
|
required:
|
|
- stage
|
|
- model
|
|
- usage
|
|
- runtime_secs
|
|
properties:
|
|
stage:
|
|
$ref: "#/components/schemas/UsageStageRef"
|
|
model:
|
|
$ref: "#/components/schemas/ModelReference"
|
|
usage:
|
|
$ref: "#/components/schemas/TokenUsage"
|
|
runtime_secs:
|
|
type: number
|
|
description: Wall-clock runtime in seconds.
|
|
example: 154.0
|
|
|
|
UsageTotals:
|
|
description: Aggregate usage totals across all stages of a run.
|
|
type: object
|
|
required:
|
|
- runtime_secs
|
|
- input_tokens
|
|
- output_tokens
|
|
- cost
|
|
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
|
|
cost:
|
|
type: number
|
|
description: Total cost in USD.
|
|
example: 2.26
|
|
|
|
UsageByModel:
|
|
description: Usage statistics grouped by model.
|
|
type: object
|
|
required:
|
|
- model
|
|
- stages
|
|
- usage
|
|
properties:
|
|
model:
|
|
$ref: "#/components/schemas/ModelReference"
|
|
stages:
|
|
type: integer
|
|
description: Number of stages that used this model.
|
|
example: 2
|
|
usage:
|
|
$ref: "#/components/schemas/TokenUsage"
|
|
|
|
RunUsage:
|
|
description: Complete usage breakdown for a single run.
|
|
type: object
|
|
required:
|
|
- stages
|
|
- totals
|
|
- by_model
|
|
properties:
|
|
stages:
|
|
type: array
|
|
description: Per-stage usage breakdown.
|
|
items:
|
|
$ref: "#/components/schemas/UsageStage"
|
|
totals:
|
|
$ref: "#/components/schemas/UsageTotals"
|
|
by_model:
|
|
type: array
|
|
description: Usage grouped by model.
|
|
items:
|
|
$ref: "#/components/schemas/UsageByModel"
|
|
|
|
AggregateUsage:
|
|
description: Aggregate token and cost usage across all runs since server start.
|
|
type: object
|
|
required:
|
|
- totals
|
|
- by_model
|
|
properties:
|
|
totals:
|
|
$ref: "#/components/schemas/AggregateUsageTotals"
|
|
by_model:
|
|
type: array
|
|
description: Usage grouped by model.
|
|
items:
|
|
$ref: "#/components/schemas/UsageByModel"
|
|
|
|
# ── Verification Schemas ─────────────────────────────────────────────
|
|
|
|
VerificationStatus:
|
|
description: Result status of a verification control evaluation.
|
|
type: string
|
|
enum:
|
|
- pass
|
|
- fail
|
|
- na
|
|
|
|
VerificationType:
|
|
description: The evaluation method used by a verification control.
|
|
type: string
|
|
enum:
|
|
- ai
|
|
- automated
|
|
- analysis
|
|
- ai-analysis
|
|
|
|
RunVerificationControl:
|
|
description: A verification control result within a run.
|
|
type: object
|
|
required:
|
|
- name
|
|
- description
|
|
- status
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Human-readable control name.
|
|
example: Motivation
|
|
description:
|
|
type: string
|
|
description: Short description of what the control verifies.
|
|
example: Origin of proposal identified
|
|
type:
|
|
$ref: "#/components/schemas/VerificationType"
|
|
status:
|
|
$ref: "#/components/schemas/VerificationStatus"
|
|
|
|
RunVerification:
|
|
description: Verification results for a category within a run.
|
|
type: object
|
|
required:
|
|
- name
|
|
- question
|
|
- status
|
|
- controls
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Category name.
|
|
example: Traceability
|
|
question:
|
|
type: string
|
|
description: The guiding question for this verification category.
|
|
example: Do we understand what this change is and why we're making it?
|
|
status:
|
|
$ref: "#/components/schemas/VerificationStatus"
|
|
controls:
|
|
type: array
|
|
description: Individual control results within this category.
|
|
items:
|
|
$ref: "#/components/schemas/RunVerificationControl"
|
|
|
|
SteerRequest:
|
|
description: Request body for sending inline steering guidance to a running agent.
|
|
type: object
|
|
required:
|
|
- guidance
|
|
properties:
|
|
location:
|
|
$ref: "#/components/schemas/CodeLocation"
|
|
guidance:
|
|
type: string
|
|
description: Guidance text for the agent.
|
|
example: Use a sliding window algorithm instead of fixed window.
|
|
|
|
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.
|
|
example: 3600
|
|
|
|
PreviewUrlResponse:
|
|
description: Response containing the generated preview URL.
|
|
type: object
|
|
required:
|
|
- url
|
|
properties:
|
|
url:
|
|
type: string
|
|
description: Time-limited preview URL.
|
|
example: "https://preview.example.com/sb-a1b2c3d4/3000"
|
|
|
|
# ── Workflow Schemas ─────────────────────────────────────────────────
|
|
|
|
WorkflowListItem:
|
|
description: Summary of a workflow shown in list views.
|
|
type: object
|
|
required:
|
|
- name
|
|
- slug
|
|
- filename
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Human-readable workflow name.
|
|
example: Fix Build
|
|
slug:
|
|
type: string
|
|
description: URL-safe slug used in API paths.
|
|
example: fix_build
|
|
filename:
|
|
type: string
|
|
description: DOT graph filename.
|
|
example: fix_build.dot
|
|
last_run:
|
|
$ref: "#/components/schemas/WorkflowLastRun"
|
|
schedule:
|
|
$ref: "#/components/schemas/WorkflowSchedule"
|
|
|
|
WorkflowDetail:
|
|
description: Full detail of a workflow definition including graph and configuration.
|
|
type: object
|
|
required:
|
|
- title
|
|
- slug
|
|
- filename
|
|
- description
|
|
- config
|
|
- graph
|
|
properties:
|
|
title:
|
|
type: string
|
|
description: Human-readable workflow title.
|
|
example: Fix Build
|
|
slug:
|
|
type: string
|
|
description: URL-safe slug used in API paths.
|
|
example: fix_build
|
|
filename:
|
|
type: string
|
|
description: DOT graph filename.
|
|
example: fix_build.dot
|
|
description:
|
|
type: string
|
|
description: Prose description of what the workflow does.
|
|
example: Automatically diagnoses and fixes CI build failures.
|
|
config:
|
|
type: string
|
|
description: TOML configuration content for the workflow.
|
|
example: "version = 1\ngoal = \"Fix CI build failures\""
|
|
graph:
|
|
type: string
|
|
description: DOT language source defining the workflow graph.
|
|
example: "digraph fix_build { rankdir=LR; start -> diagnose -> fix -> validate }"
|
|
|
|
# ── Verification Detail Schemas ──────────────────────────────────────
|
|
|
|
EvaluationResult:
|
|
description: Outcome of a single verification evaluation.
|
|
type: string
|
|
enum:
|
|
- pass
|
|
- fail
|
|
- skip
|
|
|
|
VerificationMode:
|
|
description: Operational mode of a verification control.
|
|
type: string
|
|
enum:
|
|
- active
|
|
- evaluate
|
|
- disabled
|
|
|
|
VerificationControl:
|
|
description: A verification control within a category, with performance metrics.
|
|
type: object
|
|
required:
|
|
- name
|
|
- slug
|
|
- description
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Human-readable control name.
|
|
example: Motivation
|
|
slug:
|
|
type: string
|
|
description: URL-safe slug for API lookups.
|
|
example: motivation
|
|
description:
|
|
type: string
|
|
description: Short description of what the control verifies.
|
|
example: Origin of proposal identified
|
|
type:
|
|
$ref: "#/components/schemas/VerificationType"
|
|
mode:
|
|
$ref: "#/components/schemas/VerificationMode"
|
|
f1:
|
|
type: number
|
|
description: F1 score of the control's AI evaluator.
|
|
example: 0.87
|
|
pass_at_1:
|
|
type: number
|
|
description: Pass@1 rate — probability of passing on the first evaluation.
|
|
example: 0.82
|
|
evaluations:
|
|
type: array
|
|
description: Recent evaluation results (newest first).
|
|
items:
|
|
$ref: "#/components/schemas/EvaluationResult"
|
|
|
|
VerificationCategory:
|
|
description: A group of related verification controls.
|
|
type: object
|
|
required:
|
|
- name
|
|
- question
|
|
- controls
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Category name.
|
|
example: Traceability
|
|
question:
|
|
type: string
|
|
description: Guiding question for the category.
|
|
example: Do we understand what this change is and why we're making it?
|
|
controls:
|
|
type: array
|
|
description: Verification controls in this category.
|
|
items:
|
|
$ref: "#/components/schemas/VerificationControl"
|
|
|
|
ControlInfo:
|
|
description: Core metadata about a verification control.
|
|
type: object
|
|
required:
|
|
- name
|
|
- slug
|
|
- description
|
|
- category
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Human-readable control name.
|
|
example: Motivation
|
|
slug:
|
|
type: string
|
|
description: URL-safe slug.
|
|
example: motivation
|
|
description:
|
|
type: string
|
|
description: Short description of what the control verifies.
|
|
example: Origin of proposal identified
|
|
type:
|
|
$ref: "#/components/schemas/VerificationType"
|
|
category:
|
|
$ref: "#/components/schemas/CategoryReference"
|
|
|
|
ControlPerformance:
|
|
description: Performance metrics for a verification control.
|
|
type: object
|
|
required:
|
|
- mode
|
|
- evaluations
|
|
properties:
|
|
mode:
|
|
$ref: "#/components/schemas/VerificationMode"
|
|
f1:
|
|
type: number
|
|
description: F1 score of the control's AI evaluator.
|
|
example: 0.87
|
|
pass_at_1:
|
|
type: number
|
|
description: Pass@1 rate.
|
|
example: 0.82
|
|
evaluations:
|
|
type: array
|
|
description: Recent evaluation results (newest first).
|
|
items:
|
|
$ref: "#/components/schemas/EvaluationResult"
|
|
|
|
ControlDetail:
|
|
description: Detailed information about a verification control including checks and examples.
|
|
type: object
|
|
required:
|
|
- description
|
|
- checks
|
|
- pass_example
|
|
- fail_example
|
|
properties:
|
|
description:
|
|
type: string
|
|
description: Detailed prose description of the control's purpose and rationale.
|
|
example: Verifies that every change traces back to a clear origin.
|
|
checks:
|
|
type: array
|
|
description: Specific checks performed by this control.
|
|
items:
|
|
type: string
|
|
example: ["PR body explains why the change is needed", "Commit messages reference a ticket"]
|
|
pass_example:
|
|
type: string
|
|
description: Example scenario where the control passes.
|
|
example: PR links to JIRA-1234 and explains the user-facing pain point.
|
|
fail_example:
|
|
type: string
|
|
description: Example scenario where the control fails.
|
|
example: PR description is empty or says only 'fix stuff'.
|
|
|
|
RecentControlResult:
|
|
description: Result of a recent verification control evaluation for a specific run.
|
|
type: object
|
|
required:
|
|
- run
|
|
- workflow
|
|
- result
|
|
- timestamp
|
|
properties:
|
|
run:
|
|
$ref: "#/components/schemas/RunReference"
|
|
workflow:
|
|
$ref: "#/components/schemas/WorkflowReference"
|
|
result:
|
|
$ref: "#/components/schemas/VerificationStatus"
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
description: ISO 8601 timestamp of the evaluation.
|
|
example: "2025-09-15T12:00:00Z"
|
|
|
|
SiblingControl:
|
|
description: Summary of a sibling verification control in the same category.
|
|
type: object
|
|
required:
|
|
- name
|
|
- slug
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Human-readable control name.
|
|
example: Specifications
|
|
slug:
|
|
type: string
|
|
description: URL-safe slug.
|
|
example: specifications
|
|
type:
|
|
$ref: "#/components/schemas/VerificationType"
|
|
mode:
|
|
$ref: "#/components/schemas/VerificationMode"
|
|
|
|
VerificationDetailResponse:
|
|
description: Complete detail view of a verification control with performance, examples, and recent results.
|
|
type: object
|
|
required:
|
|
- control
|
|
- performance
|
|
- control_detail
|
|
- recent_results
|
|
- siblings
|
|
properties:
|
|
control:
|
|
$ref: "#/components/schemas/ControlInfo"
|
|
performance:
|
|
$ref: "#/components/schemas/ControlPerformance"
|
|
control_detail:
|
|
$ref: "#/components/schemas/ControlDetail"
|
|
recent_results:
|
|
type: array
|
|
description: Recent evaluation results across runs.
|
|
items:
|
|
$ref: "#/components/schemas/RecentControlResult"
|
|
siblings:
|
|
type: array
|
|
description: Other controls in the same category.
|
|
items:
|
|
$ref: "#/components/schemas/SiblingControl"
|
|
|
|
# ── Retro Schemas ────────────────────────────────────────────────────
|
|
|
|
SmoothnessRating:
|
|
description: Qualitative assessment of how smoothly a run executed.
|
|
type: string
|
|
enum:
|
|
- effortless
|
|
- smooth
|
|
- bumpy
|
|
- struggled
|
|
- failed
|
|
|
|
RetroStats:
|
|
description: Summary statistics for a run retrospective.
|
|
type: object
|
|
required:
|
|
- total_duration_ms
|
|
- total_retries
|
|
- files_touched
|
|
- stages_completed
|
|
- stages_failed
|
|
properties:
|
|
total_duration_ms:
|
|
type: integer
|
|
description: Total run duration in milliseconds.
|
|
example: 389000
|
|
total_cost:
|
|
type: number
|
|
description: Total cost in USD.
|
|
example: 2.78
|
|
total_retries:
|
|
type: integer
|
|
description: Total number of retries across all stages.
|
|
example: 0
|
|
files_touched:
|
|
type: array
|
|
description: List of files modified during the run.
|
|
items:
|
|
type: string
|
|
example: ["src/middleware/rate-limit.ts", "src/routes/auth.ts"]
|
|
stages_completed:
|
|
type: integer
|
|
description: Number of stages that completed successfully.
|
|
example: 4
|
|
stages_failed:
|
|
type: integer
|
|
description: Number of stages that failed.
|
|
example: 0
|
|
|
|
RetroListItem:
|
|
description: Summary of a run retrospective shown in list views.
|
|
type: object
|
|
required:
|
|
- run
|
|
- workflow
|
|
- timestamp
|
|
- stats
|
|
- friction_point_count
|
|
properties:
|
|
run:
|
|
$ref: "#/components/schemas/RunReference"
|
|
workflow:
|
|
$ref: "#/components/schemas/WorkflowReference"
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp when the retro was generated.
|
|
example: "2026-02-28T14:32:00Z"
|
|
smoothness:
|
|
$ref: "#/components/schemas/SmoothnessRating"
|
|
stats:
|
|
$ref: "#/components/schemas/RetroStats"
|
|
friction_point_count:
|
|
type: integer
|
|
description: Number of friction points identified in the retro.
|
|
example: 0
|
|
|
|
# ── Session Schemas ──────────────────────────────────────────────────
|
|
|
|
SessionListItem:
|
|
description: Summary of a session shown in list views.
|
|
type: object
|
|
required:
|
|
- id
|
|
- title
|
|
- model
|
|
- last_message_preview
|
|
- created_at
|
|
- updated_at
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
description: Unique session identifier.
|
|
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
|
|
title:
|
|
type: string
|
|
description: Short title summarizing the session topic.
|
|
example: Add rate limiting to auth endpoints
|
|
model:
|
|
$ref: "#/components/schemas/ModelReference"
|
|
last_message_preview:
|
|
type: string
|
|
description: Truncated snippet of the most recent turn's content.
|
|
example: "Done. I've created the rate limiter and wired it up..."
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp when the session was created.
|
|
example: "2026-03-06T14:30:00Z"
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp when the session was last updated (e.g. new turn added).
|
|
example: "2026-03-06T15:45:00Z"
|
|
|
|
|
|
SessionTurn:
|
|
description: A single turn in a session conversation — a user message, assistant response, or tool invocation block.
|
|
discriminator:
|
|
propertyName: kind
|
|
mapping:
|
|
user: "#/components/schemas/UserTurn"
|
|
assistant: "#/components/schemas/AssistantTurn"
|
|
tool: "#/components/schemas/ToolTurn"
|
|
oneOf:
|
|
- $ref: "#/components/schemas/UserTurn"
|
|
- $ref: "#/components/schemas/AssistantTurn"
|
|
- $ref: "#/components/schemas/ToolTurn"
|
|
|
|
UserTurn:
|
|
description: A user message turn.
|
|
type: object
|
|
required:
|
|
- kind
|
|
- content
|
|
- created_at
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum: [user]
|
|
content:
|
|
type: string
|
|
description: Text content of the user message.
|
|
example: Add rate limiting to the auth endpoints using a sliding window approach with Redis.
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp when the turn was created.
|
|
example: "2026-02-28T10:00:00Z"
|
|
|
|
AssistantTurn:
|
|
description: An assistant response turn.
|
|
type: object
|
|
required:
|
|
- kind
|
|
- content
|
|
- created_at
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum: [assistant]
|
|
content:
|
|
type: string
|
|
description: Text content of the assistant response.
|
|
example: I'll implement sliding window rate limiting using Redis.
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp when the turn was created.
|
|
example: "2026-02-28T10:01:00Z"
|
|
|
|
ToolTurn:
|
|
description: A tool invocation turn.
|
|
type: object
|
|
required:
|
|
- kind
|
|
- tools
|
|
- created_at
|
|
properties:
|
|
kind:
|
|
type: string
|
|
enum: [tool]
|
|
tools:
|
|
type: array
|
|
description: Tool invocations for this turn.
|
|
items:
|
|
$ref: "#/components/schemas/ToolUse"
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp when the turn was created.
|
|
example: "2026-02-28T10:01:05Z"
|
|
|
|
SessionDetail:
|
|
description: Full session record including metadata and the complete conversation history.
|
|
type: object
|
|
required:
|
|
- id
|
|
- title
|
|
- model
|
|
- created_at
|
|
- updated_at
|
|
- turns
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
description: Unique session identifier.
|
|
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
|
|
title:
|
|
type: string
|
|
description: Short title summarizing the session topic.
|
|
example: Add rate limiting to auth endpoints
|
|
model:
|
|
$ref: "#/components/schemas/ModelReference"
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp when the session was created.
|
|
example: "2026-03-06T14:30:00Z"
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp when the session was last updated (e.g. new turn added).
|
|
example: "2026-03-06T15:45:00Z"
|
|
turns:
|
|
type: array
|
|
description: Ordered list of conversation turns.
|
|
items:
|
|
$ref: "#/components/schemas/SessionTurn"
|
|
|
|
CreateSessionRequest:
|
|
description: Request body for starting a new session.
|
|
type: object
|
|
required:
|
|
- content
|
|
properties:
|
|
content:
|
|
type: string
|
|
description: The initial user message to start the session.
|
|
example: Add rate limiting to the auth endpoints using a sliding window approach with Redis, 10 requests per minute per IP.
|
|
model:
|
|
type: string
|
|
description: LLM model to use. If omitted, the server default is used.
|
|
example: claude-opus-4-6
|
|
|
|
CreateSessionResponse:
|
|
description: Response returned after successfully creating a session.
|
|
type: object
|
|
required:
|
|
- id
|
|
- title
|
|
- model
|
|
- created_at
|
|
- updated_at
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
description: Unique identifier for the newly created session.
|
|
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
|
|
title:
|
|
type: string
|
|
description: Server-generated title for the session.
|
|
example: Add rate limiting to auth endpoints
|
|
model:
|
|
$ref: "#/components/schemas/ModelReference"
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp when the session was created.
|
|
example: "2026-03-06T16:00:00Z"
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp when the session was last updated (equal to created_at at creation time).
|
|
example: "2026-03-06T16:00:00Z"
|
|
|
|
SendMessageRequest:
|
|
description: Request body for sending a follow-up message in an existing session.
|
|
type: object
|
|
required:
|
|
- content
|
|
properties:
|
|
content:
|
|
type: string
|
|
description: The user message text.
|
|
example: Can you also add a bypass for internal health-check IPs?
|
|
|
|
SendMessageResponse:
|
|
description: Acknowledgement that the message was accepted for asynchronous processing.
|
|
type: object
|
|
required:
|
|
- accepted
|
|
properties:
|
|
accepted:
|
|
type: boolean
|
|
description: Whether the message was accepted for processing.
|
|
example: true
|
|
|
|
# ── Insights Schemas ─────────────────────────────────────────────────
|
|
|
|
SavedQuery:
|
|
description: A saved SQL query for the insights editor.
|
|
type: object
|
|
required:
|
|
- id
|
|
- name
|
|
- sql
|
|
- created_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: {}
|
|
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 ─────────────────────────────────────────────────
|
|
|
|
SettingFieldType:
|
|
description: Input type for a setting field.
|
|
type: string
|
|
enum:
|
|
- text
|
|
- select
|
|
- toggle
|
|
|
|
SettingField:
|
|
description: A single configurable setting within a group.
|
|
type: object
|
|
required:
|
|
- key
|
|
- label
|
|
- value
|
|
- type
|
|
properties:
|
|
key:
|
|
type: string
|
|
description: Machine-readable setting key.
|
|
example: org_name
|
|
label:
|
|
type: string
|
|
description: Human-readable label displayed in the UI.
|
|
example: Organization name
|
|
value:
|
|
type: string
|
|
description: Current value of the setting.
|
|
example: Acme Corp
|
|
type:
|
|
$ref: "#/components/schemas/SettingFieldType"
|
|
options:
|
|
type: array
|
|
description: Available options for select-type fields.
|
|
items:
|
|
type: string
|
|
example: ["America/New_York", "UTC", "Europe/London"]
|
|
description:
|
|
type: string
|
|
description: Additional help text for the setting.
|
|
example: Comma-separated CIDRs. Leave empty to allow all.
|
|
|
|
SettingGroup:
|
|
description: A logical group of related settings.
|
|
type: object
|
|
required:
|
|
- id
|
|
- name
|
|
- description
|
|
- fields
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Machine-readable group identifier.
|
|
example: general
|
|
name:
|
|
type: string
|
|
description: Human-readable group name.
|
|
example: General
|
|
description:
|
|
type: string
|
|
description: Prose description of the settings group.
|
|
example: Core platform settings and defaults.
|
|
fields:
|
|
type: array
|
|
description: Settings within this group.
|
|
items:
|
|
$ref: "#/components/schemas/SettingField"
|
|
|
|
# ── Project Schemas ──────────────────────────────────────────────────
|
|
|
|
Project:
|
|
description: A registered project (repository).
|
|
type: object
|
|
required:
|
|
- id
|
|
- name
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique project identifier.
|
|
example: arc-web
|
|
name:
|
|
type: string
|
|
description: Human-readable project name.
|
|
example: arc-web
|
|
|
|
Branch:
|
|
description: A branch within a project.
|
|
type: object
|
|
required:
|
|
- id
|
|
- name
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Branch identifier.
|
|
example: main
|
|
name:
|
|
type: string
|
|
description: Branch name.
|
|
example: main
|
|
|
|
# ── 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: /openapi.json
|
|
current_user_url:
|
|
type: string
|
|
description: URL of the current user endpoint.
|
|
example: /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
|
|
|
|
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
|