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. Each task represents an agent run against a repository.

Method	Endpoint	Description
GET	/api/tasks	List tasks (filterable by state, repo, type)
POST	/api/tasks	Create a new task
GET	/api/tasks/:id	Get task details
PATCH	/api/tasks/:id	Update a task
DELETE	/api/tasks/:id	Delete a task
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
}

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, Linear).

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 terminal
WS /ws/sessions/:id/chat — interactive Claude Code chat

Secrets

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" }
  ]
}

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

Schedules

Method	Endpoint	Description
GET	/api/schedules	List scheduled/recurring tasks
POST	/api/schedules	Create a schedule
PATCH	/api/schedules/:id	Update a schedule
DELETE	/api/schedules/:id	Delete a schedule

Workflows

Multi-step workflow automation with templates and run tracking.

Method	Endpoint	Description
GET	/api/workflows	List workflow templates
POST	/api/workflows	Create a workflow template
POST	/api/workflows/:id/run	Execute a workflow
GET	/api/workflows/:id/runs	List runs for a workflow

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