Documentation Index Fetch the complete documentation index at: https://mintlify.com/coleam00/Archon/llms.txt
Use this file to discover all available pages before exploring further.
Archon exposes a REST API via a Hono server with full OpenAPI 3.0 spec generation. All endpoints are prefixed with /api/. This page documents every endpoint with method, path, parameters, request bodies, and response shapes.
Base URL http://localhost:3090/api/
Override the port with the PORT environment variable or let Archon auto-allocate when running inside a worktree (range 3190–4089).
Authentication None. Archon is a single-developer tool — there is no authentication on the API by default. If you expose Archon on a network, use a reverse proxy or firewall to restrict access. See deployment/docker for Caddy-based auth options.
OpenAPI specification A machine-readable OpenAPI 3.0 spec is available at GET /api/openapi.json. Feed it into Swagger UI or use it to generate typed API clients.
curl http://localhost:3090/api/openapi.json
Health Method Path Description GET /healthBasic liveness check GET /api/healthAPI-level health with adapter and concurrency info
curl http://localhost:3090/health # {"status":"ok"} curl http://localhost:3090/api/health # {"status":"ok","adapter":"...","concurrency":{"active":0,"queued":0,"max":10},"runningWorkflows":0}
Conversations Method Path Description GET /api/conversationsList conversations GET /api/conversations/{id}Get a single conversation POST /api/conversationsCreate a new conversation PATCH /api/conversations/{id}Update a conversation (rename) DELETE /api/conversations/{id}Soft-delete a conversation GET /api/conversations/{id}/messagesList messages in a conversation POST /api/conversations/{id}/messageSend a message to a conversation
List conversations curl http://localhost:3090/api/conversations
Query parameters: Parameter Type Description codebase_idstring Filter by codebase include_deletedboolean Include soft-deleted conversations
Create a conversation # Empty conversation curl -X POST http://localhost:3090/api/conversations \ -H "Content-Type: application/json" \ -d '{}' # Scoped to a codebase curl -X POST http://localhost:3090/api/conversations \ -H "Content-Type: application/json" \ -d '{"codebase_id": "your-codebase-id"}'
Returns the created conversation including its platform_conversation_id.
Send a message curl -X POST http://localhost:3090/api/conversations/{id}/message \ -H "Content-Type: application/json" \ -d '{"message": "What does this codebase do?"}'
The message is dispatched to the orchestrator asynchronously. AI responses arrive via SSE streaming (/api/stream/{conversationId}) or can be polled via the messages endpoint.
Get messages curl http://localhost:3090/api/conversations/{id}/messages
Query parameters: Parameter Type Description limitinteger Number of messages to return beforestring Cursor for pagination
Update a conversation curl -X PATCH http://localhost:3090/api/conversations/{id} \ -H "Content-Type: application/json" \ -d '{"title": "My feature discussion"}'
Delete a conversation curl -X DELETE http://localhost:3090/api/conversations/{id}
Performs a soft delete — the conversation is hidden but not destroyed. Pass include_deleted=true when listing to include it.
Codebases Method Path Description GET /api/codebasesList registered codebases POST /api/codebasesRegister a codebase (clone or local path) GET /api/codebases/{id}Get a single codebase DELETE /api/codebases/{id}Delete a codebase and clean up resources GET /api/codebases/{id}/envList env var keys for a codebase (never returns values) PUT /api/codebases/{id}/envUpsert a single codebase env var DELETE /api/codebases/{id}/env/{key}Delete a single codebase env var GET /api/codebases/{id}/environmentsList isolation environments for a codebase
Register a codebase Clone from a URL:
curl -X POST http://localhost:3090/api/codebases \ -H "Content-Type: application/json" \ -d '{"url": "https://github.com/user/repo"}'
Register a local path:
curl -X POST http://localhost:3090/api/codebases \ -H "Content-Type: application/json" \ -d '{"path": "/home/user/projects/my-repo"}'
Delete a codebase curl -X DELETE http://localhost:3090/api/codebases/{id}
Removes the codebase registration and cleans up associated worktrees and isolation environments.
Manage codebase env vars # List env var keys (values are never returned) curl http://localhost:3090/api/codebases/{id}/env # Upsert a key-value pair curl -X PUT http://localhost:3090/api/codebases/{id}/env \ -H "Content-Type: application/json" \ -d '{"key": "MY_API_KEY", "value": "secret-value"}' # Delete a key curl -X DELETE http://localhost:3090/api/codebases/{id}/env/MY_API_KEY
Per-project env vars are injected into Claude, Codex, bash/script nodes, and direct chat when the conversation is codebase-scoped.
List environments curl http://localhost:3090/api/codebases/{id}/environments
Returns the isolation environments (worktrees) associated with a codebase.
Workflows Workflow definitions Method Path Description GET /api/workflowsList available workflows GET /api/workflows/{name}Get a single workflow definition POST /api/workflows/validateValidate a workflow definition (in-memory, no save) PUT /api/workflows/{name}Save (create or update) a workflow DELETE /api/workflows/{name}Delete a user-defined workflow
List workflows curl http://localhost:3090/api/workflows # With project-specific discovery curl "http://localhost:3090/api/workflows?cwd=/path/to/repo"
Query parameters: Parameter Type Description cwdstring Working directory to discover project-specific workflows
Returns { workflows: [...], errors?: [...] }. When cwd is omitted, returns bundled defaults and home-scoped workflows only.
Get a workflow curl http://localhost:3090/api/workflows/archon-assist curl "http://localhost:3090/api/workflows/archon-assist?cwd=/path/to/repo"
Returns { workflow, filename, source: "project" | "global" | "bundled" }.
Validate a workflow curl -X POST http://localhost:3090/api/workflows/validate \ -H "Content-Type: application/json" \ -d '{ "definition": { "name": "my-wf", "description": "Test workflow", "nodes": [{"id": "a", "prompt": "hello"}] } }'
Returns { valid: true } or { valid: false, errors: ["..."] }. Does not save anything.
Save a workflow curl -X PUT http://localhost:3090/api/workflows/my-workflow \ -H "Content-Type: application/json" \ -d '{ "definition": { "name": "my-workflow", "description": "My custom workflow", "nodes": [{"id": "plan", "prompt": "Plan the feature: $ARGUMENTS"}] } }'
Query parameters: Parameter Type Description cwdstring Target directory (must have .archon/workflows/) sourceproject | globalScope to write to. project = <cwd>/.archon/workflows/ (default), global = ~/.archon/workflows/
Delete a workflow curl -X DELETE http://localhost:3090/api/workflows/my-workflow curl -X DELETE "http://localhost:3090/api/workflows/my-workflow?source=global"
Only user-defined workflows can be deleted. Bundled defaults cannot be removed.
Query parameters: Parameter Type Description cwdstring Target directory sourceproject | globalScope to delete from (default: project)
Workflow runs Method Path Description POST /api/workflows/{name}/runRun a workflow GET /api/workflows/runsList workflow runs GET /api/workflows/runs/{runId}Get run details with events GET /api/workflows/runs/by-worker/{platformId}Look up a run by worker conversation ID POST /api/workflows/runs/{runId}/cancelCancel a running workflow POST /api/workflows/runs/{runId}/resumeResume a failed workflow POST /api/workflows/runs/{runId}/abandonAbandon a non-terminal run POST /api/workflows/runs/{runId}/approveApprove a paused workflow POST /api/workflows/runs/{runId}/rejectReject a paused workflow DELETE /api/workflows/runs/{runId}Delete a terminal run and its events
Run a workflow curl -X POST http://localhost:3090/api/workflows/archon-assist/run \ -H "Content-Type: application/json" \ -d '{"message": "Explain the auth module", "conversationId": "conv-123"}'
Resume a failed run curl -X POST http://localhost:3090/api/workflows/runs/{runId}/resume
Resumes the workflow from where it left off, skipping already-completed nodes. Equivalent to archon workflow resume <run-id> from the CLI.
Approve or reject a paused run # Approve (optionally with a comment available as $LOOP_USER_INPUT) curl -X POST http://localhost:3090/api/workflows/runs/{runId}/approve \ -H "Content-Type: application/json" \ -d '{"comment": "Looks good, proceed"}' # Reject (optionally with a reason available as $REJECTION_REASON) curl -X POST http://localhost:3090/api/workflows/runs/{runId}/reject \ -H "Content-Type: application/json" \ -d '{"reason": "Please add error handling first"}'
Delete a terminal run curl -X DELETE http://localhost:3090/api/workflows/runs/{runId}
Only terminal runs (completed, failed, cancelled) can be deleted.
Artifacts Method Path Description GET /api/artifacts/{runId}/*Serve a workflow artifact file by run ID and relative path
# Fetch a specific artifact file curl http://localhost:3090/api/artifacts/{runId}/report.md
Returns text/markdown for .md files, text/plain otherwise. Returns 400 on path traversal attempts (..), 404 if the run or file is not found.
Commands Method Path Description GET /api/commandsList available command names
curl http://localhost:3090/api/commands # With project-specific discovery curl "http://localhost:3090/api/commands?cwd=/path/to/repo"
Query parameters: Parameter Type Description cwdstring Working directory for project-specific commands
Returns { commands: [{ name, source: "bundled" | "project" }] }.
Providers Method Path Description GET /api/providersList registered AI providers
curl http://localhost:3090/api/providers
Returns { providers: [{ id, displayName, capabilities, builtIn }] }.
Configuration Method Path Description GET /api/configGet read-only configuration (safe subset) PATCH /api/config/assistantsUpdate assistant configuration
# Read current config curl http://localhost:3090/api/config # Update assistant defaults curl -X PATCH http://localhost:3090/api/config/assistants \ -H "Content-Type: application/json" \ -d '{"claude": {"model": "opus"}}'
Dashboard Method Path Description GET /api/dashboard/runsList enriched workflow runs for the Command Center
Supports status filters, date ranges, and pagination. Used by the Command Center UI.
System Method Path Description GET /api/update-checkCheck for available updates GET /api/openapi.jsonGenerated OpenAPI 3.0 specification
curl http://localhost:3090/api/update-check
Returns { updateAvailable, currentVersion, latestVersion, releaseUrl }. For non-binary (source) builds, always returns updateAvailable: false without making external requests.
SSE streaming Path Description /api/stream/{conversationId}Real-time events for a single conversation /api/stream/__dashboard__Multiplexed workflow events across all conversations
These are Server-Sent Events (SSE) endpoints — connect with EventSource in a browser or any SSE client.
# Listen to a conversation stream curl -N http://localhost:3090/api/stream/your-conversation-id
Events are JSON-encoded with a type field. See adapters/web for the full list of event types.
Common patterns Create a conversation and send a message # 1. Create a conversation CONV_ID = $( curl -s -X POST http://localhost:3090/api/conversations \ -H "Content-Type: application/json" \ -d '{}' | jq -r '.platform_conversation_id' ) # 2. Send a message curl -X POST "http://localhost:3090/api/conversations/ $CONV_ID /message" \ -H "Content-Type: application/json" \ -d '{"message": "/status"}' # 3. Poll for messages curl "http://localhost:3090/api/conversations/ $CONV_ID /messages"
Run a workflow via the API # 1. Create a conversation scoped to a codebase CONV_ID = $( curl -s -X POST http://localhost:3090/api/conversations \ -H "Content-Type: application/json" \ -d '{"codebase_id": "your-codebase-id"}' | jq -r '.platform_conversation_id' ) # 2. Start the workflow curl -X POST http://localhost:3090/api/workflows/archon-assist/run \ -H "Content-Type: application/json" \ -d "{ \" message \" : \" How does auth work? \" , \" conversationId \" : \" $CONV_ID \" }" # 3. Monitor via SSE curl -N "http://localhost:3090/api/stream/ $CONV_ID "
Validate and save a workflow # 1. Validate first RESULT = $( curl -s -X POST http://localhost:3090/api/workflows/validate \ -H "Content-Type: application/json" \ -d '{"definition": {"name":"my-wf","description":"Test","nodes":[{"id":"a","prompt":"hello"}]}}' ) echo $RESULT | jq '.valid' # true # 2. Save if valid curl -X PUT http://localhost:3090/api/workflows/my-wf \ -H "Content-Type: application/json" \ -d '{"definition": {"name":"my-wf","description":"Test","nodes":[{"id":"a","prompt":"hello"}]}}'
Architecture How the server, adapters, and workflow engine fit together.
CLI Reference CLI equivalents for most API operations.
Web Adapter SSE event types and Web UI integration details.
Configuration PORT and other server configuration options.
