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

question

string

Yes

Up to 4000 characters

event_id

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

event_id

string

Yes

Unique ID, up to 200 characters. Resending an ID that was already processed is ignored. Resend a failed ID to retry it

event_type

string

Yes

Any descriptive name, for example queue_count_changed

service

string

No

Name of the producing service, used to learn from operator responses. If missing, it is taken from event_type (built-in types, or QSR_EVENT_SERVICES)

store_id

string

No

Store identifier. If set, must equal the agent’s QSR_RESTAURANT_ID (default qsr-001)

occurred_at

string

No

ISO 8601 timestamp

data

object

No

Event details. When several MCP servers back one service, data.venue names the server that owns the event; chat actions on the event go to that server

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

reason

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

event_id

string

One of

An event already sent to POST /autonomy/events

event

object

One of

The full event (same fields as POST /autonomy/events) when the agent never received it

kind

string

No

instruction (default), approved, rejected, or none

text

string

No

What the operator said or the reason, up to 1000 characters

tool_calls

array

No

Up to 10 {"tool": "<service.action>", "arguments": {...}} naming action tools of a connected MCP service

response_id

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"
  }'