API Server

The API server exposes your Claway agent as an OpenAI-compatible HTTP API. Any client that speaks the OpenAI format (n8n's OpenAI Chat Model and AI Agent nodes, Open WebUI, LobeChat, LibreChat, the OpenAI SDKs, ...) can use the agent as if it were a model.

The agent answers with its full toolset (web search, files, memory, skills, terminal) and returns the final response. When streaming, tool progress appears inline so clients can show what the agent is doing.

On a Claway Box or hosted Claway

In OPS, open Connectors → API server, run the setup wizard and set the API key: at least 16 random characters (for example the output of openssl rand -hex 32). It is stored as API_SERVER_KEY; the API server does not start without a strong key.
Leave the listener host at 127.0.0.1 and the port at 8642. The address in front forwards /v1/ to it without the OPS login, and the API server checks the Bearer key on every /v1/* call.

Where Claway runs	Base URL
Claway Box	`https://<box>/v1`
Hosted Claway	`http://<server-ip>:8443/v1`

While the connector is off, the base URL answers 503 {"error": "connector_not_enabled", ...}.

curl -k https://<box>/v1/chat/completions \
  -H "Authorization: Bearer $API_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claway", "messages": [{"role": "user", "content": "Hello!"}]}'

(-k accepts the Box's self-signed certificate; on hosted Claway use http://<server-ip>:8443/v1/... without -k.)

Only the /v1/* endpoints are reachable through that address. The Jobs and Sessions APIs under /api/ and the /health endpoints are served on the machine itself (http://127.0.0.1:8642); use /v1/health from outside.

n8n

OpenAI Chat Model / AI Agent nodes: create an OpenAI credential with API Key = your API_SERVER_KEY and Base URL = https://<box>/v1 (hosted: http://<server-ip>:8443/v1). Pick the model the node lists (claway, or your profile name).
HTTP Request node: POST https://<box>/v1/chat/completions with Authorization: Bearer <API_SERVER_KEY>.
Box certificate: the Box's certificate is self-signed. The HTTP Request node has Ignore SSL Issues; for the OpenAI credential, start n8n with NODE_EXTRA_CA_CERTS pointing at the Box certificate (or, on a trusted LAN only, NODE_TLS_REJECT_UNAUTHORIZED=0).
For a plain "send a message, get the answer" call without the OpenAI shape, use the webhook connector's built-in agent route.

On your own install

1. Enable the API server

Add to ~/.claway/.env:

API_SERVER_ENABLED=true
API_SERVER_KEY=<16+ random characters>
# Optional: only if a browser must call Claway directly
# API_SERVER_CORS_ORIGINS=http://localhost:3000

2. Start the gateway

claway gateway

You'll see:

[API Server] API server listening on http://127.0.0.1:8642

3. Connect a client

Point any OpenAI-compatible client at http://localhost:8642/v1:

curl http://localhost:8642/v1/chat/completions \
  -H "Authorization: Bearer $API_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claway", "messages": [{"role": "user", "content": "Hello!"}]}'

Or connect Open WebUI, LobeChat, or any other frontend; see the Open WebUI integration guide for step-by-step instructions.

Endpoints

POST /v1/chat/completions

Standard OpenAI Chat Completions format. Stateless — the full conversation is included in each request via the messages array.

Request:

{
  "model": "claway",
  "messages": [
    {"role": "system", "content": "You are a Python expert."},
    {"role": "user", "content": "Write a fibonacci function"}
  ],
  "stream": false
}

Response:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "claway",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Here's a fibonacci function..."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 50, "completion_tokens": 200, "total_tokens": 250}
}

Inline image input: user messages may send content as an array of text and image_url parts. Both remote http(s) URLs and data:image/... URLs are supported:

{
  "model": "claway",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What is in this image?"},
        {"type": "image_url", "image_url": {"url": "https://example.com/cat.png", "detail": "high"}}
      ]
    }
  ]
}

Uploaded files (file / input_file / file_id) and non-image data: URLs return 400 unsupported_content_type.

Streaming ("stream": true): Returns Server-Sent Events (SSE) with token-by-token response chunks. For Chat Completions, the stream uses standard chat.completion.chunk events plus Claway's custom claway.tool.progress event for tool-start UX. For Responses, the stream uses OpenAI Responses event types such as response.created, response.output_text.delta, response.output_item.added, response.output_item.done, and response.completed.

Tool progress in streams:

Chat Completions: Claway emits event: claway.tool.progress for tool-start visibility without polluting persisted assistant text.
Responses: Claway emits spec-native function_call and function_call_output output items during the SSE stream, so clients can render structured tool UI in real time.

POST /v1/responses

OpenAI Responses API format. Supports server-side conversation state via previous_response_id — the server stores full conversation history (including tool calls and results) so multi-turn context is preserved without the client managing it.

Request:

{
  "model": "claway",
  "input": "What files are in my project?",
  "instructions": "You are a helpful coding assistant.",
  "store": true
}

Response:

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "claway",
  "output": [
    {"type": "function_call", "name": "terminal", "arguments": "{\"command\": \"ls\"}", "call_id": "call_1"},
    {"type": "function_call_output", "call_id": "call_1", "output": "README.md src/ tests/"},
    {"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "Your project has..."}]}
  ],
  "usage": {"input_tokens": 50, "output_tokens": 200, "total_tokens": 250}
}

Inline image input: input[].content can contain input_text and input_image parts. Both remote URLs and data:image/... URLs are supported:

{
  "model": "claway",
  "input": [
    {
      "role": "user",
      "content": [
        {"type": "input_text", "text": "Describe this screenshot."},
        {"type": "input_image", "image_url": "data:image/png;base64,iVBORw0K..."}
      ]
    }
  ]
}

Uploaded files (input_file / file_id) and non-image data: URLs return 400 unsupported_content_type.

Multi-turn with previous_response_id

Chain responses to maintain full context (including tool calls) across turns:

{
  "input": "Now show me the README",
  "previous_response_id": "resp_abc123"
}

The server reconstructs the full conversation from the stored response chain — all previous tool calls and results are preserved. Chained requests also share the same session, so multi-turn conversations appear as a single entry in the dashboard and session history.

Named conversations

Use the conversation parameter instead of tracking response IDs:

{"input": "Hello", "conversation": "my-project"}
{"input": "What's in src/?", "conversation": "my-project"}
{"input": "Run the tests", "conversation": "my-project"}

The server automatically chains to the latest response in that conversation. Like the /title command for gateway sessions.

GET /v1/responses/{id}

Retrieve a previously stored response by ID.

DELETE /v1/responses/{id}

Delete a stored response.

GET /v1/models

Lists the agent as an available model. The advertised model name defaults to the profile name (or claway for the default profile). Required by most frontends for model discovery.

GET /v1/capabilities

Returns a machine-readable description of the API server's stable surface for external UIs, orchestrators, and plugin bridges.

{
  "object": "claway.api_server.capabilities",
  "platform": "claway",
  "model": "claway",
  "auth": {"type": "bearer", "required": true},
  "features": {
    "chat_completions": true,
    "responses_api": true,
    "run_submission": true,
    "run_status": true,
    "run_events_sse": true,
    "run_stop": true
  }
}

Use this endpoint when integrating dashboards, browser UIs, or control planes so they can discover whether the running Claway version supports runs, streaming, cancellation, and session continuity without depending on private Python internals.

GET /health

Health check. Returns {"status": "ok"}. Also available at GET /v1/health for OpenAI-compatible clients that expect the /v1/ prefix.

GET /health/detailed

Extended health check that also reports active sessions, running agents, and resource usage. Useful for monitoring/observability tooling.

Runs API (streaming-friendly alternative)

In addition to /v1/chat/completions and /v1/responses, the server exposes a runs API for long-form sessions where the client wants to subscribe to progress events instead of managing streaming themselves.

POST /v1/runs

Create a new agent run. Returns a run_id that can be used to subscribe to progress events.

{
  "run_id": "run_abc123",
  "status": "started"
}

Runs accept a simple input string and optional session_id, instructions, conversation_history, or previous_response_id. When session_id is provided, Claway surfaces it in the run status so external UIs can correlate runs with their own conversation IDs.

GET /v1/runs/{run_id}

Poll the current run state. This is useful for dashboards that need status without holding an SSE connection open, or for UIs that reconnect after navigation.

{
  "object": "claway.run",
  "run_id": "run_abc123",
  "status": "completed",
  "session_id": "space-session",
  "model": "claway",
  "output": "Done.",
  "usage": {"input_tokens": 50, "output_tokens": 200, "total_tokens": 250}
}

Statuses are retained briefly after terminal states (completed, failed, or cancelled) for polling and UI reconciliation.

GET /v1/runs/{run_id}/events

Server-Sent Events stream of the run's tool-call progress, token deltas, and lifecycle events. Designed for dashboards and thick clients that want to attach/detach without losing state.

POST /v1/runs/{run_id}/stop

Interrupt a running agent turn. The endpoint returns immediately with {"status": "stopping"} while Claway asks the active agent to stop at the next safe interruption point.

POST /v1/runs/{run_id}/approval

Resolve a pending approval for a run that is waiting on a human decision (for example, a tool call gated behind an approval policy). The body carries the approval decision; the run resumes once the decision is recorded. This endpoint is advertised in /v1/capabilities as the run_approval feature so external UIs can detect support before surfacing an approval prompt.

Jobs API (background scheduled work)

The server exposes a lightweight jobs CRUD surface for managing scheduled / background agent runs from a remote client. All endpoints are gated behind the same bearer auth.

GET /api/jobs

List all scheduled jobs.

POST /api/jobs

Create a new scheduled job. Body accepts the same shape as claway cron — prompt, schedule, skills, provider override, delivery target.

GET /api/jobs/{job_id}

Fetch a single job's definition and last-run state.

PATCH /api/jobs/{job_id}

Update fields on an existing job (prompt, schedule, etc.). Partial updates are merged.

DELETE /api/jobs/{job_id}

Remove a job. Also cancels any in-flight run.

POST /api/jobs/{job_id}/pause

Pause a job without deleting it. Next-scheduled-run timestamps are suspended until resumed.

POST /api/jobs/{job_id}/resume

Resume a previously paused job.

POST /api/jobs/{job_id}/run

Trigger the job to run immediately, out of schedule.

Sessions API (session control over REST)

External UIs can manage Claway sessions over REST without standing up the dashboard. All endpoints are gated by API_SERVER_KEY and live under /api/sessions/*.

Method	Path	Description
`GET`	`/api/sessions`	List sessions (paginated — `limit`, `offset`, `source`, `include_children`)
`POST`	`/api/sessions`	Create an empty session
`GET`	`/api/sessions/{id}`	Read session metadata
`PATCH`	`/api/sessions/{id}`	Update title or `end_reason`
`DELETE`	`/api/sessions/{id}`	Delete a session
`GET`	`/api/sessions/{id}/messages`	Message history for a session
`POST`	`/api/sessions/{id}/fork`	Branch the session via `SessionDB` lineage (matches CLI `/branch` semantics)
`POST`	`/api/sessions/{id}/chat`	Run one synchronous agent turn
`POST`	`/api/sessions/{id}/chat/stream`	SSE wrapper over a single turn — emits `assistant.delta`, `tool.started`, `tool.completed`, `run.completed` events

/v1/capabilities advertises the full surface via session_* feature flags and endpoints.session_* entries so external UIs can detect support and fall back safely. Inline images are supported in chat and chat/stream payloads (multimodal-aware path).

# fork a session and run one turn
curl -X POST http://localhost:8642/api/sessions/$ID/fork \
  -H "Authorization: Bearer $API_SERVER_KEY" \
  -d '{"title": "explore alt path"}'

# stream a turn over SSE
curl -N -X POST http://localhost:8642/api/sessions/$ID/chat/stream \
  -H "Authorization: Bearer $API_SERVER_KEY" \
  -d '{"input": "what files changed in the last hour?"}'

Skills and toolsets discovery

GET /v1/skills and GET /v1/toolsets let external clients enumerate the agent's capabilities deterministically over REST instead of asking the model. Both are read-only and gated by API_SERVER_KEY.

curl http://localhost:8642/v1/skills \
  -H "Authorization: Bearer $API_SERVER_KEY"
# → [{"name": "github-pr-workflow", "description": "...", "category": "..."}, ...]

curl http://localhost:8642/v1/toolsets \
  -H "Authorization: Bearer $API_SERVER_KEY"
# → [{"name": "core", "label": "...", "description": "...", "enabled": true,
#     "configured": true, "tools": ["read_file", "write_file", ...]}, ...]

/v1/skills returns the same metadata the skills hub uses internally. /v1/toolsets returns toolsets resolved for the api_server platform with the concrete tools list each one expands to. Both are advertised under endpoints.* in /v1/capabilities.

Long-term memory scoping (`X-Claway-Session-Key`)

Multi-user frontends like Open WebUI need a stable per-channel identifier for long-term memory (Honcho, etc.) that is independent of the transcript-scoped X-Claway-Session-Id (which rotates on /new). Pass X-Claway-Session-Key on /v1/chat/completions, /v1/responses, or /v1/runs and Claway threads it through to AIAgent(gateway_session_key=...), where the Honcho memory provider uses it to derive a stable scope.

POST /v1/chat/completions HTTP/1.1
Authorization: Bearer ***
X-Claway-Session-Id: transcript-alpha
X-Claway-Session-Key: agent:main:webui:dm:user-42

Rules: max 256 chars, control characters (\r, \n, \x00) are rejected, and the value is echoed back on responses (JSON + SSE). /v1/capabilities advertises support via "session_key_header": "X-Claway-Session-Key". Without the key, Honcho's per-session strategy produces a different scope per session_id — exactly the behavior Claway had before.

System Prompt Handling

When a frontend sends a system message (Chat Completions) or instructions field (Responses API), claway layers it on top of its core system prompt. Your agent keeps all its tools, memory, and skills — the frontend's system prompt adds extra instructions.

This means you can customize behavior per-frontend without losing capabilities:

Open WebUI system prompt: "You are a Python expert. Always include type hints."
The agent still has terminal, file tools, web search, memory, etc.

Authentication

Bearer token auth via the Authorization header:

Authorization: Bearer ***

Configure the key via API_SERVER_KEY env var. If you need a browser to call Claway directly, also set API_SERVER_CORS_ORIGINS to an explicit allowlist.

Security

The API server gives full access to claway's toolset, including terminal commands. API_SERVER_KEY is required for every deployment, including the default loopback bind on 127.0.0.1. Keep API_SERVER_CORS_ORIGINS narrow to control browser access when you explicitly allow browser callers.

Configuration

Environment Variables

Variable	Default	Description
`API_SERVER_ENABLED`	`false`	Enable the API server
`API_SERVER_PORT`	`8642`	HTTP server port
`API_SERVER_HOST`	`127.0.0.1`	Bind address (localhost only by default)
`API_SERVER_KEY`	(required)	Bearer token for auth; at least 16 characters and not a placeholder, or the server refuses to start
`API_SERVER_CORS_ORIGINS`	(none)	Comma-separated allowed browser origins
`API_SERVER_MODEL_NAME`	(profile name)	Model name on `/v1/models`. Defaults to profile name, or `claway` for default profile.

config.yaml

The same settings can also go under platforms.api_server in config.yaml (enabled, and port, host, cors_origins, model_name under extra). Environment variables win over config.yaml. Keep the key itself in .env: it is a secret.

platforms:
  api_server:
    enabled: true
    extra:
      port: 8642
      host: 127.0.0.1

Security Headers

All responses include security headers:

X-Content-Type-Options: nosniff — prevents MIME type sniffing
Referrer-Policy: no-referrer — prevents referrer leakage

CORS

The API server does not enable browser CORS by default.

For direct browser access, set an explicit allowlist:

API_SERVER_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

When CORS is enabled:

Preflight responses include Access-Control-Max-Age: 600 (10 minute cache)
SSE streaming responses include CORS headers so browser EventSource clients work correctly
Idempotency-Key is an allowed request header — clients can send it for deduplication (responses are cached by key for 5 minutes)

Most documented frontends such as Open WebUI connect server-to-server and do not need CORS at all.

Compatible Frontends

Any client that supports the OpenAI API format works, for example:

Frontend	Connection
Open WebUI	Full guide available
LobeChat	Custom provider endpoint
LibreChat	Custom endpoint in librechat.yaml
AnythingLLM	Generic OpenAI provider
NextChat	BASE_URL env var
ChatBox	API Host setting
Jan	Remote model config
HF Chat-UI	OPENAI_BASE_URL
big-AGI	Custom endpoint
n8n	OpenAI credential with a custom Base URL, see n8n
OpenAI Python SDK	`OpenAI(base_url="https://<box>/v1", api_key=...)`
curl	Direct HTTP requests

Multi-User Setup with Profiles

To give multiple users their own isolated Claway instance (separate config, memory, skills), use profiles:

# Create a profile per user
claway profile create alice
claway profile create bob

# Configure each profile's API server on a different port. API_SERVER_* are env
# vars, so write them to each profile's .env (keys: 16+ random characters):
cat >> ~/.claway/profiles/alice/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8650
API_SERVER_KEY=$(openssl rand -hex 32)
EOF

cat >> ~/.claway/profiles/bob/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8651
API_SERVER_KEY=$(openssl rand -hex 32)
EOF

# Start each profile's gateway
claway -p alice gateway &
claway -p bob gateway &

Each profile's API server automatically advertises the profile name as the model ID:

http://localhost:8650/v1/models → model alice
http://localhost:8651/v1/models → model bob

In Open WebUI, add each as a separate connection. The model dropdown shows alice and bob as distinct models, each backed by a fully isolated Claway instance. See the Open WebUI guide for details.

Limitations

Response storage — stored responses (for previous_response_id) are persisted in SQLite and survive gateway restarts. Max 100 stored responses (LRU eviction).
No file upload — inline images are supported on both /v1/chat/completions and /v1/responses, but uploaded files (file, input_file, file_id) and non-image document inputs are not supported through the API.
Model field is cosmetic — the model field in requests is accepted but the actual LLM model used is configured server-side in config.yaml.

Proxy Mode

The API server also serves as the backend for gateway proxy mode. When another Claway gateway instance is configured with GATEWAY_PROXY_URL pointing at this API server, it forwards all messages here instead of running its own agent. This enables split deployments — for example, a Docker container handling Matrix E2EE that relays to a host-side agent.

See Matrix Proxy Mode for the full setup guide.

On a Claway Box or hosted Claway​

n8n​

On your own install​

1. Enable the API server​

2. Start the gateway​

3. Connect a client​

Endpoints​

POST /v1/chat/completions​

POST /v1/responses​

Multi-turn with previous_response_id​

Named conversations​

GET /v1/responses/{id}​

DELETE /v1/responses/{id}​

GET /v1/models​

GET /v1/capabilities​

GET /health​

GET /health/detailed​

Runs API (streaming-friendly alternative)​

POST /v1/runs​

GET /v1/runs/{run_id}​

GET /v1/runs/{run_id}/events​

POST /v1/runs/{run_id}/stop​

POST /v1/runs/{run_id}/approval​

Jobs API (background scheduled work)​

GET /api/jobs​

POST /api/jobs​

GET /api/jobs/{job_id}​

PATCH /api/jobs/{job_id}​

DELETE /api/jobs/{job_id}​

POST /api/jobs/{job_id}/pause​

POST /api/jobs/{job_id}/resume​

POST /api/jobs/{job_id}/run​

Sessions API (session control over REST)​

Skills and toolsets discovery​

Long-term memory scoping (X-Claway-Session-Key)​

System Prompt Handling​

Authentication​

Configuration​

Environment Variables​

config.yaml​

Security Headers​

CORS​

Compatible Frontends​

Multi-User Setup with Profiles​

Limitations​

Proxy Mode​