API Reference#
The operator UI serves a small HTTP API on port 8600. All request and
response bodies are JSON unless noted. Request bodies are limited to 64 KiB.
Important
The API has no built-in authentication. Restrict network access as described in Configuration.
Health#
GET /health#
Returns 200 while the server is running.
{"status": "ok"}
GET /ready#
Returns 200 once the model is warmed up and the first answer will be fast,
or 503 while warming up.
{"status": "ready"}
Services#
GET /servers#
Lists the store services registered with the agent.
GET /status#
Returns reachability and tool count for each registered service. Results are
cached briefly. Use GET /status?force=1 to recheck now.
{"ok": true, "services": {"weather": {"ok": true, "tools": 2}}}
Chat#
POST /ask/stream#
Asks the agent a question and streams the answer as Server-Sent Events.
Field |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
Up to 4000 characters |
|
string |
No |
Links the question to an event shown in Autonomy Decisions |
curl -N -X POST http://localhost:8600/ask/stream \
-H 'Content-Type: application/json' \
-d '{"question": "What is the current queue count?"}'
Each message is a data: line with a JSON object. delta messages carry
partial text, and the final done message carries the full answer.
POST /ask#
Same request as /ask/stream. Returns the complete answer in one response:
{"ok": true, "answer": "There are 4 customers in the queue..."}
POST /chat/new#
Starts a new conversation. The agent’s memory of operator preferences is kept.
Events#
POST /autonomy/events#
Submits a store event for the agent to evaluate. Returns 202 immediately. The
evaluation runs in the background.
Field |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
Unique ID, up to 200 characters. Resending an ID that was already processed is ignored. Resend a failed ID to retry it |
|
string |
Yes |
Any descriptive name, for example |
|
string |
No |
Name of the producing service, used to learn from operator responses. If missing, it is taken from |
|
string |
No |
Store identifier. If set, must equal the agent’s |
|
string |
No |
ISO 8601 timestamp |
|
object |
No |
Event details. When several MCP servers back one service, |
The whole event must be under 32 KiB.
curl -X POST http://localhost:8600/autonomy/events \
-H 'Content-Type: application/json' \
-d '{
"event_id": "queue-0001",
"event_type": "queue_count_changed",
"service": "kiosk",
"store_id": "qsr-001",
"occurred_at": "2026-10-27T12:00:00Z",
"data": {"queue_count": 12}
}'
{"ok": true, "event_id": "queue-0001", "duplicate": false, "status": "queued"}
GET /autonomy/status#
Returns the event queue and recent decisions. Decision states are queued,
processing, pending, no_action, and failed.
POST /autonomy/proposals/{proposal_id}/approve#
POST /autonomy/proposals/{proposal_id}/reject#
Approves or rejects a pending proposal. Optional body:
Field |
Type |
Description |
|---|---|---|
|
string |
Up to 500 characters. Recorded for learning |
Returns 404 if the proposal does not exist, and 409 if it has expired or
was already decided.
Learning#
GET /learning/status#
Returns services with enough operator responses to learn from, learning progress, and learned rules waiting for review.
POST /learning/run#
Starts learning for one service. Body: {"service": "kiosk"}. Returns 202,
or 409 if the service is not ready or learning is already running.
POST /learning/pending/{id}/approve#
POST /learning/pending/{id}/reject#
Approves or rejects learned rules that are waiting for review.
POST /learning/responses#
Records an operator response that a service observed itself, for example an
action the operator took on the service’s own screen. Returns 201 with the
record ID.
Field |
Type |
Required |
Description |
|---|---|---|---|
|
string |
One of |
An event already sent to |
|
object |
One of |
The full event (same fields as |
|
string |
No |
|
|
string |
No |
What the operator said or the reason, up to 1000 characters |
|
array |
No |
Up to 10 |
|
string |
No |
Idempotency key; resending the same ID adds nothing |
An instruction needs text or tool_calls. Returns 404 for an unknown
event_id without event, and 400 for unregistered tools or invalid fields.
curl -X POST http://localhost:8600/learning/responses \
-H 'Content-Type: application/json' \
-d '{
"event_id": "evt-0001",
"tool_calls": [{"tool": "<service>.<action>", "arguments": {}}],
"response_id": "evt-0001-response"
}'