REST API

Overview

The REST server is implemented in seshat-ai/cmd/api and seshat-ai/internal/api. The API layer stays thin on purpose: middleware, auth, route registration, JSON bodies, SSE framing, and error mapping live there, while the real business and runtime logic lives in backend domain services and the Seshat SDK adapter.

The Two REST Surfaces

Authentication Model

The native API uses bearer auth for most protected routes, and the backend accepts both JWTs and Seshat API keys with the sk- prefix. The Anthropic-compatible path additionally accepts the native x-api-key header because that is what Claude SDK clients expect.

• POST /api/v1/auth/login and POST /api/v1/auth/register are public entry points.
• Most /api/v1/* routes require Authorization: Bearer ....
• The auth middleware resolves either a JWT principal or an API-key principal depending on the token format.
• Some routes are admin-only through role checks, notably parts of MCP and skill repository management.

curl -X POST http://localhost:8090/api/v1/auth/login   -H 'Content-Type: application/json'   -d '{
    "email": "[email protected]",
    "password": "secret"
  }'

Streaming, Permissions, And SSE

The native stream endpoint is POST /api/v1/query/stream. It returns Server-Sent Events and stays open across long-running agent turns. The API sets X-SSE-Version: 1, sends keepalive comments, and emits structured runtime events alongside text chunks.

curl -N -X POST http://localhost:8090/api/v1/query/stream   -H 'Authorization: Bearer <jwt>'   -H 'Content-Type: application/json'   -d '{
    "prompt": "Inspect the attached corpus and summarize the key risks.",
    "session_id": "sess_123",
    "corpus_id": "corp_456",
    "agent_slug": "risk-analyst"
  }'

One important backend-specific feature is that permission requests and non-confirm prompts are bridged through SSE. That means web or desktop clients can stay connected to one stream and still react to runtime permission gates without reimplementing the loop themselves.

Endpoint Catalog

The router in internal/api/routes.go currently groups the backend into the following main families.

Anthropic-Compatible Messages API

The compatibility layer exists so existing Claude-oriented clients can point their base URL at Seshat and still use the backend as the execution engine. The request format is Anthropic-style, but the actual tool use, permissions, memory, and provider routing remain server-side in Seshat.

• The compatible path is POST /v1/messages.
• It accepts either x-api-key or Authorization: Bearer.
• x-seshat-session-id binds the request to an existing backend session for multi-turn continuity.
• x-seshat-provider-setting-id lets the client override which provider setting the backend should use.
• Runtime events are intentionally not forwarded in Anthropic mode because the protocol has no equivalent for Seshat-specific tool progress or permission events.

curl -N -X POST http://localhost:8090/v1/messages   -H 'x-api-key: <seshat-api-key>'   -H 'x-seshat-session-id: sess_123'   -H 'x-seshat-provider-setting-id: pset_456'   -H 'Content-Type: application/json'   -d '{
    "model": "anthropic:claude-sonnet-4-20250514",
    "max_tokens": 2048,
    "stream": true,
    "messages": [
      {"role": "user", "content": "Review the project status and propose next actions."}
    ]
  }'

If you want the protobuf-first alternative instead of HTTP compatibility, continue with gRPC API.

Operational Notes

The HTTP server configuration is intentionally SSE-friendly. The backend disables global write timeout for the API server, enables optional localhost-oriented CORS in debug mode, assigns request IDs, caps most JSON bodies to 4 MB, and treats panic recovery as transport middleware rather than app logic.

For the backend package map behind this API, see [architecture.md](/home/amiche/Projects/AI/ai/seshat-ai/docs/architecture.md:1). For the runtime side it calls into, see Mono-Run Architecture.