Server API and events
The clients of Finn talk to its server over HTTP on 127.0.0.1. A program of your own can too: start a session, send it messages, read its events and answer its approvals. The protocol package of the repository has every record below with its JSON codec.
Find the server #
A running server writes server.json to its state folder (~/.local/state/finn by default), readable by you alone:
{"port": 41234, "token": "...", "pid": 12345}Every request sends Authorization: Bearer TOKEN. The server also refuses a Host that is not this machine, and an Origin other than its own, so a web page cannot call it.
state=~/.local/state/finn/server.json
port=$(jq .port "$state"); token=$(jq -r .token "$state")
curl -s -H "Authorization: Bearer $token" "http://127.0.0.1:$port/v1/sessions"Routes #
| Method and path | What it does |
|---|---|
GET /v1/health | the server answers, with its version |
GET /v1/server | the server's status: its pid, version and start time, how many sessions it has and how many turns run, whether it is stopping, and whether the approvals are on |
POST /v1/server/stop | stop the server, as finn server stop does |
GET /v1/providers | the providers and their models |
GET /v1/auth | the logins: each provider, where its key comes from, and what a login asks for (asks: key, or url with the base_url of local) |
PUT /v1/auth | make an empty key file when there is none, so the first-start login is not offered again |
POST /v1/auth/PROVIDER | log in: {"key": "..."}, checked at the provider, then stored; local takes {"base_url": "..."}, checked with its GET /models |
DELETE /v1/auth/PROVIDER | remove the stored key of a provider (the base URL of local, the tokens of chatgpt, which also ends a login that waits); DELETE /v1/auth removes all |
POST /v1/auth/chatgpt | start the device login of a ChatGPT subscription: {"user_code", "url", "expires_in"}; the user opens url and types the code, and the server waits for that and stores the tokens in chatgpt.json of its state folder (0600) |
GET /v1/auth/chatgpt | where that login is: {"state", "message"}, state being none, waiting, done or failed (message says why) |
POST /v1/sessions | a new session: {"cwd": "/path", "model": null}, plus provider, api and profile; it answers its id and profile |
GET /v1/sessions | the sessions, the last changed first; empty marks one with no message, compaction or output of a tool or command yet |
GET /v1/sessions/ID | one session: its settings, history (the messages, and items with an empty text for what the turns did: thinking with its text, a tool call with its end in done (without its output and diff), or the stop of a turn that did not end as asked; while a turn runs, the history stops at its start, and the events from turn_from_event_id give the rest), the usage of its last model call, the model's todos and its profile (name, source: built-in, user, project or empty when it does not load, description, warnings) |
PATCH /v1/sessions/ID | change provider, model, effort (the thinking level), accept_edits or profile (with the model and thinking level it sets, unless the same request gives them; 409 while a turn, a command or a compaction runs) |
DELETE /v1/sessions/ID | delete a session and its file |
POST /v1/sessions/ID/messages | send {"text": "..."}; it starts a turn, or joins the running one |
GET /v1/sessions/ID/events | the event stream of the session |
POST /v1/sessions/ID/approvals/AID | answer an approval: {"decision": "allow"} |
POST /v1/sessions/ID/stop | stop the running turn or command; {"turn_id": "..."} stops only that turn while it runs; answers {"stopped": true} or false |
POST /v1/sessions/ID/compact | fold the history now |
GET /v1/sessions/ID/tree | the user messages of every branch |
POST /v1/sessions/ID/branch | go on from an earlier message |
POST /v1/sessions/ID/fork | a new session from an earlier message |
GET /v1/sessions/ID/commands | the session's slash commands: {"commands": [{"name", "source", "description", "warnings"}]}; one that does not load has an empty source |
GET /v1/sessions/ID/profiles | the profiles the session may take: {"profiles": [{"name", "source", "description", "warnings"}]}; one that does not load has an empty source |
GET /v1/sessions/ID/files | the files of the session folder that the deny rules do not hide, for the @ completion: {"files": [...], "truncated": false}; truncated is true when the walk stopped at 5000 files, 2000 folders or about 2 s; with a files command they are the files of its output that the same rules let through, and note says why the walk listed them instead when it failed |
POST /v1/sessions/ID/shell | run {"command": "...", "context": true} in the session folder |
A decision is allow, deny, allow_session, allow_prefix or allow_tool (Answer).
A failed request answers with {"kind": "...", "message": "..."}. Branch on kind, a dotted name such as session.busy; the message is for people.
Events #
GET /v1/sessions/ID/events is a stream of Server-Sent Events. Each event has its kind as the SSE event:, its id as id:, and its JSON as data:. The stream has no heartbeat and stays quiet while the model thinks, so read it with no read timeout (with Agentica's std/http, read_timeout_ms: 0).
| Event | When |
|---|---|
turn_started | a turn starts with a user message |
text_delta, thinking_delta | a piece of the model's answer or thinking |
tool_started, tool_finished | a tool call starts and ends, with its output and the diff of an edit |
approval_requested, approval_resolved | a call waits for an answer, and gets one |
message_queued | a message sent while the turn runs |
shell_started, shell_finished | a command that a client ran in the session folder (!CMD) |
usage | the tokens of a model call: input, cache_read, cache_write and context of that call, output summed over the session, cost, turn_cost and session_cost when the catalog has prices, window, the model's window in tokens, when it is known, call_output, the output of that call alone, and output_ms, the milliseconds from its first output to its end |
todos | the model's whole todo list after a todo_write call: {"todos": [{"content", "status"}]} |
turn_finished | the turn ended, with its stop reason |
error | a failure, as {"kind", "message"} |
resync | the stream cannot go on from where you asked: read the session again |
An event id counts from 1 in each session, and stays valid across a restart of the server. To go on after a lost connection, send the last id you read as Last-Event-ID: the stream repeats no event and misses none. An id that is unknown or too old gets resync; so does one that needs a text or thinking delta from before a restart, since those are not kept.
A reader should ignore a key it does not know: newer servers may add some.