API Routes

Route Groups

Group	File	Prefix	Endpoints
Chat (streaming)	`chat.py`	`/api/chat`	5
Sessions	`sessions.py`	`/api/chat`	11
Workspaces	`workspaces.py`	`/api/workspaces`	7
Auth	`auth.py`	`/api/auth`	5
Bots	`bots.py`	`/api/bots`	8
Modules	`modules.py`	`/api/modules`	5
MCP Servers	`mcp.py`	`/api/mcps`	6
Skills	`skills.py`	`/api/skills`	5
Context Folders	`context_folders.py`	`/api/contexts`	6
Claude Code	`claude_code.py`	`/api/claude-code`	5
Scheduler	`scheduler.py`	`/api/scheduler`	3
Sync	`sync.py`	`/api/sync`	5
Imports	`imports.py`	`/api/import`	5
Filesystem	`filesystem.py`	`/api/fs`	3
Prompts	`prompts.py`	`/api/prompts`	1
Usage	`usage.py`	`/api/usage`	1
Hooks	`hooks.py`	`/api/hooks`	3
Sandbox	`sandbox.py`	`/api/sandbox`	2
Health	`health.py`	`/api/health`	1

Chat (Streaming)

Core chat functionality with streaming SSE responses. Defined in chat.py.

POST /api/chat Run agent with streaming response

POST /api/chat/{session_id}/abort Abort active stream

GET /api/chat/{session_id}/stream-status Check if stream is active

GET /api/chat/active-streams List all active streams

POST /api/chat/{session_id}/answer Answer a permission prompt

POST /api/chat

The main chat endpoint. Sends a message and returns a streaming SSE response.

Request Body

{
  "message": "Help me understand this code",
  "session_id": null,                    // null = new session, string = resume
  "trust_level": "vault",               // "full" | "vault" | "sandboxed"
  "workspace_id": "my-project",         // optional workspace scope
  "attachments": [                       // optional
    {"name": "screenshot.png", "mimeType": "image/png", "base64Data": "..."}
  ],
  "context_files": ["/src/main.py"],     // optional file context
  "context_folders": ["/src"],           // optional folder context
  "working_directory": "/path/to/project" // optional CWD for agent
}

Response (SSE Stream)

data: {"type": "session", "id": "abc123", "title": "New Chat"}
data: {"type": "text", "content": "I'll help you...", "delta": "I'll"}
data: {"type": "tool_use_start", "id": "t1", "name": "Read", "input": {...}}
data: {"type": "tool_result", "tool_use_id": "t1", "result": "..."}
data: {"type": "result", "session_id": "abc123", "sdk_session_id": "sdk_xyz"}

Sessions

Session CRUD, configuration, and permission management. Defined in sessions.py.

GET /api/chat List sessions (with filters)

GET /api/chat/stats Session statistics

GET /api/chat/{session_id} Get session details

DELETE /api/chat/{session_id} Delete session

POST /api/chat/{session_id}/archive Archive session

POST /api/chat/{session_id}/unarchive Unarchive session

POST /api/chat/{session_id}/activate Activate pending bot session

PUT /api/chat/{session_id}/config Update session configuration

GET /api/chat/{session_id}/transcript Get full transcript

GET /api/chat/{session_id}/permissions Get permission grants/denies

POST /api/chat/{session_id}/permissions/grant Grant a tool permission

Workspaces

Workspace management for organizing sessions. Defined in workspaces.py.

GET /api/workspaces List all workspaces

POST /api/workspaces Create workspace

GET /api/workspaces/{slug} Get workspace details

PUT /api/workspaces/{slug} Update workspace

DELETE /api/workspaces/{slug} Delete workspace

GET /api/workspaces/{slug}/sessions List sessions in workspace

Authentication

API key management and auth settings. Defined in auth.py.

GET /api/auth/keys List API keys (hashed)

POST /api/auth/keys Create new API key

DELETE /api/auth/keys/{key_id} Revoke API key

GET /api/auth/settings Get auth settings

PUT /api/auth/settings Update auth mode

Header Options

# Option 1: X-API-Key header
X-API-Key: para_aBcDeFgHiJkLmNoPqRsT1234

