mirror of
https://github.com/fabro-sh/fabro.git
synced 2026-09-06 08:18:58 +00:00
736d4f8ba6
Add 17 new sub-schemas (ModelReference, WorkflowReference, RunReference, RepositoryReference, CategoryReference, TokenUsage, CodeLocation, RunError, RunPullRequest, RunTimings, SandboxResources, RunSandbox, RunQuestion, AggregateUsageTotals, WorkflowSchedule, WorkflowLastRun, UsageStageRef) and restructure 11 existing schemas to use them, improving evolvability by grouping related fields into nested objects. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
3169 lines
94 KiB
YAML
3169 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
|
|
description: Human-readable relative timestamp of the next run.
|
|
example: in 4 hours
|
|
|
|
WorkflowLastRun:
|
|
description: Information about a workflow's most recent run.
|
|
type: object
|
|
required:
|
|
- label
|
|
properties:
|
|
label:
|
|
type: string
|
|
description: Human-readable relative timestamp.
|
|
example: 2 hours ago
|
|
|
|
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
|
|
description: Human-readable relative timestamp of the evaluation.
|
|
example: 2h ago
|
|
|
|
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
|
|
description: Human-readable relative timestamp of execution.
|
|
example: 2 min ago
|
|
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
|