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 /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, sessionId?: string`	Omit sessionId to start a new conversation.
`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.
`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.
`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