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

These endpoints do not require authentication.

Method	Endpoint	Description
GET	/health	Basic health check
GET	/health/detailed	Service status with latencies
GET	/health/ready	Readiness probe
GET	/health/live	Liveness probe

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/logout	Yes	Logout and invalidate session
GET	/api/auth/me	Yes	Get current user info
POST	/api/auth/passkey/register	Yes	Register WebAuthn passkey
POST	/api/auth/passkey/authenticate	No	Authenticate with passkey
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/totp/verify	Yes	Verify TOTP code
POST	/api/auth/link	Yes	Redeem channel link code

Agents

All agent endpoints require authentication.

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
POST	/api/agents/:id/pause	Pause agent
POST	/api/agents/:id/resume	Resume paused agent
GET	/api/agents/:id/events	Get agent events (cursor-based: ?after=<seq>)

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

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/:id/default	Set as default model
GET	/api/models/routing	Get topic routing
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
POST	/api/models/test	Test model connectivity before registration

Hooks

Method	Endpoint	Description
GET	/api/hooks	List all hooks
POST	/api/hooks	Create hook
GET	/api/hooks/:id	Get hook details
PUT	/api/hooks/:id	Update hook
DELETE	/api/hooks/:id	Delete hook
POST	/api/hooks/:id/enable	Enable hook
POST	/api/hooks/:id/disable	Disable hook

Vault

Method	Endpoint	Description
GET	/api/vault	List credentials
POST	/api/vault	Store credential
PATCH	/api/vault/:id	Update credential
DELETE	/api/vault/:id	Delete credential
POST	/api/vault/:id/rotate	Rotate credential

Pipelines

Method	Endpoint	Description
GET	/api/pipelines	List user’s pipeline runs
GET	/api/pipelines/:id	Get pipeline detail with stages
POST	/api/pipelines/:id/stop	Stop a running pipeline
GET	/api/pipelines/templates	List pipeline templates
POST	/api/pipelines/templates	Create pipeline template
PUT	/api/pipelines/templates/:id	Update pipeline template
DELETE	/api/pipelines/templates/:id	Delete pipeline template

Notifications

Method	Endpoint	Description
GET	/api/notifications	List notifications (paginated)
POST	/api/notifications/:id/read	Mark notification as read
POST	/api/notifications/read-all	Mark all notifications read

Voice

Method	Endpoint	Description
POST	/api/voice/transcribe	Transcribe audio (base64) to text

Skills

Method	Endpoint	Description
GET	/api/skills	List registered skills
GET	/api/skills/:id	Get skill details
GET	/api/skills/tools/all	All tools (skills + MCP combined)
GET	/api/skills/permissions	User permission overrides
PUT	/api/skills/permissions	Set permission level
DELETE	/api/skills/permissions/:skillId/:action	Reset permission
POST	/api/skills/:skillId/tools/:toolName/execute	Execute a skill tool (MCP bridge)

Chat

Method	Endpoint	Description
POST	/api/chat	Send a chat message
POST	/api/chat/approve	Respond to an approval request

Documents

Method	Endpoint	Description
POST	/api/documents/upload	Upload files (multipart)
GET	/api/documents	List documents with filters
GET	/api/documents/:id	Get document details with OCR text

Knowledge Base

Method	Endpoint	Description
GET	/api/knowledge	Browse entries with filters
GET	/api/knowledge/stats	Get stats (counts by source type)
GET	/api/knowledge/:id	Get full entry content
POST	/api/knowledge/search	Search with query, mode, filters
DELETE	/api/knowledge/:id	Delete entry
POST	/api/knowledge/index	Index a file or directory

Reader

Method	Endpoint	Description
POST	/api/reader/read	Read and extract content from URL
GET	/api/reader/tasks	List reader tasks
GET	/api/reader/tasks/:id	Get task results

Research

Method	Endpoint	Description
POST	/api/research/start	Start a research job
GET	/api/research/jobs	List research jobs
GET	/api/research/jobs/:id	Get job status and results
POST	/api/research/jobs/:id/cancel	Cancel a research job

Tasks & Recurring Tasks

Method	Endpoint	Description
GET	/api/tasks	List user tasks
POST	/api/tasks	Create a task
PATCH	/api/tasks/:id	Update task
DELETE	/api/tasks/:id	Delete task
POST	/api/tasks/:id/complete	Mark task complete
GET	/api/recurring-tasks	List recurring tasks
POST	/api/recurring-tasks	Create recurring task
PATCH	/api/recurring-tasks/:id	Update recurring task
DELETE	/api/recurring-tasks/:id	Delete recurring task

Email

Method	Endpoint	Description
GET	/api/email/messages	Get email messages (read-only)
POST	/api/email/send	Send email (requires permission)
POST	/api/email/process	Trigger email processing

Capabilities

Method	Endpoint	Description
GET	/api/capabilities	List all capabilities
GET	/api/capabilities/hardware	Get hardware info and fit analysis
POST	/api/capabilities/install	Install a capability (e.g., model)

Experts

Method	Endpoint	Description
GET	/api/experts	List all experts (system + custom)
GET	/api/experts/:id	Get expert details
POST	/api/experts	Create custom expert
PATCH	/api/experts/:id	Update expert
DELETE	/api/experts/:id	Delete expert

Organizations & SSO

Method	Endpoint	Description
GET	/api/orgs	List user’s organizations
POST	/api/orgs	Create organization
GET	/api/orgs/:id	Get organization details
PUT	/api/orgs/:id/sso	Configure SSO/SAML settings
GET	/api/saml/metadata	Get SAML metadata for federation
POST	/api/saml/acs	SAML assertion consumer endpoint
GET	/api/scim/v2/users	SCIM user provisioning endpoint
POST	/api/scim/v2/users	SCIM user creation

Admin (Audit & Management)

Method	Endpoint	Description
GET	/api/admin/audit	Audit log entries
GET	/api/admin/users	List all users (admin only)
POST	/api/admin/users/:id/impersonate	Impersonate user (admin only)
POST	/api/admin/users/:id/invite	Invite user
PATCH	/api/admin/users/:id	Update user role/permissions

Webhooks

Method	Endpoint	Description
GET	/api/webhooks	List outgoing webhooks
POST	/api/webhooks	Create webhook
PATCH	/api/webhooks/:id	Update webhook
DELETE	/api/webhooks/:id	Delete webhook
POST	/api/hooks/incoming/:hookId	Receive inbound webhook (public, auth via secret)
POST	/api/teams-webhook	Teams/Microsoft Teams webhook handler
POST	/api/whatsapp-webhook	WhatsApp webhook handler

WebSocket

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

Message Types

Event	Description
subscribe	Subscribe to event channels
unsubscribe	Unsubscribe from event channels
message	Send a chat message
agent.status	Agent status changes
agent.message	Agent responses
agent.tool_call	Tool execution events

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);
};

Tip

For the complete interactive API documentation with request/response schemas, visit http://localhost:3005/swagger when the backend is running.