HTTP Gateway Reference

What this is for: every HTTP route the daemon exposes — JSON-RPC, REST API for the dashboard, experimental OpenAI-shaped endpoints, webhooks, media, and SSE. Who it’s for: anyone integrating an external system with Comis or building tools on top of the daemon. Complete reference for the Comis HTTP gateway. The gateway serves HTTP endpoints, WebSocket connections, and optionally a web dashboard. Default port: 4766. All endpoints require authentication unless noted otherwise. The gateway is implemented with Hono and lives in packages/gateway/src/server/hono-server.ts. Companion routes are wired in packages/daemon/src/wiring/setup-gateway-routes.ts (experimental /v1 routes, media, and webhook mappings).

Authentication

The gateway supports four authentication methods depending on the endpoint type.

Bearer Token

The primary authentication method. Pass a token configured in gateway.tokens[] via the Authorization header.

curl -H "Authorization: Bearer your-token" http://localhost:4766/api/agents

Tokens are configured with scopes that determine which endpoints and JSON-RPC methods the client can access.

WebSocket Query Parameter

WebSocket clients that cannot set custom headers may pass the token as a query parameter. SSE endpoints require the Authorization header and reject ?token= credentials.

# WebSocket
wscat -c "ws://localhost:4766/ws?token=your-token"

Query parameter tokens can appear in server access logs. Prefer a WebSocket client that supports the Authorization header.

HMAC Signature

The webhook endpoint (/hooks/webhook) authenticates requests using an HMAC signature. The signature is computed over the request body and verified against a shared secret. The HMAC algorithm is configurable (defaults to SHA-256).

mTLS

Optional TLS client certificate verification. When gateway.tls.requireClientCert is true, the server requires clients to present a valid certificate signed by the configured CA.

Rate Limiting

The gateway applies rate limiting at multiple levels to protect against abuse.

Global HTTP rate limiter applies to all HTTP endpoints except /health and /api/health. Configured via gateway.rateLimit.
Per-connection WebSocket rate limiting uses a sliding window to limit messages per connection. Configured via gateway.wsMessageRateLimit.maxMessages and gateway.wsMessageRateLimit.windowMs.
Body size limit on POST endpoints (default: 1 MB). Configured via gateway.httpBodyLimitBytes.

For detailed rate limiting configuration, see Rate Limiting.

Core Routes

These routes are always available when the gateway is running.

Method	Path	Auth	Description
GET	`/health`	None	Health check endpoint. Returns `{ status: "ok", timestamp: "..." }`. Rate-limit exempt.
GET	`/ws`	Bearer / query param	WebSocket upgrade for JSON-RPC 2.0 communication. See WebSocket Protocol.
POST	`/hooks/webhook`	HMAC signature	Webhook endpoint. Only mounted when webhook configuration is provided.
GET	`/`	None	Redirects to `/app/` when the web dashboard is enabled.

REST API

The REST API is mounted at /api and provides HTTP endpoints for the web dashboard. These endpoints are available when gateway.web.enabled is true (the default).

REST API endpoints are available when the web dashboard is enabled. All authenticated REST API endpoints require at least the rpc scope.

Method	Path	Auth	Description
GET	`/api/health`	None	API health check. Rate-limit exempt.
GET	`/api/agents`	Bearer (`rpc`)	Agent configuration list with ID, name, provider, and model.
GET	`/api/channels`	Bearer (`rpc`)	Enabled channel connection status.
GET	`/api/activity`	Bearer (`rpc`)	Recent activity events from the ring buffer. Accepts `?limit=` (1-100, default 50).
GET	`/api/memory/search`	Bearer (`rpc`)	Memory search. Requires `?q=` query. Accepts `?limit=` (1-100, default 10).
GET	`/api/memory/stats`	Bearer (`rpc`)	Memory statistics (entry counts, index info).
GET	`/api/chat/history`	Bearer (`rpc`)	Chat session history. Accepts `?channelId=` to filter by channel.
POST	`/api/chat`	Bearer (`rpc`)	Execute an agent turn. Requires JSON body.

