API Reference The Optio API is a REST API served by Fastify. All endpoints are prefixed with /api and return JSON. Request bodies use JSON with Zod schema validation.
Info
All endpoints except /api/health, /api/auth/*, and /api/setup/* require authentication via the optio_session cookie or a ?token= query parameter.
Health Method Endpoint Description GET /api/health Health check endpoint (no auth required)
Tasks Tasks are the core resource. The /api/tasks endpoint is polymorphic over three kinds, distinguished by a type field:
repo-task — an ad-hoc Repo Task (agent clones repo, opens PR).repo-blueprint — a scheduled Repo Task config; triggers spawn fresh runs.standalone — a Standalone Task (agent runs with no repo).Method Endpoint Description GET /api/tasks?type=... List tasks (type=repo-task|repo-blueprint|standalone|all; default repo-task) POST /api/tasks Create a task (body.type discriminates the kind) GET /api/tasks/:id Get any task by id; response includes a type discriminator PATCH /api/tasks/:id Update a task DELETE /api/tasks/:id Delete a task GET /api/tasks/:id/runs List runs under a blueprint or standalone Task POST /api/tasks/:id/runs Kick off a run (for blueprints/standalone) GET /api/tasks/:id/runs/:runId Get a single run GET /api/tasks/:id/triggers List triggers on a blueprint or standalone Task POST /api/tasks/:id/triggers Attach a trigger (schedule/webhook/ticket/manual) PATCH /api/tasks/:id/triggers/:triggerId Update a trigger DELETE /api/tasks/:id/triggers/:triggerId Delete a trigger POST /api/tasks/:id/cancel Cancel a running or queued task POST /api/tasks/:id/retry Retry a failed task POST /api/tasks/:id/resume Resume a needs_attention or failed task with new context POST /api/tasks/:id/force-restart Fresh agent session on existing PR branch POST /api/tasks/:id/force-redo Clear everything and re-run from scratch POST /api/tasks/:id/review Manually launch a code review agent POST /api/tasks/reorder Reorder task priorities by position
Create Task Example POST /api/tasks
{
"title": "Add user avatar support",
"prompt": "Add avatar upload and display to user profiles",
"repoUrl": "https://github.com/acme/webapp",
"repoBranch": "main",
"agentType": "claude",
"priority": 0
}Copy Bulk Operations Method Endpoint Description POST /api/tasks/bulk/retry-failed Retry all failed tasks POST /api/tasks/bulk/cancel-active Cancel all running and queued tasks
Subtasks Tasks can have child tasks. Three subtask types are supported: child (independent), step (sequential pipeline), and review (code review).
Method Endpoint Description GET /api/tasks/:id/subtasks List subtasks of a task POST /api/tasks/:id/subtasks Create a subtask (child, step, or review) GET /api/tasks/:id/subtasks/status Get subtask completion status
Task Comments Method Endpoint Description GET /api/tasks/:id/comments List comments on a task POST /api/tasks/:id/comments Add a comment to a task
Task Dependencies Method Endpoint Description GET /api/tasks/:id/dependencies List task dependencies POST /api/tasks/:id/dependencies Add a dependency (task must complete before this task starts) DELETE /api/tasks/:id/dependencies/:depId Remove a dependency
Repositories Manage connected repositories and their per-repo settings.
Method Endpoint Description GET /api/repos List connected repositories POST /api/repos Connect a new repository GET /api/repos/:id Get repository details and settings PATCH /api/repos/:id Update repository settings DELETE /api/repos/:id Disconnect a repository
Issues Browse and assign GitHub Issues from connected repositories.
Method Endpoint Description GET /api/issues List GitHub Issues across all connected repos POST /api/issues/assign Assign a GitHub Issue to Optio (creates a task)
Tickets Manage external ticket provider integrations (GitHub Issues, GitLab Issues, Linear, Jira, Notion).
Method Endpoint Description GET /api/tickets/providers List configured ticket providers POST /api/tickets/providers Add a ticket provider PATCH /api/tickets/providers/:id Update a ticket provider DELETE /api/tickets/providers/:id Remove a ticket provider POST /api/tickets/sync Trigger a manual ticket sync
Interactive Sessions Sessions provide persistent, interactive workspaces connected to repo pods with terminal and agent chat.
Method Endpoint Description GET /api/sessions List sessions (filterable by state, repo) POST /api/sessions Create an interactive session GET /api/sessions/:id Get session details POST /api/sessions/:id/end End a session and clean up worktree
Sessions also expose WebSocket endpoints:
WS /ws/sessions/:id/terminal — xterm.js interactive terminalWS /ws/sessions/:id/chat — interactive Claude Code chatSecrets Method Endpoint Description GET /api/secrets List secrets (names and scopes only, never values) POST /api/secrets Create or update a secret DELETE /api/secrets/:name Delete a secret
Warning
Secret values are never returned by the API. Only names and scopes are exposed. Secrets are encrypted at rest with AES-256-GCM.
Authentication Method Endpoint Description GET /api/auth/providers List enabled OAuth providers (no auth required) GET /api/auth/:provider/login Initiate OAuth flow (redirects to provider) GET /api/auth/:provider/callback OAuth callback (sets session cookie) GET /api/auth/me Get current user profile POST /api/auth/logout Revoke session and clear cookie GET /api/auth/status Claude subscription status GET /api/auth/usage Claude Max/Pro usage metrics
Workspaces Multi-tenancy via workspaces. Resources are scoped to the active workspace.
Method Endpoint Description GET /api/workspaces List workspaces for the current user POST /api/workspaces Create a new workspace PATCH /api/workspaces/:id Update workspace settings GET /api/workspaces/:id/members List workspace members POST /api/workspaces/:id/members Invite a member to the workspace
Prompt Templates Method Endpoint Description GET /api/prompt-templates List prompt templates POST /api/prompt-templates Create a prompt template PATCH /api/prompt-templates/:id Update a prompt template DELETE /api/prompt-templates/:id Delete a prompt template
Task Templates Method Endpoint Description GET /api/task-templates List task templates POST /api/task-templates Create a task template PATCH /api/task-templates/:id Update a task template DELETE /api/task-templates/:id Delete a task template
Analytics Method Endpoint Description GET /api/analytics/costs Cost analytics with daily, per-repo, and per-type breakdowns
Query Parameters Param Default Description days 30 Number of days to aggregate repoUrl all Filter by repository URL
Response Shape GET /api/analytics/costs?days=30
{
"summary": {
"totalCost": "12.45",
"taskCount": 38,
"averageCost": "0.33",
"costTrend": 15.2
},
"dailyCosts": [
{ "date": "2025-01-15", "cost": "1.20", "taskCount": 4 }
],
"costByRepo": [
{ "repoUrl": "https://github.com/acme/webapp", "cost": "8.30" }
],
"costByType": [
{ "taskType": "coding", "cost": "10.15" },
{ "taskType": "review", "cost": "2.30" }
],
"topTasks": [
{ "id": "abc123", "title": "Refactor auth", "costUsd": "1.85" }
]
}Copy Webhooks Method Endpoint Description GET /api/webhooks List configured webhooks POST /api/webhooks Create a webhook endpoint PATCH /api/webhooks/:id Update a webhook DELETE /api/webhooks/:id Delete a webhook
Legacy Aliases The following endpoints are retained for backward compatibility. New integrations should use the unified /api/tasks surface documented above.
Method Endpoint Description GET /api/jobs/* Standalone Task alias (use /api/tasks?type=standalone) GET /api/task-configs/* Repo Task blueprint alias (use /api/tasks?type=repo-blueprint)
Cluster Method Endpoint Description GET /api/cluster/nodes List cluster nodes with resource usage GET /api/cluster/pods List Optio-managed pods GET /api/cluster/pods/:name/logs Get pod logs
Slack Method Endpoint Description POST /api/slack/test Send a test Slack notification
MCP Servers Method Endpoint Description GET /api/mcp-servers List MCP server configurations POST /api/mcp-servers Add an MCP server (global or per-repo) PATCH /api/mcp-servers/:id Update an MCP server config DELETE /api/mcp-servers/:id Remove an MCP server
Skills Method Endpoint Description GET /api/skills List custom agent skills POST /api/skills Create a custom skill PATCH /api/skills/:id Update a skill DELETE /api/skills/:id Delete a skill
Setup Method Endpoint Description GET /api/setup/status Check if initial setup is complete POST /api/setup/complete Complete the initial setup wizard
WebSocket Endpoints Real-time communication uses WebSocket connections authenticated via ?token= query parameter.
Endpoint Description /ws/logs/:taskId Stream real-time structured logs for a task /ws/events Global event stream (task state changes, new tasks, etc.) /ws/sessions/:id/terminal Interactive terminal for a session (xterm.js) /ws/sessions/:id/chat Interactive Claude Code chat for a session