From 802727ac07ef18d9d44640a86512dc59bcac48dc Mon Sep 17 00:00:00 2001 From: Bryan Helmkamp Date: Mon, 2 Mar 2026 11:01:38 -0500 Subject: [PATCH] docs --- docs/api-reference/arc-api.yaml | 1786 +++++++++++++++++++++++ docs/api-reference/endpoint/create.mdx | 4 - docs/api-reference/endpoint/delete.mdx | 4 - docs/api-reference/endpoint/get.mdx | 4 - docs/api-reference/endpoint/webhook.mdx | 4 - docs/api-reference/introduction.mdx | 33 - docs/api-reference/openapi.json | 217 --- docs/docs.json | 20 +- 8 files changed, 1788 insertions(+), 284 deletions(-) create mode 100644 docs/api-reference/arc-api.yaml delete mode 100644 docs/api-reference/endpoint/create.mdx delete mode 100644 docs/api-reference/endpoint/delete.mdx delete mode 100644 docs/api-reference/endpoint/get.mdx delete mode 100644 docs/api-reference/endpoint/webhook.mdx delete mode 100644 docs/api-reference/introduction.mdx delete mode 100644 docs/api-reference/openapi.json diff --git a/docs/api-reference/arc-api.yaml b/docs/api-reference/arc-api.yaml new file mode 100644 index 000000000..3fc3224df --- /dev/null +++ b/docs/api-reference/arc-api.yaml @@ -0,0 +1,1786 @@ +openapi: "3.1.0" +info: + title: Arc Run API + version: "0.1.0" + description: HTTP API for managing Arc workflow run executions. + +tags: + - name: Runs + description: Run management operations + - name: Workflows + description: Workflow definitions and execution + - name: Verifications + description: Verification categories and controls + - name: Retros + description: Run retrospectives + - name: Sessions + description: Interactive chat sessions + - name: Insights + description: SQL query editor and history + - name: Settings + description: Platform configuration + - name: Projects + description: Project and branch management + +paths: + # ── Runs ────────────────────────────────────────────────────────────── + + /runs: + get: + operationId: listRuns + tags: [Runs] + summary: List all runs (board view) + responses: + "200": + description: Array of runs for the board view + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/RunListItem" + post: + operationId: startRun + tags: [Runs] + summary: Start a new 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: getRunStatus + tags: [Runs] + summary: Get run status + parameters: + - $ref: "#/components/parameters/RunId" + responses: + "200": + description: Run status + content: + application/json: + schema: + $ref: "#/components/schemas/RunStatusResponse" + "404": + description: Run not found + + /runs/{id}/cancel: + post: + operationId: cancelRun + tags: [Runs] + summary: Cancel a running 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 + "409": + description: Run is not running + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + + /runs/{id}/graph: + get: + operationId: getGraph + tags: [Runs] + summary: Get run graph as 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 + "502": + description: Graphviz not available + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + + /runs/{id}/checkpoint: + get: + operationId: getCheckpoint + tags: [Runs] + summary: Get 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 + + /runs/{id}/context: + get: + operationId: getContext + tags: [Runs] + summary: Get 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 + + /runs/{id}/events: + get: + operationId: getEvents + tags: [Runs] + summary: Subscribe to run events via SSE + parameters: + - $ref: "#/components/parameters/RunId" + responses: + "200": + description: Server-sent event stream + content: + text/event-stream: + schema: + type: string + "404": + description: Run not found + "410": + description: Event stream closed + + /runs/{id}/questions: + get: + operationId: getQuestions + tags: [Runs] + summary: Get pending questions for a run + parameters: + - $ref: "#/components/parameters/RunId" + responses: + "200": + description: Array of pending questions + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ApiQuestion" + "404": + description: Run not found + + /runs/{id}/questions/{qid}/answer: + post: + operationId: submitAnswer + tags: [Runs] + summary: Submit an answer to a question + 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 + + /runs/{id}/retro: + get: + operationId: getRetro + tags: [Runs] + summary: Get run retrospective + parameters: + - $ref: "#/components/parameters/RunId" + responses: + "200": + description: Retro data (null if not yet available) + content: + application/json: + schema: {} + "404": + description: Run not found + + /runs/{id}/stages: + get: + operationId: getRunStages + tags: [Runs] + summary: List stages with status and duration + parameters: + - $ref: "#/components/parameters/RunId" + responses: + "200": + description: Array of run stages + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/RunStage" + "404": + description: Run not found + + /runs/{id}/stages/{stageId}/turns: + get: + operationId: getStageTurns + tags: [Runs] + summary: Conversation transcript for a stage + parameters: + - $ref: "#/components/parameters/RunId" + - name: stageId + in: path + required: true + schema: + type: string + responses: + "200": + description: Array of conversation turns + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/StageTurn" + "404": + description: Run or stage not found + + /runs/{id}/files: + get: + operationId: getRunFiles + tags: [Runs] + summary: File diffs grouped by checkpoint + 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/RunFiles" + "404": + description: Run not found + + /runs/{id}/usage: + get: + operationId: getRunUsage + tags: [Runs] + summary: Token and cost breakdown by stage and model + parameters: + - $ref: "#/components/parameters/RunId" + responses: + "200": + description: Usage data + content: + application/json: + schema: + $ref: "#/components/schemas/RunUsage" + "404": + description: Run not found + + /runs/{id}/verifications: + get: + operationId: getRunVerifications + tags: [Runs] + summary: Verification results for this run + parameters: + - $ref: "#/components/parameters/RunId" + responses: + "200": + description: Array of verification categories with controls + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/RunVerification" + "404": + description: Run not found + + /runs/{id}/configuration: + get: + operationId: getRunConfiguration + tags: [Runs] + summary: Run configuration (TOML) + parameters: + - $ref: "#/components/parameters/RunId" + responses: + "200": + description: Configuration content + content: + text/plain: + schema: + type: string + "404": + description: Run not found + + /runs/{id}/steer: + post: + operationId: steerRun + tags: [Runs] + summary: Submit steering guidance on a file line + 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 + + # ── Workflows ───────────────────────────────────────────────────────── + + /workflows: + get: + operationId: listWorkflows + tags: [Workflows] + summary: List all workflows + responses: + "200": + description: Array of workflows + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/WorkflowListItem" + + /workflows/{name}: + get: + operationId: getWorkflow + tags: [Workflows] + summary: Get workflow detail with config and graph + 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 + + /workflows/{name}/runs: + get: + operationId: listWorkflowRuns + tags: [Workflows] + summary: List runs for this workflow + parameters: + - name: name + in: path + required: true + schema: + type: string + responses: + "200": + description: Array of runs + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/RunListItem" + "404": + description: Workflow not found + post: + operationId: triggerWorkflowRun + tags: [Workflows] + summary: Trigger a run for this workflow + 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 + + # ── Verifications ───────────────────────────────────────────────────── + + /verifications: + get: + operationId: listVerifications + tags: [Verifications] + summary: List all verification categories with controls + responses: + "200": + description: Array of verification categories + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/VerificationCategory" + + /verifications/{slug}: + get: + operationId: getVerificationDetail + tags: [Verifications] + summary: Control detail with performance and recent results + 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 + + # ── Retros ──────────────────────────────────────────────────────────── + + /retros: + get: + operationId: listRetros + tags: [Retros] + summary: List all retros across runs + responses: + "200": + description: Array of retros + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/RetroListItem" + + # ── Sessions ────────────────────────────────────────────────────────── + + /sessions: + get: + operationId: listSessions + tags: [Sessions] + summary: List sessions grouped by recency + responses: + "200": + description: Array of session groups + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/SessionGroup" + post: + operationId: createSession + tags: [Sessions] + summary: Create a new session + 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: getSession + tags: [Sessions] + summary: Session detail with full turn history + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + "200": + description: Session detail + content: + application/json: + schema: + $ref: "#/components/schemas/SessionDetail" + "404": + description: Session not found + + /sessions/{id}/messages: + post: + operationId: sendMessage + tags: [Sessions] + summary: Send a user message + parameters: + - name: id + in: path + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/SendMessageRequest" + responses: + "200": + description: Message accepted + content: + application/json: + schema: + type: object + properties: + accepted: + type: boolean + required: + - accepted + "404": + description: Session not found + + /sessions/{id}/events: + get: + operationId: getSessionEvents + tags: [Sessions] + summary: SSE stream for live assistant responses + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + "200": + description: Server-sent event stream + content: + text/event-stream: + schema: + type: string + "404": + description: Session not found + + # ── Insights ────────────────────────────────────────────────────────── + + /insights/queries: + get: + operationId: listSavedQueries + tags: [Insights] + summary: List saved queries + responses: + "200": + description: Array of saved queries + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/SavedQuery" + post: + operationId: saveQuery + tags: [Insights] + summary: Save a 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 a 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 + delete: + operationId: deleteSavedQuery + tags: [Insights] + summary: Delete a saved query + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + "204": + description: Query deleted + "404": + description: Query not found + + /insights/execute: + post: + operationId: executeQuery + tags: [Insights] + summary: Execute a SQL 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: Query execution history + responses: + "200": + description: Array of history entries + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/HistoryEntry" + + # ── Settings ────────────────────────────────────────────────────────── + + /settings: + get: + operationId: getSettings + tags: [Settings] + summary: Get all setting groups with current values + 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 available projects + responses: + "200": + description: Array of projects + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Project" + + /projects/{id}/branches: + get: + operationId: listBranches + tags: [Projects] + summary: List branches for a project + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + "200": + description: Array of branches + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Branch" + "404": + description: Project not found + +components: + parameters: + RunId: + name: id + in: path + required: true + schema: + type: string + + schemas: + # ── Existing Run Schemas ──────────────────────────────────────────── + + RunStatus: + type: string + enum: + - 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 + + 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: + type: string + options: + type: array + items: + $ref: "#/components/schemas/ApiQuestionOption" + allow_freeform: + type: boolean + + SubmitAnswerRequest: + type: object + required: + - value + properties: + value: + type: string + selected_option_key: + type: string + + SubmitAnswerResponse: + type: object + required: + - accepted + properties: + accepted: + type: boolean + + ErrorResponse: + type: object + required: + - error + properties: + error: + type: string + + # ── 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: + type: object + required: + - tool_name + - args + - result + properties: + tool_name: + type: string + args: + type: string + result: + type: string + + 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 + + RunFiles: + 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" + + 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 + + # ── 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: + type: object + required: + - id + - title + - repo + - time + properties: + id: + type: string + title: + type: string + repo: + type: string + time: + type: string + + SessionGroup: + type: object + required: + - label + - sessions + properties: + label: + type: string + sessions: + type: array + items: + $ref: "#/components/schemas/SessionListItem" + + SessionTurn: + type: object + required: + - kind + properties: + kind: + type: string + enum: + - user + - assistant + - tool + content: + type: string + date: + type: string + tools: + type: array + items: + $ref: "#/components/schemas/ToolUse" + + SessionDetail: + type: object + required: + - id + - title + - repo + - model + - turns + properties: + id: + type: string + title: + type: string + repo: + type: string + model: + type: string + turns: + type: array + items: + $ref: "#/components/schemas/SessionTurn" + + CreateSessionRequest: + type: object + required: + - project + - branch + - prompt + properties: + project: + type: string + branch: + type: string + prompt: + type: string + + CreateSessionResponse: + type: object + required: + - id + properties: + id: + type: string + + SendMessageRequest: + type: object + required: + - content + properties: + content: + type: string + + # ── 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 diff --git a/docs/api-reference/endpoint/create.mdx b/docs/api-reference/endpoint/create.mdx deleted file mode 100644 index 5689f1b65..000000000 --- a/docs/api-reference/endpoint/create.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Create Plant' -openapi: 'POST /plants' ---- diff --git a/docs/api-reference/endpoint/delete.mdx b/docs/api-reference/endpoint/delete.mdx deleted file mode 100644 index 657dfc871..000000000 --- a/docs/api-reference/endpoint/delete.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Delete Plant' -openapi: 'DELETE /plants/{id}' ---- diff --git a/docs/api-reference/endpoint/get.mdx b/docs/api-reference/endpoint/get.mdx deleted file mode 100644 index 56aa09ec1..000000000 --- a/docs/api-reference/endpoint/get.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Get Plants' -openapi: 'GET /plants' ---- diff --git a/docs/api-reference/endpoint/webhook.mdx b/docs/api-reference/endpoint/webhook.mdx deleted file mode 100644 index 329134020..000000000 --- a/docs/api-reference/endpoint/webhook.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'New Plant' -openapi: 'WEBHOOK /plant/webhook' ---- diff --git a/docs/api-reference/introduction.mdx b/docs/api-reference/introduction.mdx deleted file mode 100644 index c835b78b5..000000000 --- a/docs/api-reference/introduction.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: 'Introduction' -description: 'Example section for showcasing API endpoints' ---- - - - If you're not looking to build API reference documentation, you can delete - this section by removing the api-reference folder. - - -## Welcome - -There are two ways to build API documentation: [OpenAPI](https://mintlify.com/docs/api-playground/openapi/setup) and [MDX components](https://mintlify.com/docs/api-playground/mdx/configuration). For the starter kit, we are using the following OpenAPI specification. - - - View the OpenAPI specification file - - -## Authentication - -All API endpoints are authenticated using Bearer tokens and picked up from the specification file. - -```json -"security": [ - { - "bearerAuth": [] - } -] -``` diff --git a/docs/api-reference/openapi.json b/docs/api-reference/openapi.json deleted file mode 100644 index da5326efc..000000000 --- a/docs/api-reference/openapi.json +++ /dev/null @@ -1,217 +0,0 @@ -{ - "openapi": "3.1.0", - "info": { - "title": "OpenAPI Plant Store", - "description": "A sample API that uses a plant store as an example to demonstrate features in the OpenAPI specification", - "license": { - "name": "MIT" - }, - "version": "1.0.0" - }, - "servers": [ - { - "url": "http://sandbox.mintlify.com" - } - ], - "security": [ - { - "bearerAuth": [] - } - ], - "paths": { - "/plants": { - "get": { - "description": "Returns all plants from the system that the user has access to", - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "The maximum number of results to return", - "schema": { - "type": "integer", - "format": "int32" - } - } - ], - "responses": { - "200": { - "description": "Plant response", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Plant" - } - } - } - } - }, - "400": { - "description": "Unexpected error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - }, - "post": { - "description": "Creates a new plant in the store", - "requestBody": { - "description": "Plant to add to the store", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NewPlant" - } - } - }, - "required": true - }, - "responses": { - "200": { - "description": "plant response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Plant" - } - } - } - }, - "400": { - "description": "unexpected error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/plants/{id}": { - "delete": { - "description": "Deletes a single plant based on the ID supplied", - "parameters": [ - { - "name": "id", - "in": "path", - "description": "ID of plant to delete", - "required": true, - "schema": { - "type": "integer", - "format": "int64" - } - } - ], - "responses": { - "204": { - "description": "Plant deleted", - "content": {} - }, - "400": { - "description": "unexpected error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - } - }, - "webhooks": { - "/plant/webhook": { - "post": { - "description": "Information about a new plant added to the store", - "requestBody": { - "description": "Plant added to the store", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NewPlant" - } - } - } - }, - "responses": { - "200": { - "description": "Return a 200 status to indicate that the data was received successfully" - } - } - } - } - }, - "components": { - "schemas": { - "Plant": { - "required": [ - "name" - ], - "type": "object", - "properties": { - "name": { - "description": "The name of the plant", - "type": "string" - }, - "tag": { - "description": "Tag to specify the type", - "type": "string" - } - } - }, - "NewPlant": { - "allOf": [ - { - "$ref": "#/components/schemas/Plant" - }, - { - "required": [ - "id" - ], - "type": "object", - "properties": { - "id": { - "description": "Identification number of the plant", - "type": "integer", - "format": "int64" - } - } - } - ] - }, - "Error": { - "required": [ - "error", - "message" - ], - "type": "object", - "properties": { - "error": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - }, - "securitySchemes": { - "bearerAuth": { - "type": "http", - "scheme": "bearer" - } - } - } -} \ No newline at end of file diff --git a/docs/docs.json b/docs/docs.json index 46b44cc4a..20ce9e0d7 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -48,24 +48,8 @@ ] }, { - "tab": "API reference", - "groups": [ - { - "group": "API documentation", - "pages": [ - "api-reference/introduction" - ] - }, - { - "group": "Endpoint examples", - "pages": [ - "api-reference/endpoint/get", - "api-reference/endpoint/create", - "api-reference/endpoint/delete", - "api-reference/endpoint/webhook" - ] - } - ] + "tab": "API Reference", + "openapi": "api-reference/arc-api.yaml" } ], "global": {