POST /api/chat

Execute an agent turn with the following request body.

{
  "message": "What is the weather today?",
  "agentId": "default",
  "sessionKey": "web-session-1"
}

{
  "response": "I don't have access to real-time weather data...",
  "tokensUsed": {
    "input": 142,
    "output": 87,
    "total": 229
  },
  "finishReason": "stop"
}

Field	Type	Required	Description
`message`	`string`	Yes	The user message to process.
`agentId`	`string`	No	Target agent ID. Uses default agent if omitted.
`sessionKey`	`string`	No	Session key for conversation continuity.
`locale`	`string`	No	Request-tier response locale as a canonical BCP-47 tag (`"he"`, `"pt-BR"`). A non-canonical or invalid tag is rejected with `400`. When the message text is written in a script that contradicts this locale, the conversation’s script wins.

SSE Endpoints

Server-Sent Events (SSE) endpoints provide real-time streaming. Both endpoints require an Authorization: Bearer ... header and at least the rpc scope. Query-string credentials are rejected so tokens never need to enter a URL. A narrowly-scoped mcp-client token is rejected with 403 because the event stream carries cross-session data and can drive agent turns.

Method	Path	Auth	Description
GET	`/api/events`	Bearer (`rpc`)	SSE stream of system events (messages, sessions, skills, scheduler, approvals, graphs).
POST	`/api/chat/stream`	Bearer (`rpc`)	Streaming chat via SSE. Requires an application/json body with `message` and optional `agentId`.

# System event stream
curl -N -H "Authorization: Bearer your-token" \
  http://localhost:4766/api/events

# Streaming chat without placing the prompt in the URL
curl -N -X POST \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  --data '{"message":"Hello","agentId":"default"}' \
  http://localhost:4766/api/chat/stream

SSE Connection Lifecycle

The /api/events endpoint streams system events as they occur. The server sends periodic keep-alive pings (every 15 seconds) to maintain the connection. If the connection drops, clients should reconnect using the retry directive (default: 3 seconds). Event types are organized by category: Messages: message:received, message:sent, message:streaming Sessions: session:created, session:expired, session:sub_agent_spawned, session:sub_agent_completed, session:sub_agent_archived, session:sub_agent_spawn_rejected, session:sub_agent_spawn_started, session:sub_agent_spawn_queued, session:sub_agent_lifecycle_ended Security: audit:event, security:injection_detected, security:injection_rate_exceeded, security:memory_tainted, security:warn, secret:accessed, secret:modified Skills: skill:executed, skill:rejected, skill:loaded, skill:registry_reset Observability: observability:metrics, observability:token_usage, observability:reset Scheduler: scheduler:cron_execution_started, scheduler:cron_execution_terminal, scheduler:heartbeat_wake_admitted, scheduler:heartbeat_wake_deferred, scheduler:heartbeat_wake_terminal, scheduler:heartbeat_alert The three heartbeat wake events share a correlationId. Admission reports the retained target, lane, reason, and disposition; deferral adds the next eligible time and a closed reason; terminal reports the final status, duration, event-entry count, and optional error or cancellation category. scheduler:heartbeat_alert is a separate health signal and is not part of the correlated wake lifecycle. Approvals: approval:requested, approval:resolved Graphs: graph:started, graph:node_updated, graph:completed Config: config:patched Diagnostics: diagnostic:channel_health, diagnostic:billing_snapshot Models: model:catalog_loaded, model:fallback_attempt, model:fallback_exhausted, model:auth_cooldown Providers: provider:degraded, provider:recovered Agents: agent:hot_added, agent:hot_removed Channels: channel:registered, channel:deregistered System: system:error

SSE Chat Streaming

