Syrenka Agent API v0.2.0

Text-only personal agent. Speech-to-text and text-to-speech happen on the client; this server only exchanges text.

Machine-readable: /openapi.json · /llms.txt

Auth

Authorization: Bearer <token> on every route except /health and these docs. The token is the identity — no username is sent and no client can act as another user.

REST

Route	Auth	What it does
`GET /health`	none	Liveness. Returns 200 even while warming so a container healthcheck does not restart-loop during first-boot indexing.
`GET /status`	bearer	Agent state, registered tools, live sessions and host metrics.
`GET /tools`	bearer	Every registered tool with the JSON Schema the model sees.
`GET /inbox`	bearer	Things that finished while you were away. Yours only. `?unread=1` to filter, `?id=` for one item's full body.
`GET /history`	bearer	Your own recent turns. Scoped to the calling token; you cannot read anyone else's.

WebSocket `/ws`

Authenticate on the handshake with the same header. Browsers may instead offer subprotocols syrenka.v1, bearer.<token>. Tokens in the query string are rejected.

Send

type	fields	notes
`turn`	`text: string, imageIds?: string[], sessionId?: string`	Omit sessionId to start a new conversation. imageIds come from POST /upload and are single-use; text may be empty when images are attached.
`cancel`	`sessionId: string`	Abort the turn in flight.
`resume`	`sessionId: string, lastSeq: number`	Replay everything you missed.
`ping`	`t?: number`	Round-trip check; answered with pong.

Receive

type	notes
`ready`	Sent on connect: your identity, session id, tool list, limits.
`turn.start`	A turn began. Carries turnId, text, speaker, and images (a count) when pictures were attached.
`step.start`	One model call begins.
`text.delta`	Reply text, token by token. Concatenate in order.
`text.done`	final=false means that text was narration; final=true means it is the answer.
`tool.call`	A tool started. callId correlates with tool.result.
`tool.result`	That tool finished: ok, durationMs, result.
`step.end`	Model call finished, with duration and tool-call count.
`turn.end`	Turn complete, with the full reply text.
`turn.error`	Turn failed.
`turn.queued`	Another turn is ahead of yours on this session.
`notice`	Out-of-band info/warn/error.
`link`	A tappable button for the reply it belongs to: label, kind (map/directions/web/youtube/spotify/call/sms/email) and an https/tel/sms/mailto url. Render under the message; ignore if you have nowhere to put it.
`inbox.item`	Something finished while you were away — research report, timer. Carries id, kind, title and the unread count. The body is fetched from /inbox when you want it.
`quick.actions`	Learned shortcut buttons for the Dynamic Island: [{label, command}]. Arrives shortly after ready, and again when they change.
`pong`	Reply to ping.

Client rules

Ignore unrecognised message types — new ones are added without a protocol bump.
Concatenate text.delta in order; turn.end carries the authoritative full reply.
Match tool.result to tool.call by callId, not by name.
Track seq and send it with resume after reconnecting.

Example

curl -H "Authorization: Bearer $TOKEN" http://mateusz-desktop.tail96606f.ts.net/status