HTTP Gateway Reference

Complete reference for all HTTP endpoints, authentication, and rate limiting

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.

Request

{
  "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.

Related

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