API

The server's HTTP API, which the web client reads.

The server’s API is plain JSON over HTTP, with no login of its own. Its OpenAPI document is at /api/openapi.json. Recorder times have no time zone: they’re the recorder’s own clock, as it keeps them, such as 2026-11-11T22:24:31.

It serves sources, such as the recorder, and their cameras. A camera’s id is its source’s id and its own, such as swann/3 for the recorder’s channel 3, and its routes take the two as path segments.

A camera in /api/cameras says what it can do: live has its go2rtc stream names, or is null for a camera with no live view; still says whether it has a still picture, which the page shows in place of video for a camera with no live view; recordings and events say whether it has them; signal is whether it has a picture now, or null when its source can’t tell. A source that isn’t connected yet leaves its cameras out until it knows them.

The settings read back carry a revision. A save sends back the one it read, and is refused with InvalidSettings when the settings have changed since, such as from another tab, so a page left open can’t undo a newer save.

A camera’s name is its source’s name for it, such as Channel 3, and its label the name you gave it on the Settings page, or null.

The settings are what sources.json keeps: each source’s id, kind, name and settings, its cameras for a kind you list cameras for yourself, and the camera labels. Each kind in /api/sources/kinds lists its fields, each text, number, secret or address. Reading them back leaves secret fields out, naming the ones that are set in secrets, and hides the password in an address as ********. A save keeps each secret it leaves out and each hidden password, checks the settings, and returns 400 with InvalidSettings saying what’s wrong, such as two sources with one id.

A source’s details are general, so any source can fill them in: facts are labelled values, such as the recorder’s name, firmware and channel count; clock is its own time, where it keeps one; storage lists each disk or card with its state; and cameras gives each camera’s signal, what it’s recording and whether there’s motion now. A source with nothing to show returns 404 with NotSupported.

/api/attention is the status source the CLI’s status, the page and push read. Each source works out its own. Alerts are what needs you: a source can’t be reached, a disk is bad or unformatted, or a camera that had a signal while the server ran has lost it. A full disk is passive, since the recorder records over its oldest recordings; the page shows it in the source’s Storage card.

An event in /api/events has its source, its camera where it’s about one, its kind (such as motion, PIR, or a camera’s own person, vehicle or animal detection), whether it started or ended, the source’s own time for it, and when the server received it.

Every endpoint that needs a source returns 503 with a SourceUnavailable error while it isn’t connected. An id that names no source or camera returns 404 with UnknownSource or UnknownCamera, and asking for something a source can’t do, such as a stream’s recordings, returns 404 with NotSupported.

Recorded video

GET /api/cameras/swann/1/video?begin=2026-11-11T21:46:00&end=2026-11-11T21:48:00 sends what a camera recorded between two recorder times as fragmented MP4, H.264 with no audio, which plays as it arrives. Add stream=sub for the small sub stream, and download=true to have a browser save it as a file rather than play it. speedUp=2, up to 4, shortens each frame so it plays that many times faster: browsers play no faster than 16 times.

every=1, up to 60, sends key frames only, one per that many seconds of recording, from the recorder’s own fast forward. The whole main stream only downloads at about 17 times real time, so it can’t keep up past 16, but its key frames come at about 58. So the page plays 32 times as every=1 with speedUp=2, at 16 times, in full resolution. The recorder runs one playback or download at a time; the server waits up to 15 seconds for it to let go of the last one.

• It runs across recordings, one after another, with the gaps between them closed up, so a range over a run of motion clips plays them back to back.
• It starts at the first key frame in the second at begin, and runs to the end of the key frame group at end, so about a second either side.
• It comes faster than real time, around 17 times on the main stream, so a minute of 1080p takes a few seconds. Nothing is kept on the server.
• A range with nothing recorded in it returns 404 with a NoRecordings error. Once video has started, a failure can only cut the response short.

The page plays it through Media Source Extensions. It sets the length from the range, asks for video from a new begin when you seek past what has loaded, and keeps only a few minutes around the playhead, as a full recording is about 250 MB.

Live video

The server serves go2rtc under /go2rtc/, its WebSocket included, so live video plays from the same address as the page, through a proxy or over HTTPS. Each camera’s live in /api/cameras names its streams, from its id: such as swann_1 for the main stream and swann_1_sub for the sub stream. Play one with /go2rtc/stream.html?src=swann_1_sub. subRatio is the width over height to draw the sub stream at when its frames squeeze the picture into another shape, as the DVR8-4575’s 352×288 sub stream does with a 16:9 picture, and null when it’s drawn at its own shape.

The DVR8-4575 offers an audio track on every stream but sends nothing on it, and an MSE player that asks for audio waits for it forever. The page plays video only, with go2rtc’s own video-rtc.js player and media set to video, so do the same in other players.

Push

The server pushes each alert from /api/attention once, when it starts, to every browser that subscribed. It follows Groundwork’s push contract, outside /api:

The page’s Notify me button subscribes. The keys and subscriptions are kept in push.json, readable only by you, under KESTREL_STATE, else $XDG_STATE_HOME/kestrel, else %LOCALAPPDATA%\kestrel on Windows, else ~/.local/state/kestrel.