Skip to content

API Reference

Jump to bottom
Michael Elliott edited this page Apr 5, 2026 · 2 revisions

API Reference

TITAN v1.0.0 Gateway API — 210+ endpoints on port 48420

Base URL: http://localhost:48420

All /api/* routes require authentication when auth is configured. Pass Authorization: Bearer <token> header or ?token=<token> query parameter.

Table of Contents

Authentication

Method Path Description
GET /login Serve login HTML page
POST /api/login Authenticate with password/token. Rate limited: 5 req/min

POST /api/login

// Request
{ "password": "your-password-or-token" }

// Response (success)
{ "token": "hex-string-64-chars" }

// Response (failure) — 401
{ "error": "Invalid password" }

Auth modes: none (open access), password, token. When no token is configured, auth is bypassed.

Core

Method Path Description
GET / Serve React SPA (Mission Control v2) or legacy dashboard
GET /legacy Legacy HTML dashboard
GET /metrics Prometheus metrics (no auth, standard scrape path)
GET /api/health Health check
GET /api/stats System statistics
GET /api/security Security audit report

GET /api/health

{ "status": "ok", "version": "1.0.0", "uptime": 3600.5, "onboarded": true }

GET /api/stats

{
  "version": "1.0.0",
  "uptime": 3600.5,
  "model": "claude-sonnet-4-20250514",
  "provider": "anthropic",
  "memoryMB": 256,
  "memoryUsage": { "heapUsed": 0, "heapTotal": 0, "rss": 0, "external": 0, "arrayBuffers": 0 },
  "health": {
    "ollamaHealthy": true,
    "ttsHealthy": true,
    "lastCheck": "2025-01-01T00:00:00.000Z",
    "stuckDetected": false,
    "uptimeSeconds": 3600,
    "memoryUsageMB": 128,
    "activeLlmRequests": 0
  }
}

Sessions

Method Path Description
GET /api/sessions List all sessions
GET /api/sessions/search Full-text search across all sessions
GET /api/sessions/:id Get session by ID
GET /api/sessions/:id/messages Get session message history
GET /api/sessions/:id/export Export session as JSON or markdown
POST /api/sessions/:id/close Close a session
POST /api/sessions/:id/abort Abort an active session
PATCH /api/sessions/:id Update session metadata
DELETE /api/sessions/:id Delete a session

GET /api/sessions/search

Query Param Type Description
q string Search query (min 2 chars, required)
limit number Max results (default: 50) 
{
  "query": "search term",
  "results": [
    { "sessionId": "abc", "sessionName": "Session 1", "role": "user", "content": "...", "timestamp": "..." }
  ],
  "total": 1
}

GET /api/sessions/:id/export

Query Param Type Description
format string json (default) or markdown / md

Chat & Messaging

Method Path Description
POST /api/message Send a message (main chat endpoint). Supports SSE streaming
POST /api/chat/stream SSE streaming chat (token-by-token). Rate limited: 30 req/min

POST /api/message

Rate limited. Concurrency guarded. Supports SSE when Accept: text/event-stream header is present.

// Request
{
  "content": "Hello TITAN",
  "channel": "api",
  "userId": "api-user",
  "agentId": "optional-agent-id",
  "sessionId": "optional-session-id"
}

// Response (JSON)
{ "content": "Response text", "sessionId": "abc-123", "toolsUsed": [], "model": "anthropic/claude-sonnet-4-20250514" }

// Response (SSE) — events: chunk, tool_start, tool_result, done

POST /api/chat/stream

// Request
{ "content": "Hello", "model": "optional-model-override" }

// SSE events: data chunks with { type: "chunk"|"done"|"error", ... }

Models

Method Path Description
GET /api/models List available models grouped by provider
GET /api/models/discover Force-discover all models from all providers
GET /api/fallback-state Get current fallback chain state
POST /api/model/switch Switch the active model

GET /api/models

{
  "ollama": ["ollama/llama3.2:latest"],
  "anthropic": ["anthropic/claude-sonnet-4-20250514"],
  "current": "anthropic/claude-sonnet-4-20250514",
  "aliases": { "fast": "ollama/llama3.2:latest" }
}

POST /api/model/switch

// Request
{ "model": "anthropic/claude-sonnet-4-20250514" }

// Response
{ "success": true, "model": "anthropic/claude-sonnet-4-20250514" }

Validates Ollama models exist locally before switching. Returns 404 if model not found, 503 if Ollama unreachable.

Configuration

Method Path Description
GET /api/config Get full configuration (sensitive fields masked)
POST /api/config Update configuration
GET /api/cloud/config Get cloud mode configuration

GET /api/config — Returns nested config with agent, voice, security, gateway, logging, providers, oauth, channels, nvidia sections. Provider API keys are returned as { configured: true/false }.

POST /api/config — Accepts partial config updates (deep-merged).

Skills

Method Path Description
GET /api/skills List all loaded skills
POST /api/skills/:name/toggle Enable/disable a skill

POST /api/skills/:name/toggle

{ "ok": true, "skill": "web_browse", "enabled": true, "tools": ["browse", "search"] }

Marketplace

Method Path Description
GET /api/marketplace List marketplace skills (with install status)
GET /api/marketplace/search Search marketplace skills
POST /api/marketplace/install Install a marketplace skill
POST /api/marketplace/uninstall Uninstall a marketplace skill

POST /api/marketplace/install

// Request
{ "skill": "skill-name" }

Personas

Method Path Description
GET /api/personas List all personas with active persona
POST /api/persona/switch Switch active persona

POST /api/persona/switch

// Request
{ "persona": "researcher" }

// Response
{ "ok": true, "active": "researcher" }

Tools

Method Path Description
GET /api/tools List all registered tools 
[{ "name": "web_search", "description": "Search the web" }]

Channels

Method Path Description
GET /api/channels List all channel adapter statuses

Providers

Method Path Description
GET /api/providers Health check all configured LLM providers

VRAM (GPU Memory)

Method Path Description
GET /api/vram Get GPU VRAM snapshot (state, models, leases)
POST /api/vram/acquire Request VRAM allocation (auto-swaps models)
POST /api/vram/release Release a VRAM lease
GET /api/vram/check Dry-run VRAM availability check

POST /api/vram/acquire

// Request
{ "service": "tts", "requiredMB": 2048, "leaseDurationMs": 300000 }

POST /api/vram/release

// Request
{ "leaseId": "uuid", "restoreModel": true }

GET /api/vram/check?mb=2048

MCP (Model Context Protocol)

Method Path Description
GET /api/mcp/server Get MCP server status
GET /api/mcp/clients List MCP client connections
POST /api/mcp/clients Add a new MCP server connection
DELETE /api/mcp/clients/:id Remove an MCP server connection
POST /api/mcp/clients/:id/toggle Enable/disable an MCP server
POST /api/mcp/clients/:id/test Test connection to an MCP server
GET /api/mcp/presets List built-in MCP server presets

POST /api/mcp/clients

// Request (from preset)
{ "presetId": "hindsight" }

// Request (custom)
{ "id": "my-server", "name": "My Server", "command": "npx", "args": ["my-mcp-server"], "enabled": true }

Agents (Multi-Agent)

Method Path Description
GET /api/agents List all agents with capacity info
POST /api/agents/spawn Spawn a new sub-agent
POST /api/agents/stop Stop a running agent

POST /api/agents/spawn

// Request
{ "name": "researcher", "model": "anthropic/claude-sonnet-4-20250514", "systemPrompt": "You are a researcher." }

Mesh Networking

P2P mesh for multi-node TITAN deployments. Requires mesh.enabled: true in config.

Method Path Description
GET /api/mesh/hello Node discovery handshake (version, models, load)
GET /api/mesh/peers List approved peers
GET /api/mesh/models List models available across the mesh
GET /api/mesh/pending List pending peer approval requests
POST /api/mesh/approve/:nodeId Approve a pending peer
POST /api/mesh/reject/:nodeId Reject a pending peer
POST /api/mesh/revoke/:nodeId Revoke an approved peer
GET /api/mesh/status Comprehensive mesh health/status
GET /api/mesh/routes Get mesh routing table

GET /api/mesh/hello

{
  "titan": true,
  "nodeId": "uuid",
  "version": "1.0.0",
  "models": ["ollama/llama3.2:latest"],
  "agentCount": 2,
  "load": 0.35
}

GET /api/mesh/status

{
  "enabled": true,
  "status": "healthy",
  "nodeId": "uuid",
  "discoveryModes": ["mdns", "tailscale"],
  "peers": { "total": 3, "connected": 3, "unreachable": 0, "pending": 0 },
  "peerDetails": [...],
  "healthScore": 1.0,
  "maxPeers": 10,
  "autoApprove": false
}

Teams RBAC

Role-based access control for multi-user team management.

Method Path Description
GET /api/teams List all teams
POST /api/teams Create a team
GET /api/teams/:teamId Get team details with stats
PATCH /api/teams/:teamId Update team name/description
DELETE /api/teams/:teamId Delete a team
GET /api/teams/:teamId/members List team members
POST /api/teams/:teamId/members Add a member to a team
DELETE /api/teams/:teamId/members/:userId Remove a team member
PATCH /api/teams/:teamId/members/:userId/role Update a member's role
POST /api/teams/:teamId/invites Create an invite code
POST /api/teams/join Join a team via invite code
GET /api/teams/:teamId/permissions/:userId Get effective permissions for user
PUT /api/teams/:teamId/roles/:role/permissions Set permissions for a role
GET /api/teams/:teamId/tools/:toolName/check/:userId Check if user can use a tool

POST /api/teams

// Request
{ "name": "Engineering", "description": "Core engineering team", "ownerId": "user-123" }

// Response — 201
{ "team": { "id": "uuid", "name": "Engineering" } }

POST /api/teams/:teamId/invites

// Request
{ "role": "operator", "expiresInHours": 48 }

// Response — 201
{ "code": "invite-code", "expiresInHours": 48 }

POST /api/teams/join

// Request
{ "code": "invite-code", "userId": "user-456", "displayName": "Jane" }

// Response
{ "teamId": "uuid", "teamName": "Engineering", "role": "operator" }

Goals

Method Path Description
GET /api/goals List all goals
POST /api/goals Create a goal
GET /api/goals/:id Get a goal by ID
DELETE /api/goals/:id Delete a goal
POST /api/goals/:id/subtasks Add a subtask to a goal
POST /api/goals/:id/subtasks/:sid/complete Complete a subtask

POST /api/goals

// Request
{ "title": "Ship v2.0", "description": "Major release", "subtasks": [], "priority": "high", "tags": ["release"] }

// Response — 201
{ "goal": { "id": "uuid", "title": "Ship v2.0", ... } }

Recipes / Workflows

Method Path Description
GET /api/recipes List all saved recipes
GET /api/recipes/:id Get a recipe by ID
POST /api/recipes Create a recipe
PUT /api/recipes/:id Update a recipe
DELETE /api/recipes/:id Delete a recipe
POST /api/recipes/:id/run Execute a recipe
GET /api/recipes/builtin/templates List built-in recipe templates
POST /api/recipes/import Import a recipe from YAML

POST /api/recipes

// Request
{ "id": "my-recipe", "name": "Daily Report", "steps": [{ "prompt": "Generate a summary" }] }

// Response — 201
{ "recipe": { "id": "my-recipe", "name": "Daily Report", ... } }

POST /api/recipes/:id/run

// Request
{ "params": { "topic": "AI news" } }

// Response
{ "recipe": "Daily Report", "stepsExecuted": 3, "steps": [...] }

Plugins

Method Path Description
GET /api/plugins List loaded plugins 
{ "plugins": [{ "name": "SmartCompress", "version": "1.0.0" }] }

Autopilot

Method Path Description
GET /api/autopilot/status Get autopilot status
GET /api/autopilot/history Get autopilot run history
POST /api/autopilot/run Trigger an autopilot run
POST /api/autopilot/toggle Enable/disable autopilot

POST /api/autopilot/toggle

// Request
{ "enabled": true, "dryRun": false }

// Response
{ "enabled": true, "dryRun": false }

POST /api/autopilot/run

// Request (optional)
{ "dryRun": true }

Daemon

Method Path Description
GET /api/daemon/status Get daemon status
POST /api/daemon/stop Pause the daemon
POST /api/daemon/resume Resume the daemon
GET /api/daemon/stream SSE stream for daemon events

GET /api/daemon/stream — SSE events: daemon:started, daemon:stopped, daemon:paused, daemon:resumed, daemon:heartbeat, goal:subtask:ready, health:ollama:down, health:ollama:degraded, cron:stuck

Cron

Method Path Description
GET /api/cron List all cron jobs
POST /api/cron Create a cron job
POST /api/cron/:id/toggle Enable/disable a cron job
DELETE /api/cron/:id Delete a cron job

POST /api/cron

// Request
{ "name": "Daily cleanup", "schedule": "0 3 * * *", "command": "clean old sessions" }

// Response — 201
{ "job": { "id": "uuid", "name": "Daily cleanup", "schedule": "0 3 * * *", "command": "...", "enabled": true } }

Command Post (Agent Governance)

Paperclip-inspired agent governance system with atomic task checkout, budget enforcement, goal ancestry, and agent registry.

Dashboard & Agents

Method Path Description
GET /api/command-post/dashboard Full dashboard state
GET /api/command-post/agents List registered agents
POST /api/command-post/agents/:id/heartbeat Report agent heartbeat
DELETE /api/command-post/agents/:id Remove an agent
PATCH /api/command-post/agents/:id Update agent org chart fields
GET /api/command-post/agents/stale Detect stale agents (no heartbeat in 1+ hour)
GET /api/command-post/agents/:agentId/inbox Get agent inbox items
GET /api/command-post/org Get organization chart

Tasks & Checkouts

Method Path Description
POST /api/command-post/tasks/:goalId/:subtaskId/checkout Checkout a task (atomic lock)
POST /api/command-post/tasks/:goalId/:subtaskId/checkin Check in a completed task
GET /api/command-post/checkouts List active checkouts
GET /api/command-post/checkouts/expired List expired checkouts
POST /api/command-post/checkouts/sweep Clean up expired checkouts

Budgets

Method Path Description
GET /api/command-post/budgets List budget policies
POST /api/command-post/budgets Create a budget policy
PUT /api/command-post/budgets/:id Update a budget policy
DELETE /api/command-post/budgets/:id Delete a budget policy
POST /api/command-post/budgets/:agentId/enforce Enforce budget for an agent
GET /api/command-post/budgets/agent/:agentId Get budget info for an agent

POST /api/command-post/budgets

// Request
{
  "name": "Agent daily limit",
  "scope": { "type": "agent", "targetId": "agent-uuid" },
  "period": "daily",
  "limitUsd": 5.00,
  "warningThresholdPercent": 80,
  "action": "pause",
  "enabled": true
}

Goals & Ancestry

Method Path Description
GET /api/command-post/goals/tree Get goal hierarchy tree
GET /api/command-post/goals/:id/ancestry Get ancestry chain for a goal
POST /api/command-post/goals/:id/validate Validate goal ancestry (depth + cycle check)

Issues

Method Path Description
GET /api/command-post/issues List issues (filterable by status, assignee, goalId)
POST /api/command-post/issues Create an issue
GET /api/command-post/issues/:id Get issue with comments
PATCH /api/command-post/issues/:id Update an issue
POST /api/command-post/issues/:id/checkout Checkout an issue for an agent
POST /api/command-post/issues/:id/comments Add a comment to an issue

Approvals

Method Path Description
GET /api/command-post/approvals List approvals (filterable by status)
POST /api/command-post/approvals Create an approval request
POST /api/command-post/approvals/:id/approve Approve a request
POST /api/command-post/approvals/:id/reject Reject a request

Runs & Activity

Method Path Description
GET /api/command-post/runs List agent runs (filterable by agentId)
GET /api/command-post/activity Get activity feed
GET /api/command-post/stream SSE stream for Command Post events

GET /api/command-post/stream — SSE events: commandpost:activity, commandpost:task:checkout, commandpost:task:checkin, commandpost:task:expired, commandpost:budget:warning, commandpost:budget:exceeded, commandpost:agent:heartbeat, commandpost:agent:status

Wakeup System

Async sub-agent delegation and coordination.

Method Path Description
POST /api/command-post/wakeup Queue a wakeup request for an agent
GET /api/command-post/wakeup/:requestId Get wakeup request status
DELETE /api/command-post/wakeup/:requestId Cancel a wakeup request
GET /api/command-post/sessions/:sessionId/pending-results Drain pending results for a session

POST /api/command-post/wakeup

// Request
{ "issueId": "uuid", "agentId": "uuid", "agentName": "Researcher", "task": "Research topic X" }

// Response
{ "wakeupRequestId": "uuid", "status": "queued" }

Voice

LiveKit WebRTC voice integration with multiple TTS engines (Orpheus, Qwen3-TTS, Edge, Browser).

Method Path Description
GET /api/voice/status Voice subsystem availability
GET /api/voice/config Voice configuration
GET /api/voice/health Full voice health check (LiveKit, STT, TTS, Agent)
POST /api/livekit/token Generate LiveKit room token
POST /api/voice/preview Preview TTS voice synthesis
POST /api/voice/stream Streaming voice: LLM -> sentence chunking -> TTS. Rate limited: 30 req/min
GET /api/voice/voices List available TTS voices
GET /api/voice/orpheus/status Orpheus TTS server status
POST /api/voice/orpheus/install Auto-install Orpheus TTS
POST /api/voice/orpheus/start Start Orpheus TTS server
POST /api/voice/orpheus/stop Stop Orpheus TTS server
GET /api/voice/qwen3tts/status Qwen3-TTS server status
POST /api/voice/qwen3tts/install Auto-install Qwen3-TTS
POST /api/voice/qwen3tts/start Start Qwen3-TTS server
POST /api/voice/qwen3tts/stop Stop Qwen3-TTS server

GET /api/voice/health

{
  "livekit": true,
  "stt": true,
  "tts": true,
  "agent": true,
  "overall": true,
  "ttsEngine": "orpheus"
}

POST /api/voice/preview

// Request
{ "voice": "tara", "text": "Hello world" }

// Response: audio/wav binary

Voice Cloning

Method Path Description
POST /api/voice/clone/upload Upload a voice sample for cloning
GET /api/voice/clone/voices List cloned voices
DELETE /api/voice/clone/:name Delete a cloned voice

POST /api/voice/clone/upload — Accepts raw audio upload with X-Voice-Name and optional X-Voice-Transcript headers.

NVIDIA Health

Method Path Description
GET /api/nvidia/health/cuopt Check NVIDIA cuOpt VRP service health
GET /api/nvidia/health/asr Check NVIDIA ASR (Nemotron) service health
GET /api/nvidia/health/nim Check NVIDIA NIM API connectivity

Training & Self-Improvement

Method Path Description
GET /api/self-improve/history Get self-improvement session history
GET /api/self-improve/config Get self-improvement configuration
GET /api/training/stream SSE stream for training progress events
GET /api/training/progress Poll training progress (fallback for SSE)
DELETE /api/training/progress Clear training progress log
GET /api/training/runs List completed training runs

GET /api/training/progress

Query Param Type Description
since string ISO timestamp filter (return events after this time)

Autoresearch

Autonomous self-improvement research: LLM-as-judge eval, LoRA fine-tuning pipeline.

Method Path Description
GET /api/autoresearch/results Get experiment results
GET /api/autoresearch/performance Get performance metrics vs baseline
GET /api/autoresearch/status Get autoresearch status
GET /api/autoresearch/benchmark Get benchmark results
POST /api/autoresearch/trigger Trigger an autoresearch experiment
POST /api/autoresearch/generate-data Generate training data
POST /api/autoresearch/deploy Deploy best trained model to Ollama

GET /api/autoresearch/results

Query Param Type Description
type string tool_router (default) or agent

POST /api/autoresearch/trigger

// Request
{ "type": "agent", "config": { "baseModel": "qwen2.5:32b", "epochs": 2, "timeBudgetMin": 60 } }

Files

Workspace file browser for ~/.titan/ directory.

Method Path Description
GET /api/files List directory contents
GET /api/files/read Read file contents (max 1MB)
POST /api/files/upload Upload a file (max 50MB)
GET /api/files/uploads List uploaded files
DELETE /api/files/uploads/:name Delete an uploaded file

GET /api/files?path=sessions

{
  "path": "sessions",
  "entries": [
    { "name": "abc.json", "path": "sessions/abc.json", "type": "file", "size": 1024, "modified": "..." }
  ],
  "basePath": "/home/user/.titan"
}

POST /api/files/upload — Send raw binary with X-Filename and optional X-Session-Id headers.

Audit

Method Path Description
GET /api/audit Query audit log
GET /api/audit/stats Get audit statistics

GET /api/audit

Query Param Type Description
since string Start time (ISO)
until string End time (ISO)
action string Filter by action type
source string Filter by source
tool string Filter by tool name
limit number Max entries (default: 100)

Browser Automation

Method Path Description
POST /api/browser/form-fill Direct form fill (bypasses LLM, supports postClicks)
POST /api/browser/solve-captcha Solve CAPTCHA on a URL via CapSolver

POST /api/browser/form-fill

// Request
{
  "url": "https://example.com/form",
  "data": { "name": "John", "email": "john@example.com" },
  "submit": true,
  "postClicks": ["Submit", "#agree-checkbox"]
}

Activity Feed

Method Path Description
GET /api/activity/recent Get recent activity events from logs
GET /api/activity/summary Get activity summary (sessions, goals, status)

GET /api/activity/recent

Query Param Type Description
limit number Max events (default: 200)
filter string all, errors, tool, agent, autopilot, goal, search, router, graph, system

GET /api/activity/summary

{
  "activeSessions": 3,
  "toolCallsLast24h": 150,
  "autopilotRunsToday": 5,
  "autopilotEnabled": true,
  "activeGoals": 2,
  "goals": [{ "id": "uuid", "title": "Ship v2", "progress": 75 }],
  "currentModel": "anthropic/claude-sonnet-4-20250514",
  "autonomyMode": "supervised",
  "status": "idle",
  "graphStats": { "entities": 100, "edges": 250 }
}

Memory Graph

Native memory graph (replaces Neo4j/Graphiti).

Method Path Description
GET /api/graphiti Get full memory graph (nodes + edges)
DELETE /api/graphiti Clear the memory graph 
{
  "graphReady": true,
  "episodeCount": 42,
  "nodeCount": 100,
  "edgeCount": 250,
  "nodes": [...],
  "edges": [...]
}

Profile

Method Path Description
GET /api/profile Get user profile
POST /api/profile Update user profile 
// GET response
{ "name": "Tony", "technicalLevel": "expert", "projectCount": 5, "goalCount": 3 }

Learning

Method Path Description
GET /api/learning Get learning statistics

Soul

SOUL.md — persistent personality and identity configuration.

Method Path Description
GET /api/soul Get SOUL.md content
POST /api/soul Update SOUL.md

POST /api/soul

// Raw content
{ "content": "# Soul\n\nYou are TITAN..." }

// Or onboarding template
{ "aboutMe": "A developer", "personality": "Helpful and direct" }

Google OAuth

Method Path Description
GET /api/auth/google/status Check Google connection status
GET /api/auth/google/start Start Google OAuth flow (redirects)
GET /api/auth/google/callback OAuth callback handler
POST /api/auth/google/disconnect Disconnect Google account

Tunnel

Method Path Description
GET /api/tunnel/status Get tunnel status (for remote access)

Costs & Usage

Method Path Description
GET /api/costs Get cost optimizer status
GET /api/usage Per-model cost breakdown

GET /api/usage

Query Param Type Description
hours number Lookback period (default: 24) 
{
  "period": "24h",
  "totalRequests": 100,
  "totalTokens": 50000,
  "estimatedCostUsd": 0.25,
  "byModel": {
    "anthropic/claude-sonnet-4-20250514": {
      "requests": 50,
      "promptTokens": 10000,
      "completionTokens": 5000,
      "totalTokens": 15000,
      "estimatedCostUsd": 0.15,
      "avgDurationMs": 2500
    }
  },
  "recentEntries": [...]
}

Update System

Method Path Description
GET /api/update Check for available updates
POST /api/update Trigger update (npm or git pull)

POST /api/update

// Request
{ "restart": true }

// Response
{ "ok": true, "message": "Update completed", "restarting": true, "output": "..." }

Metrics

Method Path Description
GET /api/metrics Prometheus-format metrics
GET /api/metrics/summary JSON metrics summary for dashboard

Onboarding

Method Path Description
GET /api/onboarding/status Get onboarding status
POST /api/onboarding/complete Complete the onboarding wizard

Data Management

Method Path Description
DELETE /api/data Full data reset (graph + knowledge + titan-data)

API Documentation

Method Path Description
GET /api/docs Interactive API documentation (JSON)
GET /docs API documentation HTML page

Logs

Method Path Description
GET /api/logs Live log tail (secrets redacted)

GET /api/logs

Query Param Type Description
lines number Number of lines to return (default: 200)

Error Responses

All endpoints return errors in a consistent format:

{ "error": "Description of the error" }

Common HTTP status codes:

  • 400 — Bad request (missing/invalid parameters)
  • 401 — Unauthorized (invalid or missing auth token)
  • 403 — Forbidden (access denied)
  • 404 — Not found
  • 409 — Conflict (e.g., task already checked out by another agent)
  • 422 — Unprocessable entity (validation error)
  • 500 — Internal server error
  • 503 — Service unavailable (server busy, external service down)

Rate Limiting

Some endpoints have rate limiting:

Endpoint Window Max Requests
POST /api/login 60 seconds 5
POST /api/message Default window Default max
POST /api/chat/stream 60 seconds 30
POST /api/voice/stream 60 seconds 30

SSE Streaming

Several endpoints support Server-Sent Events (SSE) for real-time updates:

  • POST /api/message — Set Accept: text/event-stream header
  • POST /api/chat/stream — Always SSE
  • GET /api/daemon/stream — Daemon lifecycle events
  • GET /api/command-post/stream — Command Post governance events
  • GET /api/training/stream — Training progress events

All SSE endpoints include periodic keepalive comments (: keepalive) every 15 seconds.

Source: src/gateway/server.ts

4,633 tests across 154 files | 100+ skills | ~195 tools | 36 providers | 15 channels

Back to Wiki Home

TITAN Wiki

Clone this wiki locally