# Option 2: Authorization header
Authorization: Bearer para_aBcDeFgHiJkLmNoPqRsT1234

Bots

Bot connector management and user pairing. Defined in bots.py.

GET /api/bots/status Get connector status

GET /api/bots/config Get bot configuration

PUT /api/bots/config Update bot configuration

POST /api/bots/{platform}/start Start a connector

POST /api/bots/{platform}/stop Stop a connector

POST /api/bots/{platform}/test Test connector connectivity

GET /api/bots/pairing List pairing requests

POST /api/bots/pairing/{id}/approve Approve pairing request

Modules

Module management, prompts, and approval. Defined in modules.py.

GET /api/modules List loaded modules

POST /api/modules/{name}/approve Approve module (record hash)

GET /api/modules/{mod}/prompt Get module system prompt

PUT /api/modules/{mod}/prompt Update module system prompt

GET /api/modules/{mod}/stats Module statistics

MCP Servers

Model Context Protocol server management. Defined in mcp.py.

GET /api/mcps List MCP servers

GET /api/mcps/{name} Get MCP server details

POST /api/mcps Add MCP server

DELETE /api/mcps/{name} Remove MCP server

POST /api/mcps/{name}/test Test MCP server connection

GET /api/mcps/{name}/tools List tools from MCP server

Skills

Skill plugin management. Defined in skills.py.

GET /api/skills List available skills

GET /api/skills/{name} Get skill details

POST /api/skills Create skill

DELETE /api/skills/{name} Delete skill

POST /api/skills/upload Upload skill file

Context Folders

Manage context folders and per-session context injection. Defined in context_folders.py.

GET /api/contexts/folders List available context folders

GET /api/contexts/chain Get context resolution chain

GET /api/contexts/session/{session_id} Get session contexts

PUT /api/contexts/session/{session_id} Update session contexts

POST /api/contexts/session/{session_id}/add Add context to session

DELETE /api/contexts/session/{session_id}/remove Remove context from session

Claude Code

Integration with local Claude Code sessions. Defined in claude_code.py.

GET /api/claude-code/recent Recent Claude Code sessions

GET /api/claude-code/projects List Claude Code projects

GET /api/claude-code/sessions List sessions for project

GET /api/claude-code/sessions/{session_id} Get session transcript

POST /api/claude-code/adopt/{session_id} Adopt Claude Code session

Scheduler

Manage scheduled daily agents. Defined in scheduler.py.

GET /api/scheduler List scheduled agents

POST /api/scheduler/reload Reload agent schedules

POST /api/scheduler/agents/{name}/trigger Trigger agent manually

Sync

Cross-device journal sync. Defined in sync.py.

GET /api/sync/manifest Get file manifest (hashes)

GET /api/sync/changes Get changed files since timestamp

POST /api/sync/push Push local changes to server

POST /api/sync/pull Pull server changes to local

DELETE /api/sync/files Delete synced files

Imports

Import conversations from Claude, ChatGPT, or file. Defined in imports.py.

POST /api/import Import JSON export

POST /api/import/file Import from uploaded file

POST /api/import/path Import from vault path

POST /api/import/sync Sync imported sessions

GET /api/import/contexts Get import contexts

Filesystem

File operations scoped to the vault. Defined in filesystem.py.

GET /api/fs/ls List directory contents

GET /api/fs/read Read file contents

PUT /api/fs/write Write file

Other Endpoints

Health

GET /api/health Server health + version info

Usage

GET /api/usage Claude token usage stats

Prompts

GET /api/prompts/preview Preview rendered system prompt

Hooks

GET /api/hooks List registered hooks

GET /api/hooks/errors Get hook execution errors

Sandbox

GET /api/sandbox/status Docker sandbox status

GET /api/sandbox/config Sandbox configuration

Error Responses

401 Unauthorized

{"error": "Unauthorized", "message": "Valid API key required"}

404 Not Found

{"error": "Not Found", "message": "Session not found: abc123"}

422 Validation Error (Pydantic)

{"detail": [{"loc": ["body", "message"], "msg": "field required", "type": "value_error.missing"}]}