API¶
replio serve runs an HTTP JSON API on 127.0.0.1:8787 by default (override with --host / --port).
replio serve
# replio serve - http://127.0.0.1:8787 (POST /chat, GET /sessions, GET /health, GET /version)
All responses are JSON with Content-Type: application/json.
POST /chat¶
Runs one agent turn on the same engine as the REPL and CLI.
Request body:
| Field | Type | Description |
|---|---|---|
prompt |
string | Required. The user message |
session_id |
string | Optional. Load or create a persistent session by name |
Example:
curl localhost:8787/chat -X POST -H 'Content-Type: application/json' \
-d '{"prompt": "Hi", "session_id": "api"}'
Response is the same TurnResult the CLI returns (see the README). session is the resolved session name.
Errors: 400 for a missing/empty prompt or invalid JSON body.
GET /sessions¶
Lists saved session names.
curl localhost:8787/sessions
# {"sessions": ["20260814_192251_hi", "api"]}
GET /health¶
Liveness check.
curl localhost:8787/health
# {"status": "ok"}
GET /version¶
Returns the installed version.
curl localhost:8787/version
# {"version": "0.12.0"}
Unknown routes return 404 {"error": "not found"}.