Skip to main content

HTTP API Overview

FlowLayer exposes a minimal HTTP surface for session access.

API availability​

The HTTP API exists only when a session bind is active:

  • CLI: -s <bind>
  • server config: session.bind

If no effective bind is resolved, the server still runs orchestration but does not expose session HTTP routes.

Authentication model​

All routes require:

Authorization: Bearer <token>

Responses:

  • missing header: 401 Unauthorized
  • invalid token: 403 Forbidden

Current endpoint surface​

MethodPathPurpose
GET/healthSession health check ({"ok": true})
GET/wsWebSocket upgrade endpoint for protocol commands/events

There are no REST action endpoints in the current API.

Runtime interaction model​

Runtime operations use WebSocket protocol messages on /ws:

  • commands from client to server
  • ack and result responses
  • async events (hello, snapshot, service_status, log)

See Protocol Overview, Logs, and Actions.

Example checks​

Health:

curl -H "Authorization: Bearer <token>" http://127.0.0.1:6999/health

WebSocket upgrade (example tooling):

wscat -H "Authorization: Bearer <token>" -c ws://127.0.0.1:6999/ws