From 5eaa653d1ffd9ac3ba150fb133c4d67e738fd7f4 Mon Sep 17 00:00:00 2001 From: Bryan Helmkamp Date: Fri, 6 Mar 2026 08:35:28 -0500 Subject: [PATCH] Move OpenAPI spec from openapi/ into docs/api-reference/ Mintlify requires all referenced files under docs/, so consolidate to a single copy and eliminate the symlink and the copy step in the generate script. Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 4 +- crates/arc-api/src/server.rs | 2 +- crates/arc-api/tests/openapi_conformance.rs | 2 +- crates/arc-types/build.rs | 2 +- docs/api-reference/arc-api.yaml | 2449 ++++++++++++++++++- docs/api-reference/client-sdks.mdx | 6 +- openapi/arc-api.yaml | 2448 ------------------ packages/arc-api-client/package.json | 2 +- 8 files changed, 2457 insertions(+), 2458 deletions(-) mode change 120000 => 100644 docs/api-reference/arc-api.yaml delete mode 100644 openapi/arc-api.yaml diff --git a/CLAUDE.md b/CLAUDE.md index d47edcc72..84d71eb60 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,9 +7,9 @@ ## API workflow -The OpenAPI spec at `openapi/arc-api.yaml` is the source of truth for the arc-api HTTP interface. +The OpenAPI spec at `docs/api-reference/arc-api.yaml` is the source of truth for the arc-api HTTP interface. -1. Edit `openapi/arc-api.yaml` +1. Edit `docs/api-reference/arc-api.yaml` 2. `cargo build -p arc-types` — build.rs regenerates Rust types via typify 3. Write/update handler in `crates/arc-api/src/server.rs`, add route to `build_router()` 4. `cargo test -p arc-api` — conformance test catches spec/router drift diff --git a/crates/arc-api/src/server.rs b/crates/arc-api/src/server.rs index 1774dc534..c5596a9da 100644 --- a/crates/arc-api/src/server.rs +++ b/crates/arc-api/src/server.rs @@ -297,7 +297,7 @@ async fn health() -> Response { } async fn openapi_spec() -> Response { - let yaml = include_str!("../../../openapi/arc-api.yaml"); + let yaml = include_str!("../../../docs/api-reference/arc-api.yaml"); let value: serde_json::Value = serde_yaml::from_str(yaml).expect("embedded OpenAPI YAML is invalid"); Json(value).into_response() } diff --git a/crates/arc-api/tests/openapi_conformance.rs b/crates/arc-api/tests/openapi_conformance.rs index 53ba27c1d..cebd4e907 100644 --- a/crates/arc-api/tests/openapi_conformance.rs +++ b/crates/arc-api/tests/openapi_conformance.rs @@ -31,7 +31,7 @@ fn load_spec() -> openapiv3::OpenAPI { .unwrap() .parent() .unwrap() - .join("openapi/arc-api.yaml"); + .join("docs/api-reference/arc-api.yaml"); let text = std::fs::read_to_string(&spec_path).expect("failed to read spec"); serde_yaml::from_str(&text).expect("failed to parse spec") } diff --git a/crates/arc-types/build.rs b/crates/arc-types/build.rs index 51e195b97..49f53f17b 100644 --- a/crates/arc-types/build.rs +++ b/crates/arc-types/build.rs @@ -8,7 +8,7 @@ fn main() { .unwrap() .parent() .unwrap() - .join("openapi/arc-api.yaml"); + .join("docs/api-reference/arc-api.yaml"); println!("cargo::rerun-if-changed={}", spec_path.display()); diff --git a/docs/api-reference/arc-api.yaml b/docs/api-reference/arc-api.yaml deleted file mode 120000 index 3f32abfbd..000000000 --- a/docs/api-reference/arc-api.yaml +++ /dev/null @@ -1 +0,0 @@ -../../openapi/arc-api.yaml \ No newline at end of file diff --git a/docs/api-reference/arc-api.yaml b/docs/api-reference/arc-api.yaml new file mode 100644 index 000000000..3900a0425 --- /dev/null +++ b/docs/api-reference/arc-api.yaml @@ -0,0 +1,2448 @@ +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 + 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 + 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 + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/StartRunRequest" + responses: + "201": + description: Run created + content: + application/json: + schema: + $ref: "#/components/schemas/StartRunResponse" + "400": + description: Invalid DOT source + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + + /runs/{id}: + get: + operationId: retrieveRun + tags: [Runs] + summary: Retrieve Run + 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 + parameters: + - $ref: "#/components/parameters/RunId" + responses: + "200": + description: Run cancelled + content: + application/json: + schema: + type: object + properties: + cancelled: + type: boolean + required: + - cancelled + "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: retrieveRunSvg + tags: [Runs] + summary: Render SVG + 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 + parameters: + - $ref: "#/components/parameters/RunId" + responses: + "200": + description: Checkpoint data (null if not yet available) + content: + application/json: + schema: {} + "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 + parameters: + - $ref: "#/components/parameters/RunId" + responses: + "200": + description: Context key-value map + content: + application/json: + schema: + type: object + "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 + 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 + parameters: + - $ref: "#/components/parameters/RunId" + 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 + parameters: + - $ref: "#/components/parameters/RunId" + - name: qid + in: path + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/SubmitAnswerRequest" + responses: + "200": + description: Answer accepted or rejected + content: + application/json: + schema: + $ref: "#/components/schemas/SubmitAnswerResponse" + "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" + + /runs/{id}/retro: + get: + operationId: retrieveRetro + tags: [Retros] + summary: Retrieve Retro + parameters: + - $ref: "#/components/parameters/RunId" + responses: + "200": + description: Retro data (null if not yet available) + content: + application/json: + schema: {} + "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 + parameters: + - $ref: "#/components/parameters/RunId" + 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 + parameters: + - $ref: "#/components/parameters/RunId" + - name: stageId + in: path + required: true + schema: + type: string + - $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: listRunCompare + tags: [Run Outputs] + summary: List Run Compare + parameters: + - $ref: "#/components/parameters/RunId" + - name: checkpoint + in: query + schema: + type: string + default: "all" + 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 + 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 + parameters: + - $ref: "#/components/parameters/RunId" + 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 + 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 + parameters: + - $ref: "#/components/parameters/RunId" + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/SteerRequest" + responses: + "200": + description: Steering accepted + content: + application/json: + schema: + type: object + properties: + accepted: + type: boolean + required: + - accepted + "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 + parameters: + - $ref: "#/components/parameters/RunId" + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/PreviewUrlRequest" + responses: + "200": + description: Preview URL generated + 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 + 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 + parameters: + - name: name + in: path + required: true + schema: + type: string + 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 + parameters: + - name: name + in: path + required: true + schema: + type: string + - $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 + parameters: + - name: name + in: path + required: true + schema: + type: string + responses: + "201": + description: Run created + content: + application/json: + schema: + $ref: "#/components/schemas/StartRunResponse" + "404": + description: Workflow not found + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + + # ── Verifications ───────────────────────────────────────────────────── + + /verifications: + get: + operationId: listVerifications + tags: [Verifications] + summary: List Verifications + 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 + parameters: + - name: slug + in: path + required: true + schema: + type: string + 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 + 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. Events include new assistant turns, tool invocations, and completion signals. + parameters: + - $ref: "#/components/parameters/SessionId" + 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 + 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 + 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 + parameters: + - name: id + in: path + required: true + schema: + type: string + 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 + parameters: + - name: id + in: path + required: true + schema: + type: string + 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 + 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 + 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 + 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 + 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 + parameters: + - name: id + in: path + required: true + schema: + type: string + - $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 + schema: + type: string + + SessionId: + name: id + in: path + required: true + description: Unique session identifier. + schema: + type: string + example: s1 + + PageLimit: + name: page[limit] + in: query + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + + PageOffset: + name: page[offset] + in: query + required: false + schema: + type: integer + minimum: 0 + default: 0 + + schemas: + PaginationMeta: + type: object + required: + - has_more + properties: + has_more: + type: boolean + + PaginatedRunList: + type: object + required: + - data + - meta + properties: + data: + type: array + items: + $ref: "#/components/schemas/RunListItem" + meta: + $ref: "#/components/schemas/PaginationMeta" + + PaginatedWorkflowList: + type: object + required: + - data + - meta + properties: + data: + type: array + items: + $ref: "#/components/schemas/WorkflowListItem" + meta: + $ref: "#/components/schemas/PaginationMeta" + + PaginatedRetroList: + type: object + required: + - data + - meta + properties: + data: + type: array + items: + $ref: "#/components/schemas/RetroListItem" + meta: + $ref: "#/components/schemas/PaginationMeta" + + PaginatedSessionList: + type: object + required: + - data + - meta + properties: + data: + type: array + items: + $ref: "#/components/schemas/SessionListItem" + meta: + $ref: "#/components/schemas/PaginationMeta" + + PaginatedProjectList: + type: object + required: + - data + - meta + properties: + data: + type: array + items: + $ref: "#/components/schemas/Project" + meta: + $ref: "#/components/schemas/PaginationMeta" + + PaginatedBranchList: + type: object + required: + - data + - meta + properties: + data: + type: array + items: + $ref: "#/components/schemas/Branch" + meta: + $ref: "#/components/schemas/PaginationMeta" + + PaginatedSavedQueryList: + type: object + required: + - data + - meta + properties: + data: + type: array + items: + $ref: "#/components/schemas/SavedQuery" + meta: + $ref: "#/components/schemas/PaginationMeta" + + PaginatedHistoryEntryList: + type: object + required: + - data + - meta + properties: + data: + type: array + items: + $ref: "#/components/schemas/HistoryEntry" + meta: + $ref: "#/components/schemas/PaginationMeta" + + PaginatedStageTurnList: + type: object + required: + - data + - meta + properties: + data: + type: array + items: + $ref: "#/components/schemas/StageTurn" + meta: + $ref: "#/components/schemas/PaginationMeta" + + PaginatedApiQuestionList: + type: object + required: + - data + - meta + properties: + data: + type: array + items: + $ref: "#/components/schemas/ApiQuestion" + meta: + $ref: "#/components/schemas/PaginationMeta" + + PaginatedRunStageList: + type: object + required: + - data + - meta + properties: + data: + type: array + items: + $ref: "#/components/schemas/RunStage" + meta: + $ref: "#/components/schemas/PaginationMeta" + + PaginatedRunVerificationList: + type: object + required: + - data + - meta + properties: + data: + type: array + items: + $ref: "#/components/schemas/RunVerification" + meta: + $ref: "#/components/schemas/PaginationMeta" + + PaginatedVerificationCategoryList: + type: object + required: + - data + - meta + properties: + data: + type: array + items: + $ref: "#/components/schemas/VerificationCategory" + meta: + $ref: "#/components/schemas/PaginationMeta" + + # ── Existing Run Schemas ──────────────────────────────────────────── + + RunStatus: + type: string + enum: + - queued + - starting + - running + - completed + - failed + - cancelled + + StartRunRequest: + type: object + required: + - dot_source + properties: + dot_source: + type: string + + StartRunResponse: + type: object + required: + - id + properties: + id: + type: string + + RunStatusResponse: + type: object + required: + - id + - status + properties: + id: + type: string + status: + $ref: "#/components/schemas/RunStatus" + error: + type: string + queue_position: + type: integer + + ApiQuestionOption: + type: object + required: + - key + - label + properties: + key: + type: string + label: + type: string + + ApiQuestion: + type: object + required: + - id + - text + - question_type + - options + - allow_freeform + properties: + id: + type: string + text: + type: string + question_type: + $ref: "#/components/schemas/QuestionType" + options: + type: array + items: + $ref: "#/components/schemas/ApiQuestionOption" + allow_freeform: + type: boolean + + QuestionType: + type: string + enum: + - yes_no + - multiple_choice + - multi_select + - freeform + - confirmation + + SubmitAnswerRequest: + type: object + required: + - value + properties: + value: + type: string + selected_option_key: + type: string + + SubmitAnswerResponse: + type: object + required: + - accepted + properties: + accepted: + type: boolean + + ErrorResponseEntry: + type: object + required: + - status + - title + - detail + properties: + status: + type: string + title: + type: string + detail: + type: string + + ErrorResponse: + type: object + required: + - errors + properties: + errors: + type: array + items: + $ref: "#/components/schemas/ErrorResponseEntry" + + # ── New Run Schemas ───────────────────────────────────────────────── + + RunListItemStatus: + type: string + enum: + - working + - pending + - review + - merge + + CheckRunStatus: + type: string + enum: + - success + - failure + - skipped + - pending + - queued + + CheckRun: + type: object + required: + - name + - status + properties: + name: + type: string + status: + $ref: "#/components/schemas/CheckRunStatus" + duration_secs: + type: number + + RunListItem: + type: object + required: + - id + - repo + - title + - workflow + - status + properties: + id: + type: string + repo: + type: string + title: + type: string + workflow: + type: string + status: + $ref: "#/components/schemas/RunListItemStatus" + number: + type: integer + additions: + type: integer + deletions: + type: integer + checks: + type: array + items: + $ref: "#/components/schemas/CheckRun" + elapsed_secs: + type: number + elapsed_warning: + type: boolean + resources: + type: string + comments: + type: integer + question: + type: string + sandbox_id: + type: string + + StageStatus: + type: string + enum: + - completed + - running + - pending + - failed + + RunStage: + type: object + required: + - id + - name + - status + properties: + id: + type: string + name: + type: string + status: + $ref: "#/components/schemas/StageStatus" + duration_secs: + type: number + dot_id: + type: string + + 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: + type: object + required: + - kind + properties: + kind: + type: string + enum: + - system + - assistant + - tool + content: + type: string + tools: + type: array + items: + $ref: "#/components/schemas/ToolUse" + + FileCheckpoint: + type: object + required: + - id + - label + properties: + id: + type: string + label: + type: string + + DiffFile: + type: object + required: + - name + - contents + properties: + name: + type: string + contents: + type: string + + FileDiff: + type: object + required: + - old_file + - new_file + properties: + old_file: + $ref: "#/components/schemas/DiffFile" + new_file: + $ref: "#/components/schemas/DiffFile" + + DiffStats: + type: object + required: + - additions + - deletions + properties: + additions: + type: integer + deletions: + type: integer + + RunCompare: + type: object + required: + - checkpoints + - files + - stats + properties: + checkpoints: + type: array + items: + $ref: "#/components/schemas/FileCheckpoint" + files: + type: array + items: + $ref: "#/components/schemas/FileDiff" + stats: + $ref: "#/components/schemas/DiffStats" + + UsageStage: + type: object + required: + - stage + - model + - input_tokens + - output_tokens + - runtime_secs + - cost + properties: + stage: + type: string + model: + type: string + input_tokens: + type: integer + output_tokens: + type: integer + runtime_secs: + type: number + cost: + type: number + + UsageTotals: + type: object + required: + - runtime_secs + - input_tokens + - output_tokens + - cost + properties: + runtime_secs: + type: number + input_tokens: + type: integer + output_tokens: + type: integer + cost: + type: number + + UsageByModel: + type: object + required: + - model + - stages + - input_tokens + - output_tokens + - cost + properties: + model: + type: string + stages: + type: integer + input_tokens: + type: integer + output_tokens: + type: integer + cost: + type: number + + RunUsage: + type: object + required: + - stages + - totals + - by_model + properties: + stages: + type: array + items: + $ref: "#/components/schemas/UsageStage" + totals: + $ref: "#/components/schemas/UsageTotals" + by_model: + type: array + items: + $ref: "#/components/schemas/UsageByModel" + + AggregateUsage: + type: object + required: + - total_runs + - total_input_tokens + - total_output_tokens + - total_cost + - total_runtime_secs + - by_model + properties: + total_runs: + type: integer + total_input_tokens: + type: integer + total_output_tokens: + type: integer + total_cost: + type: number + total_runtime_secs: + type: number + by_model: + type: array + items: + $ref: "#/components/schemas/UsageByModel" + + VerificationStatus: + type: string + enum: + - pass + - fail + - na + + VerificationType: + type: string + enum: + - ai + - automated + - analysis + - ai-analysis + + RunVerificationControl: + type: object + required: + - name + - description + - status + properties: + name: + type: string + description: + type: string + type: + $ref: "#/components/schemas/VerificationType" + status: + $ref: "#/components/schemas/VerificationStatus" + + RunVerification: + type: object + required: + - name + - question + - status + - controls + properties: + name: + type: string + question: + type: string + status: + $ref: "#/components/schemas/VerificationStatus" + controls: + type: array + items: + $ref: "#/components/schemas/RunVerificationControl" + + SteerRequest: + type: object + required: + - file + - line + - guidance + properties: + file: + type: string + line: + type: integer + guidance: + type: string + + PreviewUrlRequest: + type: object + required: + - port + - expires_in_secs + properties: + port: + type: integer + expires_in_secs: + type: integer + + PreviewUrlResponse: + type: object + required: + - url + properties: + url: + type: string + + # ── Workflow Schemas ───────────────────────────────────────────────── + + WorkflowListItem: + type: object + required: + - name + - slug + - filename + properties: + name: + type: string + slug: + type: string + filename: + type: string + last_run: + type: string + schedule: + type: string + next_run: + type: string + + WorkflowDetail: + type: object + required: + - title + - slug + - filename + - description + - config + - graph + properties: + title: + type: string + slug: + type: string + filename: + type: string + description: + type: string + config: + type: string + graph: + type: string + + # ── Verification Schemas ──────────────────────────────────────────── + + EvaluationResult: + type: string + enum: + - pass + - fail + - skip + + VerificationMode: + type: string + enum: + - active + - evaluate + - disabled + + VerificationControl: + type: object + required: + - name + - slug + - description + properties: + name: + type: string + slug: + type: string + description: + type: string + type: + $ref: "#/components/schemas/VerificationType" + mode: + $ref: "#/components/schemas/VerificationMode" + f1: + type: number + pass_at_1: + type: number + evaluations: + type: array + items: + $ref: "#/components/schemas/EvaluationResult" + + VerificationCategory: + type: object + required: + - name + - question + - controls + properties: + name: + type: string + question: + type: string + controls: + type: array + items: + $ref: "#/components/schemas/VerificationControl" + + ControlInfo: + type: object + required: + - name + - slug + - description + - category + properties: + name: + type: string + slug: + type: string + description: + type: string + type: + $ref: "#/components/schemas/VerificationType" + category: + type: string + + ControlPerformance: + type: object + required: + - mode + - evaluations + properties: + mode: + $ref: "#/components/schemas/VerificationMode" + f1: + type: number + pass_at_1: + type: number + evaluations: + type: array + items: + $ref: "#/components/schemas/EvaluationResult" + + ControlDetail: + type: object + required: + - description + - checks + - pass_example + - fail_example + properties: + description: + type: string + checks: + type: array + items: + type: string + pass_example: + type: string + fail_example: + type: string + + RecentControlResult: + type: object + required: + - run_id + - run_title + - workflow + - result + - timestamp + properties: + run_id: + type: string + run_title: + type: string + workflow: + type: string + result: + $ref: "#/components/schemas/VerificationStatus" + timestamp: + type: string + + SiblingControl: + type: object + required: + - name + - slug + properties: + name: + type: string + slug: + type: string + type: + $ref: "#/components/schemas/VerificationType" + mode: + $ref: "#/components/schemas/VerificationMode" + + VerificationDetailResponse: + 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 + items: + $ref: "#/components/schemas/RecentControlResult" + siblings: + type: array + items: + $ref: "#/components/schemas/SiblingControl" + + # ── Retro Schemas ─────────────────────────────────────────────────── + + SmoothnessRating: + type: string + enum: + - effortless + - smooth + - bumpy + - struggled + - failed + + RetroStats: + type: object + required: + - total_duration_ms + - total_retries + - files_touched + - stages_completed + - stages_failed + properties: + total_duration_ms: + type: integer + total_cost: + type: number + total_retries: + type: integer + files_touched: + type: array + items: + type: string + stages_completed: + type: integer + stages_failed: + type: integer + + RetroListItem: + type: object + required: + - run_id + - workflow_name + - goal + - timestamp + - stats + - friction_point_count + properties: + run_id: + type: string + workflow_name: + type: string + goal: + type: string + timestamp: + type: string + smoothness: + $ref: "#/components/schemas/SmoothnessRating" + stats: + $ref: "#/components/schemas/RetroStats" + friction_point_count: + type: integer + + # ── Session Schemas ───────────────────────────────────────────────── + + SessionListItem: + description: Summary of a session shown in list views. + type: object + required: + - id + - title + - created_at + - updated_at + properties: + id: + type: string + description: Unique session identifier. + example: s1 + title: + type: string + description: Short title summarizing the session topic. + example: Add rate limiting to auth endpoints + 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 + 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. + + ToolTurn: + description: A tool invocation turn. + type: object + required: + - kind + - tools + properties: + kind: + type: string + enum: [tool] + tools: + type: array + description: Tool invocations for this turn. + items: + $ref: "#/components/schemas/ToolUse" + + 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 + description: Unique session identifier. + example: s1 + title: + type: string + description: Short title summarizing the session topic. + example: Add rate limiting to auth endpoints + model: + type: string + description: The LLM model used for this session. + example: Opus 4.6 + 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: Opus 4.6 + + CreateSessionResponse: + description: Response returned after successfully creating a session. + type: object + required: + - id + - created_at + properties: + id: + type: string + description: Unique identifier for the newly created session. + example: s42 + created_at: + type: string + format: date-time + description: Timestamp when the session was created. + 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: + type: object + required: + - id + - name + - sql + properties: + id: + type: string + name: + type: string + sql: + type: string + + SaveQueryRequest: + type: object + required: + - name + - sql + properties: + name: + type: string + sql: + type: string + + ExecuteQueryRequest: + type: object + required: + - sql + properties: + sql: + type: string + + ExecuteQueryResponse: + type: object + required: + - columns + - rows + - elapsed + - row_count + properties: + columns: + type: array + items: + type: string + rows: + type: array + items: + type: array + items: {} + elapsed: + type: number + row_count: + type: integer + + HistoryEntry: + type: object + required: + - id + - sql + - timestamp + - elapsed + - row_count + properties: + id: + type: string + sql: + type: string + timestamp: + type: string + elapsed: + type: number + row_count: + type: integer + + # ── Settings Schemas ──────────────────────────────────────────────── + + SettingFieldType: + type: string + enum: + - text + - select + - toggle + + SettingField: + type: object + required: + - key + - label + - value + - type + properties: + key: + type: string + label: + type: string + value: + type: string + type: + $ref: "#/components/schemas/SettingFieldType" + options: + type: array + items: + type: string + description: + type: string + + SettingGroup: + type: object + required: + - id + - name + - description + - fields + properties: + id: + type: string + name: + type: string + description: + type: string + fields: + type: array + items: + $ref: "#/components/schemas/SettingField" + + # ── Project Schemas ───────────────────────────────────────────────── + + Project: + type: object + required: + - id + - name + properties: + id: + type: string + name: + type: string + + Branch: + type: object + required: + - id + - name + properties: + id: + type: string + name: + type: string + + # ── Discovery Schemas ────────────────────────────────────────────── + + RootResponseUrls: + type: object + required: + - openapi_url + - current_user_url + - health_url + properties: + openapi_url: + type: string + current_user_url: + type: string + health_url: + type: string + + RootResponse: + type: object + required: + - urls + properties: + urls: + $ref: "#/components/schemas/RootResponseUrls" + + HealthResponse: + type: object + required: + - status + properties: + status: + type: string + + UserResponse: + type: object + required: + - login + properties: + login: + type: string diff --git a/docs/api-reference/client-sdks.mdx b/docs/api-reference/client-sdks.mdx index 4aeaf0997..80d8b31a8 100644 --- a/docs/api-reference/client-sdks.mdx +++ b/docs/api-reference/client-sdks.mdx @@ -3,7 +3,7 @@ title: "Client SDKs" description: "Language-specific clients generated from the Arc OpenAPI spec" --- -The Arc API is defined by an OpenAPI 3.1 specification (`openapi/arc-api.yaml` in the repository) that serves as the single source of truth for all endpoints, request/response schemas, and parameter definitions. The spec is also available at runtime from the server at `GET /openapi.json`. Both client SDKs below are generated directly from this spec. +The Arc API is defined by an OpenAPI 3.1 specification (`docs/api-reference/arc-api.yaml` in the repository) that serves as the single source of truth for all endpoints, request/response schemas, and parameter definitions. The spec is also available at runtime from the server at `GET /openapi.json`. Both client SDKs below are generated directly from this spec. ## TypeScript (Axios) @@ -18,7 +18,7 @@ cd packages/arc-api-client bun run generate ``` -This runs `openapi-generator-cli` against `openapi/arc-api.yaml` and writes the generated source into `packages/arc-api-client/src/`. +This runs `openapi-generator-cli` against `docs/api-reference/arc-api.yaml` and writes the generated source into `packages/arc-api-client/src/`. ### Usage @@ -40,7 +40,7 @@ The `arc-types` crate generates Rust structs and enums from the OpenAPI componen ### How It Works -A `build.rs` script reads `openapi/arc-api.yaml`, extracts `components/schemas`, and feeds them to typify. The generated code is written to `OUT_DIR` and included via: +A `build.rs` script reads `docs/api-reference/arc-api.yaml`, extracts `components/schemas`, and feeds them to typify. The generated code is written to `OUT_DIR` and included via: ```rust // crates/arc-types/src/lib.rs diff --git a/openapi/arc-api.yaml b/openapi/arc-api.yaml deleted file mode 100644 index 3900a0425..000000000 --- a/openapi/arc-api.yaml +++ /dev/null @@ -1,2448 +0,0 @@ -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 - 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 - 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 - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/StartRunRequest" - responses: - "201": - description: Run created - content: - application/json: - schema: - $ref: "#/components/schemas/StartRunResponse" - "400": - description: Invalid DOT source - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - - /runs/{id}: - get: - operationId: retrieveRun - tags: [Runs] - summary: Retrieve Run - 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 - parameters: - - $ref: "#/components/parameters/RunId" - responses: - "200": - description: Run cancelled - content: - application/json: - schema: - type: object - properties: - cancelled: - type: boolean - required: - - cancelled - "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: retrieveRunSvg - tags: [Runs] - summary: Render SVG - 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 - parameters: - - $ref: "#/components/parameters/RunId" - responses: - "200": - description: Checkpoint data (null if not yet available) - content: - application/json: - schema: {} - "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 - parameters: - - $ref: "#/components/parameters/RunId" - responses: - "200": - description: Context key-value map - content: - application/json: - schema: - type: object - "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 - 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 - parameters: - - $ref: "#/components/parameters/RunId" - 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 - parameters: - - $ref: "#/components/parameters/RunId" - - name: qid - in: path - required: true - schema: - type: string - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/SubmitAnswerRequest" - responses: - "200": - description: Answer accepted or rejected - content: - application/json: - schema: - $ref: "#/components/schemas/SubmitAnswerResponse" - "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" - - /runs/{id}/retro: - get: - operationId: retrieveRetro - tags: [Retros] - summary: Retrieve Retro - parameters: - - $ref: "#/components/parameters/RunId" - responses: - "200": - description: Retro data (null if not yet available) - content: - application/json: - schema: {} - "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 - parameters: - - $ref: "#/components/parameters/RunId" - 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 - parameters: - - $ref: "#/components/parameters/RunId" - - name: stageId - in: path - required: true - schema: - type: string - - $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: listRunCompare - tags: [Run Outputs] - summary: List Run Compare - parameters: - - $ref: "#/components/parameters/RunId" - - name: checkpoint - in: query - schema: - type: string - default: "all" - 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 - 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 - parameters: - - $ref: "#/components/parameters/RunId" - 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 - 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 - parameters: - - $ref: "#/components/parameters/RunId" - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/SteerRequest" - responses: - "200": - description: Steering accepted - content: - application/json: - schema: - type: object - properties: - accepted: - type: boolean - required: - - accepted - "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 - parameters: - - $ref: "#/components/parameters/RunId" - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/PreviewUrlRequest" - responses: - "200": - description: Preview URL generated - 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 - 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 - parameters: - - name: name - in: path - required: true - schema: - type: string - 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 - parameters: - - name: name - in: path - required: true - schema: - type: string - - $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 - parameters: - - name: name - in: path - required: true - schema: - type: string - responses: - "201": - description: Run created - content: - application/json: - schema: - $ref: "#/components/schemas/StartRunResponse" - "404": - description: Workflow not found - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - - # ── Verifications ───────────────────────────────────────────────────── - - /verifications: - get: - operationId: listVerifications - tags: [Verifications] - summary: List Verifications - 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 - parameters: - - name: slug - in: path - required: true - schema: - type: string - 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 - 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. Events include new assistant turns, tool invocations, and completion signals. - parameters: - - $ref: "#/components/parameters/SessionId" - 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 - 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 - 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 - parameters: - - name: id - in: path - required: true - schema: - type: string - 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 - parameters: - - name: id - in: path - required: true - schema: - type: string - 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 - 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 - 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 - 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 - 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 - parameters: - - name: id - in: path - required: true - schema: - type: string - - $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 - schema: - type: string - - SessionId: - name: id - in: path - required: true - description: Unique session identifier. - schema: - type: string - example: s1 - - PageLimit: - name: page[limit] - in: query - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - default: 20 - - PageOffset: - name: page[offset] - in: query - required: false - schema: - type: integer - minimum: 0 - default: 0 - - schemas: - PaginationMeta: - type: object - required: - - has_more - properties: - has_more: - type: boolean - - PaginatedRunList: - type: object - required: - - data - - meta - properties: - data: - type: array - items: - $ref: "#/components/schemas/RunListItem" - meta: - $ref: "#/components/schemas/PaginationMeta" - - PaginatedWorkflowList: - type: object - required: - - data - - meta - properties: - data: - type: array - items: - $ref: "#/components/schemas/WorkflowListItem" - meta: - $ref: "#/components/schemas/PaginationMeta" - - PaginatedRetroList: - type: object - required: - - data - - meta - properties: - data: - type: array - items: - $ref: "#/components/schemas/RetroListItem" - meta: - $ref: "#/components/schemas/PaginationMeta" - - PaginatedSessionList: - type: object - required: - - data - - meta - properties: - data: - type: array - items: - $ref: "#/components/schemas/SessionListItem" - meta: - $ref: "#/components/schemas/PaginationMeta" - - PaginatedProjectList: - type: object - required: - - data - - meta - properties: - data: - type: array - items: - $ref: "#/components/schemas/Project" - meta: - $ref: "#/components/schemas/PaginationMeta" - - PaginatedBranchList: - type: object - required: - - data - - meta - properties: - data: - type: array - items: - $ref: "#/components/schemas/Branch" - meta: - $ref: "#/components/schemas/PaginationMeta" - - PaginatedSavedQueryList: - type: object - required: - - data - - meta - properties: - data: - type: array - items: - $ref: "#/components/schemas/SavedQuery" - meta: - $ref: "#/components/schemas/PaginationMeta" - - PaginatedHistoryEntryList: - type: object - required: - - data - - meta - properties: - data: - type: array - items: - $ref: "#/components/schemas/HistoryEntry" - meta: - $ref: "#/components/schemas/PaginationMeta" - - PaginatedStageTurnList: - type: object - required: - - data - - meta - properties: - data: - type: array - items: - $ref: "#/components/schemas/StageTurn" - meta: - $ref: "#/components/schemas/PaginationMeta" - - PaginatedApiQuestionList: - type: object - required: - - data - - meta - properties: - data: - type: array - items: - $ref: "#/components/schemas/ApiQuestion" - meta: - $ref: "#/components/schemas/PaginationMeta" - - PaginatedRunStageList: - type: object - required: - - data - - meta - properties: - data: - type: array - items: - $ref: "#/components/schemas/RunStage" - meta: - $ref: "#/components/schemas/PaginationMeta" - - PaginatedRunVerificationList: - type: object - required: - - data - - meta - properties: - data: - type: array - items: - $ref: "#/components/schemas/RunVerification" - meta: - $ref: "#/components/schemas/PaginationMeta" - - PaginatedVerificationCategoryList: - type: object - required: - - data - - meta - properties: - data: - type: array - items: - $ref: "#/components/schemas/VerificationCategory" - meta: - $ref: "#/components/schemas/PaginationMeta" - - # ── Existing Run Schemas ──────────────────────────────────────────── - - RunStatus: - type: string - enum: - - queued - - starting - - running - - completed - - failed - - cancelled - - StartRunRequest: - type: object - required: - - dot_source - properties: - dot_source: - type: string - - StartRunResponse: - type: object - required: - - id - properties: - id: - type: string - - RunStatusResponse: - type: object - required: - - id - - status - properties: - id: - type: string - status: - $ref: "#/components/schemas/RunStatus" - error: - type: string - queue_position: - type: integer - - ApiQuestionOption: - type: object - required: - - key - - label - properties: - key: - type: string - label: - type: string - - ApiQuestion: - type: object - required: - - id - - text - - question_type - - options - - allow_freeform - properties: - id: - type: string - text: - type: string - question_type: - $ref: "#/components/schemas/QuestionType" - options: - type: array - items: - $ref: "#/components/schemas/ApiQuestionOption" - allow_freeform: - type: boolean - - QuestionType: - type: string - enum: - - yes_no - - multiple_choice - - multi_select - - freeform - - confirmation - - SubmitAnswerRequest: - type: object - required: - - value - properties: - value: - type: string - selected_option_key: - type: string - - SubmitAnswerResponse: - type: object - required: - - accepted - properties: - accepted: - type: boolean - - ErrorResponseEntry: - type: object - required: - - status - - title - - detail - properties: - status: - type: string - title: - type: string - detail: - type: string - - ErrorResponse: - type: object - required: - - errors - properties: - errors: - type: array - items: - $ref: "#/components/schemas/ErrorResponseEntry" - - # ── New Run Schemas ───────────────────────────────────────────────── - - RunListItemStatus: - type: string - enum: - - working - - pending - - review - - merge - - CheckRunStatus: - type: string - enum: - - success - - failure - - skipped - - pending - - queued - - CheckRun: - type: object - required: - - name - - status - properties: - name: - type: string - status: - $ref: "#/components/schemas/CheckRunStatus" - duration_secs: - type: number - - RunListItem: - type: object - required: - - id - - repo - - title - - workflow - - status - properties: - id: - type: string - repo: - type: string - title: - type: string - workflow: - type: string - status: - $ref: "#/components/schemas/RunListItemStatus" - number: - type: integer - additions: - type: integer - deletions: - type: integer - checks: - type: array - items: - $ref: "#/components/schemas/CheckRun" - elapsed_secs: - type: number - elapsed_warning: - type: boolean - resources: - type: string - comments: - type: integer - question: - type: string - sandbox_id: - type: string - - StageStatus: - type: string - enum: - - completed - - running - - pending - - failed - - RunStage: - type: object - required: - - id - - name - - status - properties: - id: - type: string - name: - type: string - status: - $ref: "#/components/schemas/StageStatus" - duration_secs: - type: number - dot_id: - type: string - - 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: - type: object - required: - - kind - properties: - kind: - type: string - enum: - - system - - assistant - - tool - content: - type: string - tools: - type: array - items: - $ref: "#/components/schemas/ToolUse" - - FileCheckpoint: - type: object - required: - - id - - label - properties: - id: - type: string - label: - type: string - - DiffFile: - type: object - required: - - name - - contents - properties: - name: - type: string - contents: - type: string - - FileDiff: - type: object - required: - - old_file - - new_file - properties: - old_file: - $ref: "#/components/schemas/DiffFile" - new_file: - $ref: "#/components/schemas/DiffFile" - - DiffStats: - type: object - required: - - additions - - deletions - properties: - additions: - type: integer - deletions: - type: integer - - RunCompare: - type: object - required: - - checkpoints - - files - - stats - properties: - checkpoints: - type: array - items: - $ref: "#/components/schemas/FileCheckpoint" - files: - type: array - items: - $ref: "#/components/schemas/FileDiff" - stats: - $ref: "#/components/schemas/DiffStats" - - UsageStage: - type: object - required: - - stage - - model - - input_tokens - - output_tokens - - runtime_secs - - cost - properties: - stage: - type: string - model: - type: string - input_tokens: - type: integer - output_tokens: - type: integer - runtime_secs: - type: number - cost: - type: number - - UsageTotals: - type: object - required: - - runtime_secs - - input_tokens - - output_tokens - - cost - properties: - runtime_secs: - type: number - input_tokens: - type: integer - output_tokens: - type: integer - cost: - type: number - - UsageByModel: - type: object - required: - - model - - stages - - input_tokens - - output_tokens - - cost - properties: - model: - type: string - stages: - type: integer - input_tokens: - type: integer - output_tokens: - type: integer - cost: - type: number - - RunUsage: - type: object - required: - - stages - - totals - - by_model - properties: - stages: - type: array - items: - $ref: "#/components/schemas/UsageStage" - totals: - $ref: "#/components/schemas/UsageTotals" - by_model: - type: array - items: - $ref: "#/components/schemas/UsageByModel" - - AggregateUsage: - type: object - required: - - total_runs - - total_input_tokens - - total_output_tokens - - total_cost - - total_runtime_secs - - by_model - properties: - total_runs: - type: integer - total_input_tokens: - type: integer - total_output_tokens: - type: integer - total_cost: - type: number - total_runtime_secs: - type: number - by_model: - type: array - items: - $ref: "#/components/schemas/UsageByModel" - - VerificationStatus: - type: string - enum: - - pass - - fail - - na - - VerificationType: - type: string - enum: - - ai - - automated - - analysis - - ai-analysis - - RunVerificationControl: - type: object - required: - - name - - description - - status - properties: - name: - type: string - description: - type: string - type: - $ref: "#/components/schemas/VerificationType" - status: - $ref: "#/components/schemas/VerificationStatus" - - RunVerification: - type: object - required: - - name - - question - - status - - controls - properties: - name: - type: string - question: - type: string - status: - $ref: "#/components/schemas/VerificationStatus" - controls: - type: array - items: - $ref: "#/components/schemas/RunVerificationControl" - - SteerRequest: - type: object - required: - - file - - line - - guidance - properties: - file: - type: string - line: - type: integer - guidance: - type: string - - PreviewUrlRequest: - type: object - required: - - port - - expires_in_secs - properties: - port: - type: integer - expires_in_secs: - type: integer - - PreviewUrlResponse: - type: object - required: - - url - properties: - url: - type: string - - # ── Workflow Schemas ───────────────────────────────────────────────── - - WorkflowListItem: - type: object - required: - - name - - slug - - filename - properties: - name: - type: string - slug: - type: string - filename: - type: string - last_run: - type: string - schedule: - type: string - next_run: - type: string - - WorkflowDetail: - type: object - required: - - title - - slug - - filename - - description - - config - - graph - properties: - title: - type: string - slug: - type: string - filename: - type: string - description: - type: string - config: - type: string - graph: - type: string - - # ── Verification Schemas ──────────────────────────────────────────── - - EvaluationResult: - type: string - enum: - - pass - - fail - - skip - - VerificationMode: - type: string - enum: - - active - - evaluate - - disabled - - VerificationControl: - type: object - required: - - name - - slug - - description - properties: - name: - type: string - slug: - type: string - description: - type: string - type: - $ref: "#/components/schemas/VerificationType" - mode: - $ref: "#/components/schemas/VerificationMode" - f1: - type: number - pass_at_1: - type: number - evaluations: - type: array - items: - $ref: "#/components/schemas/EvaluationResult" - - VerificationCategory: - type: object - required: - - name - - question - - controls - properties: - name: - type: string - question: - type: string - controls: - type: array - items: - $ref: "#/components/schemas/VerificationControl" - - ControlInfo: - type: object - required: - - name - - slug - - description - - category - properties: - name: - type: string - slug: - type: string - description: - type: string - type: - $ref: "#/components/schemas/VerificationType" - category: - type: string - - ControlPerformance: - type: object - required: - - mode - - evaluations - properties: - mode: - $ref: "#/components/schemas/VerificationMode" - f1: - type: number - pass_at_1: - type: number - evaluations: - type: array - items: - $ref: "#/components/schemas/EvaluationResult" - - ControlDetail: - type: object - required: - - description - - checks - - pass_example - - fail_example - properties: - description: - type: string - checks: - type: array - items: - type: string - pass_example: - type: string - fail_example: - type: string - - RecentControlResult: - type: object - required: - - run_id - - run_title - - workflow - - result - - timestamp - properties: - run_id: - type: string - run_title: - type: string - workflow: - type: string - result: - $ref: "#/components/schemas/VerificationStatus" - timestamp: - type: string - - SiblingControl: - type: object - required: - - name - - slug - properties: - name: - type: string - slug: - type: string - type: - $ref: "#/components/schemas/VerificationType" - mode: - $ref: "#/components/schemas/VerificationMode" - - VerificationDetailResponse: - 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 - items: - $ref: "#/components/schemas/RecentControlResult" - siblings: - type: array - items: - $ref: "#/components/schemas/SiblingControl" - - # ── Retro Schemas ─────────────────────────────────────────────────── - - SmoothnessRating: - type: string - enum: - - effortless - - smooth - - bumpy - - struggled - - failed - - RetroStats: - type: object - required: - - total_duration_ms - - total_retries - - files_touched - - stages_completed - - stages_failed - properties: - total_duration_ms: - type: integer - total_cost: - type: number - total_retries: - type: integer - files_touched: - type: array - items: - type: string - stages_completed: - type: integer - stages_failed: - type: integer - - RetroListItem: - type: object - required: - - run_id - - workflow_name - - goal - - timestamp - - stats - - friction_point_count - properties: - run_id: - type: string - workflow_name: - type: string - goal: - type: string - timestamp: - type: string - smoothness: - $ref: "#/components/schemas/SmoothnessRating" - stats: - $ref: "#/components/schemas/RetroStats" - friction_point_count: - type: integer - - # ── Session Schemas ───────────────────────────────────────────────── - - SessionListItem: - description: Summary of a session shown in list views. - type: object - required: - - id - - title - - created_at - - updated_at - properties: - id: - type: string - description: Unique session identifier. - example: s1 - title: - type: string - description: Short title summarizing the session topic. - example: Add rate limiting to auth endpoints - 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 - 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. - - ToolTurn: - description: A tool invocation turn. - type: object - required: - - kind - - tools - properties: - kind: - type: string - enum: [tool] - tools: - type: array - description: Tool invocations for this turn. - items: - $ref: "#/components/schemas/ToolUse" - - 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 - description: Unique session identifier. - example: s1 - title: - type: string - description: Short title summarizing the session topic. - example: Add rate limiting to auth endpoints - model: - type: string - description: The LLM model used for this session. - example: Opus 4.6 - 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: Opus 4.6 - - CreateSessionResponse: - description: Response returned after successfully creating a session. - type: object - required: - - id - - created_at - properties: - id: - type: string - description: Unique identifier for the newly created session. - example: s42 - created_at: - type: string - format: date-time - description: Timestamp when the session was created. - 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: - type: object - required: - - id - - name - - sql - properties: - id: - type: string - name: - type: string - sql: - type: string - - SaveQueryRequest: - type: object - required: - - name - - sql - properties: - name: - type: string - sql: - type: string - - ExecuteQueryRequest: - type: object - required: - - sql - properties: - sql: - type: string - - ExecuteQueryResponse: - type: object - required: - - columns - - rows - - elapsed - - row_count - properties: - columns: - type: array - items: - type: string - rows: - type: array - items: - type: array - items: {} - elapsed: - type: number - row_count: - type: integer - - HistoryEntry: - type: object - required: - - id - - sql - - timestamp - - elapsed - - row_count - properties: - id: - type: string - sql: - type: string - timestamp: - type: string - elapsed: - type: number - row_count: - type: integer - - # ── Settings Schemas ──────────────────────────────────────────────── - - SettingFieldType: - type: string - enum: - - text - - select - - toggle - - SettingField: - type: object - required: - - key - - label - - value - - type - properties: - key: - type: string - label: - type: string - value: - type: string - type: - $ref: "#/components/schemas/SettingFieldType" - options: - type: array - items: - type: string - description: - type: string - - SettingGroup: - type: object - required: - - id - - name - - description - - fields - properties: - id: - type: string - name: - type: string - description: - type: string - fields: - type: array - items: - $ref: "#/components/schemas/SettingField" - - # ── Project Schemas ───────────────────────────────────────────────── - - Project: - type: object - required: - - id - - name - properties: - id: - type: string - name: - type: string - - Branch: - type: object - required: - - id - - name - properties: - id: - type: string - name: - type: string - - # ── Discovery Schemas ────────────────────────────────────────────── - - RootResponseUrls: - type: object - required: - - openapi_url - - current_user_url - - health_url - properties: - openapi_url: - type: string - current_user_url: - type: string - health_url: - type: string - - RootResponse: - type: object - required: - - urls - properties: - urls: - $ref: "#/components/schemas/RootResponseUrls" - - HealthResponse: - type: object - required: - - status - properties: - status: - type: string - - UserResponse: - type: object - required: - - login - properties: - login: - type: string diff --git a/packages/arc-api-client/package.json b/packages/arc-api-client/package.json index db23746cc..45ab63882 100644 --- a/packages/arc-api-client/package.json +++ b/packages/arc-api-client/package.json @@ -4,7 +4,7 @@ "private": true, "type": "module", "scripts": { - "generate": "bunx @openapitools/openapi-generator-cli generate -i ../../openapi/arc-api.yaml -g typescript-axios --additional-properties=supportsES6=true,typescriptThreePlus=true,withSeparateModelsAndApi=true,apiPackage=api,modelPackage=models,useTags=true,enumPropertyNaming=UPPERCASE -o src && cp ../../openapi/arc-api.yaml ../../docs/api-reference/arc-api.yaml" + "generate": "bunx @openapitools/openapi-generator-cli generate -i ../../docs/api-reference/arc-api.yaml -g typescript-axios --additional-properties=supportsES6=true,typescriptThreePlus=true,withSeparateModelsAndApi=true,apiPackage=api,modelPackage=models,useTags=true,enumPropertyNaming=UPPERCASE -o src" }, "dependencies": { "axios": "^1.7.0"