The /api/chat/stream endpoint accepts { "message": string, "agentId"?: string, "locale"?: string } as its JSON request body (locale is a canonical BCP-47 tag, rejected with 400 when invalid — same semantics as POST /api/chat). It sends incremental token deltas as token events, followed by a final done event with the complete response. The same configured HTTP body-size ceiling used by other chat POST endpoints is enforced before JSON parsing.

event: token
data: {"delta": "Hello", "accumulated": "Hello"}

event: token
data: {"delta": " world", "accumulated": "Hello world"}

event: done
data: {"response": "Hello world", "tokensUsed": {...}, "finishReason": "stop"}

Experimental OpenAI-shaped endpoints

These routes implement selected request and response shapes associated with OpenAI endpoints. They are experimental and are not a general OpenAI client, SDK, or drop-in compatibility guarantee. Validate the exact fields and behavior your integration needs against the endpoint reference.

Method	Path	Auth	Description
POST	`/v1/chat/completions`	Bearer	ChatCompletion endpoint (streaming and non-streaming).
GET	`/v1/models`	Bearer	List available models.
GET	`/v1/models/:model_id`	Bearer	Get a specific model.
POST	`/v1/embeddings`	Bearer	Generate text embeddings.
POST	`/v1/responses`	Bearer	OpenResponses format (streaming and non-streaming).

For the implemented subset, see Experimental OpenAI-shaped API.

Media Routes

Media routes serve stored media files (images, audio, video, documents). Authentication is optional and depends on gateway configuration; when a token store is configured, requests require at least the rpc scope (a narrowly-scoped mcp-client token is rejected with 403).

Method	Path	Auth	Description
GET	`/media/:id`	Bearer (`rpc`, optional)	Serve a media file with correct Content-Type. Returns 404 if not found, 410 if expired (TTL-based).
GET	`/media/:id/meta`	Bearer (`rpc`, optional)	JSON metadata for a media file (content type, saved timestamp, size).

Media IDs are validated against a safe character pattern (letters, digits, dots, hyphens, underscores) to prevent path traversal. Content types are resolved from sidecar .meta files or file extension fallback.

Static Files

When the web dashboard is enabled and a webDistPath is configured, the gateway serves the single-page application.

Method	Path	Auth	Description
GET	`/app/*`	None	Web dashboard SPA files. No authentication required for static assets.

JSON-RPC Methods

All JSON-RPC methods available over WebSocket and HTTP

WebSocket Protocol

WebSocket connection protocol, heartbeat, and error handling

Experimental OpenAI-Shaped API

Implemented request and response shapes for the experimental /v1 routes

Rate Limiting

Rate limiting configuration and behavior

CLI

Configuration

Security

Gateway and APIs

HTTP Gateway Reference

Authentication

Bearer Token

WebSocket Query Parameter

HMAC Signature

mTLS

Rate Limiting

Core Routes

REST API

POST /api/chat

SSE Endpoints

SSE Connection Lifecycle

SSE Chat Streaming

Experimental OpenAI-shaped endpoints

Media Routes

Static Files

JSON-RPC Methods

WebSocket Protocol

Experimental OpenAI-Shaped API

Rate Limiting

​Authentication

​Bearer Token

​WebSocket Query Parameter

​HMAC Signature

​mTLS

​Rate Limiting

​Core Routes

​REST API

​POST /api/chat

​SSE Endpoints

​SSE Connection Lifecycle

​SSE Chat Streaming

​Experimental OpenAI-shaped endpoints

​Media Routes

​Static Files

​Related

JSON-RPC Methods

WebSocket Protocol

Experimental OpenAI-Shaped API

Rate Limiting

Authentication

Bearer Token

WebSocket Query Parameter

HMAC Signature

mTLS

Rate Limiting

Core Routes

REST API

POST /api/chat

SSE Endpoints

SSE Connection Lifecycle

SSE Chat Streaming

Experimental OpenAI-shaped endpoints

Media Routes

Static Files

Related