HTTP routes
Every server endpoint, grouped by surface.
The HTTP API is grouped by surface. Each path below links to a dedicated endpoint specification page.
Authentication
GET /health is public. Every other route on the SNA runtime requires
Authorization: Bearer <authToken>, including /api/sna-port, SSE
routes, and chat image reads. Missing or invalid tokens return 401;
browser requests from disallowed origins return 403.
SDK-managed hosts should pass handle.connection to SnaClient or
SnaProvider. A separate app-owned discovery endpoint may return
{ baseUrl, authToken } to a trusted renderer, but the SNA runtime's
own /api/sna-port route is still protected.
System
| Method | Path | Purpose |
|---|---|---|
GET | /health | Health check |
GET | /api/sna-port | Read the current SNA API port |
Sessions
| Method | Path | Purpose |
|---|---|---|
POST | /agent/sessions | Create a session record |
GET | /agent/sessions | List sessions |
PATCH | /agent/sessions/{id} | Update label, meta, cwd |
DELETE | /agent/sessions/{id} | Delete a session, history, runtime chain, and pending permission |
Agent lifecycle
| Method | Path | Purpose |
|---|---|---|
POST | /agent/start | Spawn an agent into a session |
POST | /agent/send | Send a message |
POST | /agent/restart | Kill and re-spawn |
POST | /agent/resume | Resume with normalized history |
POST | /agent/interrupt | Cancel the current turn |
POST | /agent/set-model | Change model at runtime |
POST | /agent/set-permission-mode | Change permission mode at runtime |
PATCH | /agent/session | Unified config mutator |
POST | /agent/kill | Kill the agent process |
GET | /agent/status | Status snapshot |
One-shot calls
| Method | Path | Purpose |
|---|---|---|
POST | /agent/run-once | Run once and return result |
POST | /agent/run-once/stream | Run once with SSE events |
POST | /agent/completion | One-shot completion |
Permissions
| Method | Path | Purpose |
|---|---|---|
POST | /agent/permission-request | Submit and wait for approval |
POST | /agent/permission-respond | Approve or deny |
GET | /agent/permission-pending | List pending requests |
Models and events
| Method | Path | Purpose |
|---|---|---|
POST | /agent/list-models | Runtime model introspection |
GET | /agent/events | Session event SSE stream |
Chat (canonical history surface)
| Method | Path | Purpose |
|---|---|---|
GET | /chat/sessions | List chat sessions from DB |
POST | /chat/sessions | Create chat session |
DELETE | /chat/sessions/{id} | Delete chat session |
GET | /chat/sessions/{id}/messages | List messages |
POST | /chat/sessions/{id}/messages | Append message |
DELETE | /chat/sessions/{id}/messages | Clear messages |
GET | /chat/images/{sessionId}/{filename} | Serve an image embed |
Response shape
Most SDK-facing responses are wrapped by server/api-types.ts, while streaming and binary endpoints use their wire-native response bodies. The live OpenAPI document remains the source of truth for exact schemas.
type ApiResponse<T> =
| { status: "ok"; data: T }
| { status: "error"; message: string; code?: string };