API Reference

This page lists common backend interfaces. The repository’s generated route catalog links mounted routes to source; CI checks generator freshness, not runtime completeness. The repository API guide contains additional endpoints and details. There is no bundled Swagger UI.

Authentication

Browser login sets an HttpOnly cookie. For scripts, use a personal access token as Authorization: Bearer <token>. /api/auth/login-mobile returns a session token and expiresAt; /api/auth/login does not return the token in JSON. MASTER_KEY is not an API credential. Health and designated auth routes are public; SSO and webhook endpoints have their own authentication contracts.

Health

Method	Endpoint	Auth	Description
GET	/api/health	No	Basic health check
GET	/api/health/detailed	No	Service status with latencies
GET	/api/health/ready	No	Readiness probe
GET	/api/health/live	No	Liveness probe
GET	/api/health/storage	No	Storage provider (cache/queue/pub-sub) health

Authentication

Method	Endpoint	Auth	Description
POST	/api/auth/register	No	Register new user
POST	/api/auth/login	No	Login with credentials (+ optional TOTP)
POST	/api/auth/login-mobile	No	Login returning bearer token in response body (for native clients)
POST	/api/auth/logout	Yes	Logout and invalidate session
GET	/api/auth/me	Yes	Get current user info
GET	/api/auth/ws-ticket	Yes	Get short-lived token for WebSocket authentication
POST	/api/auth/passkey/register/options	Yes	Generate WebAuthn registration options
POST	/api/auth/passkey/register/verify	Yes	Verify WebAuthn registration response
POST	/api/auth/passkey/auth/options	No	Generate WebAuthn authentication options
POST	/api/auth/passkey/auth/verify	No	Verify WebAuthn authentication response
POST	/api/auth/totp/setup	Yes	Setup TOTP 2FA
POST	/api/auth/totp/enable	Yes	Enable TOTP after verification
POST	/api/auth/totp/disable	Yes	Disable TOTP 2FA
POST	/api/auth/link	Yes	Redeem channel link code

Agents

Method	Endpoint	Description
GET	/api/agents	List all agents
POST	/api/agents	Spawn new agent
GET	/api/agents/:id	Get agent details
DELETE	/api/agents/:id	Stop and remove agent
POST	/api/agents/:id/message	Send message to agent
GET	/api/agents/:id/events	Get agent events (cursor-based: ?after=<seq>)

Sessions

Method	Endpoint	Description
GET	/api/sessions	List sessions
GET	/api/sessions/:id	Get session details
GET	/api/sessions/:id/messages	Get session messages

Models

Method	Endpoint	Description
GET	/api/models	List all models
POST	/api/models	Register new model
GET	/api/models/:name	Get model details
PATCH	/api/models/:name	Update model config
DELETE	/api/models/:name	Delete model
POST	/api/models/:name/default	Set as default model
GET	/api/topics	Get topic bindings and configuration
GET	/api/models/health	Check provider health
GET	/api/models/cli/status	CLI tool availability
GET	/api/models/cli/quota	CLI quota status
GET	/api/models/providers/ollama/models	List available Ollama models
GET	/api/models/providers/litellm/models	List LiteLLM models
GET	/api/models/providers/:provider/known	Known models for a provider

Topics

Method	Endpoint	Description
GET	/api/topics	List all topics with current model bindings and config
PATCH	/api/topics/:topic/config	Update topic config (executorModel, temperature, maxTokens) (admin)
PUT	/api/topics/:topic/binding	Set topic’s primary/backup model binding (admin)
POST	/api/topics/assign-all	Bind one model as primary for all text topics (admin)

Tools

Method	Endpoint	Description
GET	/api/tools	List registered tools
GET	/api/tools/:id	Get tool details
GET	/api/tools/all	All built-in and expanded MCP tool definitions
GET	/api/tools/permissions	User permission overrides
PUT	/api/tools/permissions	Set an override, optionally scoped with expiry
DELETE	/api/tools/permissions/:toolId/:action	Reset permission
POST	/api/tools/:toolId/tools/:toolName/execute	Execute a tool function

Chat

Method	Endpoint	Description
POST	/api/chat	Send a chat message (optional expertId for expert routing)
POST	/api/chat/approve	Respond to an approval request

Documents

Method	Endpoint	Description
POST	/api/documents/upload	Upload one or more documents
GET	/api/documents	List documents (with optional filtering by category/status)
GET	/api/documents/:id	Get document details
GET	/api/documents/:id/raw	Stream original file (with ?download=1 for attachment mode)
DELETE	/api/documents/:id	Delete document
POST	/api/documents/:id/cancel	Cancel document processing

