Skip to content
Octipus Logo Octipus

API Reference

All API endpoints are under /api with JWT Bearer authentication (except health and auth endpoints).

Interactive documentation is available at http://localhost:3005/swagger.

Health

Section titled “Health”

These endpoints do not require authentication.

MethodEndpointDescription
GET/healthBasic health check
GET/health/detailedService status with latencies
GET/health/readyReadiness probe
GET/health/liveLiveness probe

Authentication

Section titled “Authentication”
MethodEndpointAuthDescription
POST/api/auth/registerNoRegister new user
POST/api/auth/loginNoLogin with credentials (+ optional TOTP)
POST/api/auth/logoutYesLogout and invalidate session
GET/api/auth/meYesGet current user info
POST/api/auth/passkey/registerYesRegister WebAuthn passkey
POST/api/auth/passkey/authenticateNoAuthenticate with passkey
POST/api/auth/totp/setupYesSetup TOTP 2FA
POST/api/auth/totp/enableYesEnable TOTP after verification
POST/api/auth/totp/disableYesDisable TOTP 2FA
POST/api/auth/totp/verifyYesVerify TOTP code
POST/api/auth/linkYesRedeem channel link code

Agents

Section titled “Agents”

All agent endpoints require authentication.

MethodEndpointDescription
GET/api/agentsList all agents
POST/api/agentsSpawn new agent
GET/api/agents/:idGet agent details
DELETE/api/agents/:idStop and remove agent
POST/api/agents/:id/messageSend message to agent
POST/api/agents/:id/pausePause agent
POST/api/agents/:id/resumeResume paused agent
GET/api/agents/:id/eventsGet agent events (cursor-based: ?after=<seq>)

Agent Events

Section titled “Agent Events”

The events endpoint supports cursor-based polling:

GET /api/agents/:id/events?after=<seq>

Events are stored in a ring buffer (max 200 events per agent) with sequential IDs. Pass the last seen event ID as the after parameter to receive only new events.

Sessions

Section titled “Sessions”
MethodEndpointDescription
GET/api/sessionsList sessions
GET/api/sessions/:idGet session details
GET/api/sessions/:id/messagesGet session messages

Models

Section titled “Models”
MethodEndpointDescription
GET/api/modelsList all models
POST/api/modelsRegister new model
GET/api/models/:nameGet model details
PATCH/api/models/:nameUpdate model config
DELETE/api/models/:nameDelete model
POST/api/models/:id/defaultSet as default model
GET/api/models/routingGet topic routing
GET/api/models/healthCheck provider health
GET/api/models/cli/statusCLI tool availability
GET/api/models/cli/quotaCLI quota status
GET/api/models/providers/ollama/modelsList available Ollama models
GET/api/models/providers/litellm/modelsList LiteLLM models
GET/api/models/providers/:provider/knownKnown models for a provider
POST/api/models/testTest model connectivity before registration

Hooks

Section titled “Hooks”
MethodEndpointDescription
GET/api/hooksList all hooks
POST/api/hooksCreate hook
GET/api/hooks/:idGet hook details
PUT/api/hooks/:idUpdate hook
DELETE/api/hooks/:idDelete hook
POST/api/hooks/:id/enableEnable hook
POST/api/hooks/:id/disableDisable hook

Vault

Section titled “Vault”
MethodEndpointDescription
GET/api/vaultList credentials
POST/api/vaultStore credential
PATCH/api/vault/:idUpdate credential
DELETE/api/vault/:idDelete credential
POST/api/vault/:id/rotateRotate credential

Pipelines

Section titled “Pipelines”
MethodEndpointDescription
GET/api/pipelinesList user’s pipeline runs
GET/api/pipelines/:idGet pipeline detail with stages
POST/api/pipelines/:id/stopStop a running pipeline
GET/api/pipelines/templatesList pipeline templates
POST/api/pipelines/templatesCreate pipeline template
PUT/api/pipelines/templates/:idUpdate pipeline template
DELETE/api/pipelines/templates/:idDelete pipeline template

Notifications

Section titled “Notifications”
MethodEndpointDescription
GET/api/notificationsList notifications (paginated)
POST/api/notifications/:id/readMark notification as read
POST/api/notifications/read-allMark all notifications read

Voice

Section titled “Voice”
MethodEndpointDescription
POST/api/voice/transcribeTranscribe audio (base64) to text

Skills

Section titled “Skills”
MethodEndpointDescription
GET/api/skillsList registered skills
GET/api/skills/:idGet skill details
GET/api/skills/tools/allAll tools (skills + MCP combined)
GET/api/skills/permissionsUser permission overrides
PUT/api/skills/permissionsSet permission level
DELETE/api/skills/permissions/:skillId/:actionReset permission
POST/api/skills/:skillId/tools/:toolName/executeExecute a skill tool (MCP bridge)

Chat

Section titled “Chat”
MethodEndpointDescription
POST/api/chatSend a chat message
POST/api/chat/approveRespond to an approval request

WebSocket

Section titled “WebSocket”

Connect to /ws?token=<jwt> for real-time events.

Message Types

Section titled “Message Types”
EventDescription
subscribeSubscribe to event channels
unsubscribeUnsubscribe from event channels
messageSend a chat message
agent.statusAgent status changes
agent.messageAgent responses
agent.tool_callTool execution events

Connection Example

Section titled “Connection Example”
const ws = new WebSocket(`ws://localhost:3005/ws?token=${jwtToken}`);


ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'subscribe',
    channels: ['agent.status', 'agent.message']
  }));
};


ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};