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 pathWhat it does
GET /v1/healththe server answers, with its version
GET /v1/serverthe 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/stopstop the server, as finn server stop does
GET /v1/providersthe providers and their models
GET /v1/auththe 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/authmake an empty key file when there is none, so the first-start login is not offered again
POST /v1/auth/PROVIDERlog in: {"key": "..."}, checked at the provider, then stored; local takes {"base_url": "..."}, checked with its GET /models
DELETE /v1/auth/PROVIDERremove 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/chatgptstart 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/chatgptwhere that login is: {"state", "message"}, state being none, waiting, done or failed (message says why)
POST /v1/sessionsa new session: {"cwd": "/path", "model": null}, plus provider, api and profile; it answers its id and profile
GET /v1/sessionsthe sessions, the last changed first; empty marks one with no message, compaction or output of a tool or command yet
GET /v1/sessions/IDone 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/IDchange 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/IDdelete a session and its file
POST /v1/sessions/ID/messagessend {"text": "..."}; it starts a turn, or joins the running one
GET /v1/sessions/ID/eventsthe event stream of the session
POST /v1/sessions/ID/approvals/AIDanswer an approval: {"decision": "allow"}
POST /v1/sessions/ID/stopstop the running turn or command; {"turn_id": "..."} stops only that turn while it runs; answers {"stopped": true} or false
POST /v1/sessions/ID/compactfold the history now
GET /v1/sessions/ID/treethe user messages of every branch
POST /v1/sessions/ID/branchgo on from an earlier message
POST /v1/sessions/ID/forka new session from an earlier message
GET /v1/sessions/ID/commandsthe session's slash commands: {"commands": [{"name", "source", "description", "warnings"}]}; one that does not load has an empty source
GET /v1/sessions/ID/profilesthe profiles the session may take: {"profiles": [{"name", "source", "description", "warnings"}]}; one that does not load has an empty source
GET /v1/sessions/ID/filesthe 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/shellrun {"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).

EventWhen
turn_starteda turn starts with a user message
text_delta, thinking_deltaa piece of the model's answer or thinking
tool_started, tool_finisheda tool call starts and ends, with its output and the diff of an edit
approval_requested, approval_resolveda call waits for an answer, and gets one
message_queueda message sent while the turn runs
shell_started, shell_finisheda command that a client ran in the session folder (!CMD)
usagethe 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
todosthe model's whole todo list after a todo_write call: {"todos": [{"content", "status"}]}
turn_finishedthe turn ended, with its stop reason
errora failure, as {"kind", "message"}
resyncthe 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.