Reader

Method	Endpoint	Description
POST	/api/reader	Fetch and extract article/page content

Research

Method	Endpoint	Description
POST	/api/research	Start a deep research job
GET	/api/research/:jobId	Get persisted research job status and results

Tasks

Method	Endpoint	Description
GET	/api/tasks	List user’s tasks (?status=, ?due=today, ?category=, ?view=next for next-action order with a bucket and reason each)
GET	/api/tasks/:id	Get one task
POST	/api/tasks	Create a task (parentId, blockedBy[], estimate optional)
PATCH	/api/tasks/:id	Update task; status is open / in_progress / done / archived; parentId: null and blockedBy: [] clear the links
DELETE	/api/tasks/:id	Delete task (its sub-tasks become top-level)

Hooks

Method	Endpoint	Description
GET	/api/hooks	List all hooks
POST	/api/hooks	Create hook
GET	/api/hooks/:id	Get hook details
PATCH	/api/hooks/:id	Update hook
DELETE	/api/hooks/:id	Delete hook
POST	/api/hooks/:id/toggle	Toggle hook enabled state

API Tokens

Method	Endpoint	Description
GET	/api/auth/api-tokens	List API tokens
POST	/api/auth/api-tokens	Create token
DELETE	/api/auth/api-tokens/:id	Revoke token

SAML & SSO

Method	Endpoint	Description
GET	/api/saml/:orgSlug/metadata	Retrieve organization SAML metadata
POST	/api/saml/:orgSlug/acs	Organization SAML assertion consumer service

SCIM (System for Cross-domain Identity Management)

Method	Endpoint	Description
GET	/api/scim/v2/Users	List users
POST	/api/scim/v2/Users	Create user
GET	/api/scim/v2/Users/:id	Get user
PATCH	/api/scim/v2/Users/:id	Apply supported SCIM user updates
DELETE	/api/scim/v2/Users/:id	Delete user
GET	/api/scim/v2/Groups	List groups

Organizations & Admin

Method	Endpoint	Description
GET	/api/admin/orgs	List organizations (admin)
POST	/api/admin/orgs	Create organization (admin)
GET	/api/admin/users	List all users (admin)
POST	/api/admin/users	Create user (admin)
PATCH	/api/admin/users/:id	Update user (admin)
GET	/api/admin/quotas	List usage quotas (admin)
GET	/api/admin/quotas/:userId	Get user quota details (admin)
PATCH	/api/admin/quotas/:userId	Update user quota overrides (admin)
DELETE	/api/admin/quotas/:userId	Clear user quota overrides (admin)
POST	/api/admin/impersonate/:userId	Start impersonation session (admin)
POST	/api/admin/impersonate/stop	Stop impersonation session
GET	/api/admin/impersonate	List recent impersonation sessions (admin)
GET	/api/admin/audit	Audit log (admin)

Permission overrides and direct execution

PUT /api/tools/permissions accepts toolId, action, level (ALLOW, ASK, DENY), optional reason, and optional scope. A scope needs future expiresAt and at least one of sessionId, workspaceId, pathPattern, commandPattern. An existing DENY cannot be replaced by scoped ALLOW without first reviewing the denial. Deleting an override restores its manifest default.

Direct execution accepts an args object and runs unattended. Blocked ASK returns HTTP 409 with code: "approval_required"; other tool execution failures return 400 with code: "tool_execution_failed". See Security.

Gateway WebSocket

New clients connect to /gateway and send an authentication frame within five seconds. Use a short-lived ticket from GET /api/auth/ws-ticket where appropriate. Frames and event types are defined by src/core/gateway/protocol.ts; consult that schema rather than the retired /ws examples. The backend exposes gateway status through /api/gateway/status and connection information to authorized callers.

OpenAI-compatible text interface

GET /v1/models lists registry models and octipus/agent. POST /v1/chat/completions supports text messages and final-text SSE delivery. octipus/agent runs the latest user message through the agent; the older octipus/orchestrator alias is accepted. A stable user field or X-Octipus-Session header keeps an agent conversation sticky.

Registry model IDs use stateless provider passthrough. This is a limited text interface, not full OpenAI API compatibility: client tool schemas and multimodal content arrays are not supported. Streaming chunks the completed response rather than emitting provider tokens as they are generated.

Agent-mode usage reports the observed total under completion/total tokens, with prompt tokens set to zero because the split is unavailable. API token scope api:chat applies to completions; an unscoped token is full access.

MCP transport

The standalone MCP server uses separate /sse and /messages routes on its own listener. These are not backend REST routes. See MCP Server.