anthrogo serve — HTTP API Reference¶
anthrogo serve starts a long-lived HTTP daemon that exposes the anthrogo engine as a REST/SSE API. All endpoints return JSON. Streaming chat responses use Server-Sent Events (SSE).
Starting the server¶
anthrogo serve --addr 127.0.0.1:8765
Flags¶
| Flag | Default | Description |
|---|---|---|
--addr |
127.0.0.1:8765 |
TCP address to listen on |
--token |
(none) | Optional Bearer auth token. When set, all routes require Authorization: Bearer <token> |
--cors-origin |
(none) | Value for Access-Control-Allow-Origin response header |
--sessions-dir |
(default ~/.anthrogo) | Override session storage root |
--model |
from settings.yaml | Model alias |
--provider |
from settings.yaml | Provider profile name |
Authentication¶
When --token is set every request must include:
Authorization: Bearer <token>
Requests without or with a wrong token receive 401 Unauthorized.
Endpoints¶
GET /v1/health¶
Returns server status.
curl http://127.0.0.1:8765/v1/health
Response:
{
"ok": true,
"version": "0.13.13-dev",
"uptime_seconds": 42.1,
"in_flight_chats": 0
}
POST /v1/chat¶
Send a message to a session. Sessions are lazily created on the first request.
Request body¶
{
"session_id": "my-session",
"prompt": "What is the capital of France?",
"stream": false
}
| Field | Type | Required | Description |
|---|---|---|---|
session_id |
string | yes | Identifies the conversation. Engines are cached per session (LRU, max 32). |
prompt |
string | yes | The user message to submit. |
stream |
bool | no | When true, response is SSE. When false (default), response is sync JSON. |
Sync response (stream: false)¶
curl -X POST http://127.0.0.1:8765/v1/chat \
-H 'Content-Type: application/json' \
-d '{"session_id":"s1","prompt":"Hello","stream":false}'
{
"session_id": "s1",
"text": "Hello! How can I help you today?"
}
Streaming response (stream: true)¶
curl -X POST http://127.0.0.1:8765/v1/chat \
-H 'Content-Type: application/json' \
-d '{"session_id":"s1","prompt":"Write a haiku","stream":true}'
Each line is a standard SSE data: frame containing a JSON object:
data: {"type":"delta","text":"Autumn leaves fall slow"}
data: {"type":"delta","text":"\nSilence fills the morning air"}
data: {"type":"done"}
SSE event types:
| Type | Fields | Description |
|---|---|---|
delta |
text |
Partial assistant text |
tool_use |
tool_name, tool_use_id |
Tool call started |
tool_result |
tool_use_id |
Tool call result |
done |
— | Turn complete |
error |
error |
Error occurred |
GET /v1/sessions¶
List up to 100 sessions sorted by modification time (most recent first).
curl http://127.0.0.1:8765/v1/sessions
[
{"id": "550e8400-e29b-41d4-a716-446655440000", "mtime": "2026-05-21T14:00:00Z"},
{"id": "7e2d4c8a-1f3b-4e5d-9a2c-123456789abc", "mtime": "2026-05-21T13:45:00Z"}
]
GET /v1/sessions/{id}¶
Return full JSONL records for a session as a JSON array.
curl http://127.0.0.1:8765/v1/sessions/550e8400-e29b-41d4-a716-446655440000
Returns an array of session records (same schema as the .jsonl files under ~/.anthrogo/projects/).
Errors: 404 when the session ID is not found.
DELETE /v1/sessions/{id}¶
Delete a session file. Returns 204 No Content on success.
curl -X DELETE http://127.0.0.1:8765/v1/sessions/550e8400-e29b-41d4-a716-446655440000
Errors: 404 when the session ID is not found.
GET /v1/tools¶
List all registered tools with their names, descriptions, and input schemas.
curl http://127.0.0.1:8765/v1/tools
[
{
"name": "Bash",
"description": "Execute a bash command",
"schema": {"type": "object", "properties": {"command": {"type": "string"}}}
}
]
Concurrency model¶
- One global
tool.Registryandpermissions.Contextis shared across all sessions. - Each session gets a lazily-created
*query.Engine, cached in async.RWMutex-guarded map capped at 32 sessions. - When the cap is reached the least-recently-used session (oldest
lastAccesstimestamp) is evicted; its engine is discarded but its JSONL file on disk is unaffected. - Each
/v1/chatrequest is bound to the HTTP request'scontext.Context, so disconnects cancel the in-flight engine turn immediately.
Authenticated example¶
anthrogo serve --addr 127.0.0.1:8765 --token mysecret &
curl -H 'Authorization: Bearer mysecret' \
http://127.0.0.1:8765/v1/health