API reference

Generated from docs/openapi.yaml, version 0.1.0. CI validates the running daemon against the same file.

Conventions

HTTP + SSE	`http://127.0.0.1:7447`
WebSocket	`ws://127.0.0.1:7448`
Auth	`Authorization: Bearer <token>` on every HTTP request; `?access_token=` also accepted on `GET /events`; on the WebSocket, a first frame of `{ "auth": "<token>" }`
Bodies	JSON in, JSON out; `Content-Type: application/json`
Paths	the take folder is relative to `outputRoot` from `GET /`; each file is relative to the take folder
Times	host times are ISO 8601 UTC with milliseconds; `t` is seconds from the cue; `timecode` is `HH:MM:SS:FF`
Absence	an unmeasurable value is absent, or `null` where the field is always present — never `0`

{ "error": "destination takes/2026-09-11/210433-episode-12 is not empty", "code": "conflict" }

status	code	when
`400`	`bad_request`	malformed JSON, missing body, a frame without `method`/`path`
`401`	`unauthorized`	no token, wrong token, WebSocket before the auth frame
`403`	`permission_denied`	macOS has not granted the device class this stream needs
`404`	`not_found`	no such route, stream or take
`405`	`method_not_allowed`	the path exists, the method does not
`409`	`conflict`	destination already exists; a take is not in the state the verb needs
`409`	`take_active`	a take is recording; stop it first
`500`	`internal`	a handler threw
`501`	`unsupported`	this kind cannot be captured yet
`503`	`device_unavailable`	the device is gone, busy, or refused the configuration
`503`	`no_frame`	preview: the device delivered no frame
`507`	`insufficient_storage`	the disk pre-flight refused the take

Discovery

GET`/`

Who this daemon is, where files go, how much room there is.

401: No token, or the wrong one.

Discovery.

→ {"id":1,"method":"GET","path":"/"}
← {"id":1,"status":200,"body":{"name":"Rheocles","version":"0.1.0","hostname":"lens-macbook-pro.local","machineId":"CD3B7EE5-5E6C-5155-854A-72E4728555F7","outputRoot":"/Users/gopher/Movies/Rheocles","freeBytes":44878079167,"auth":"bearer","ports":{"http":7447,"ws":7448}}}

response field	type
`name`*	`"Rheocles"`
`version`*	`string`
`hostname`*	`string`
`machineId`*	`string`	The kernel host UUID; stable across renames and reboots.
`outputRoot`*	`string`	The one absolute path in the API. Every other path is relative to it.
`freeBytes`	`integer`	Bytes available for important usage on the output root's volume. Absent when unmeasurable — absent means unknown, never zero.
`auth`*	`"bearer"`
`ports`*	`object`
`ports.http`*	`integer`
`ports.ws`*	`integer`

Streams

Every input on the machine, with a stable id. Arming makes a device live; it never writes.

GET`/streams`

Every stream with its armed state, plus what macOS lets this process see.

401: No token, or the wrong one.

Streams, in a fixed order — displays, windows, cameras, microphones, system audio.

→ {"id":2,"method":"GET","path":"/streams"}
← {"id":2,"status":200,"body":{"streams":[],"permissions":{"camera":"authorized","microphone":"authorized","screen":"authorized"}}}

response field	type
`streams`*	`object[]`
`streams[].id`*	`string`	Stable and URL-safe, `<kind>:<identifier>`. Clients hold this.
`streams[].kind`*	`"display" \| "window" \| "camera" \| "microphone" \| "systemAudio"`
`streams[].name`*	`string`	What the user calls it.
`streams[].model`*	`string`	What the hardware calls itself, or the owning application for a window.
`streams[].capabilities`*	`object`
`streams[].capabilities.video`	`object`
`streams[].capabilities.audio`	`object`
`streams[].armed`*	`boolean`	Whether the capture session is live.
`streams[].active`	`object`	What the device is actually delivering; present only while armed.
`streams[].active.video`	`object`
`streams[].active.audio`	`object`
`streams[].framesSeen`	`integer`	Frames or audio buffers delivered since arming; present only while armed.
`permissions`*	`object`	What macOS has let this process do. Screen Recording gates displays and windows both; with `screen` anything but `authorized` the list has none.
`permissions.camera`*	`"authorized" \| "denied" \| "restricted" \| "notDetermined"`
`permissions.microphone`*	`"authorized" \| "denied" \| "restricted" \| "notDetermined"`
`permissions.screen`*	`"authorized" \| "denied" \| "restricted" \| "notDetermined"`

POST`/streams/{id}/arm`

Make a device live (frames flow and are discarded) or release it. Never stamps, never writes.

field	type
`armed`*	`boolean`

400: Malformed or missing JSON body.
401: No token, or the wrong one.
403: macOS has not granted this process the device class.
404: No such stream or take.
503: The device is gone, busy, or refused the configuration.

The stream as it now is. Idempotent in both directions.

→ {"id":3,"method":"POST","path":"/streams/camera:0x2300000fd9009c/arm","body":{"armed":true}}
← {"id":3,"status":200,"body":{"id":"camera:0x2300000fd9009c","kind":"camera","name":"Elgato 4K X","model":"UVC Camera VendorID_4057 ProductID_156","capabilities":{"video":{"width":3840,"height":2160,"maxFrameRate":30}},"armed":true,"active":{"video":{"width":1280,"height":720,"maxFrameRate":120}},"framesSeen":0}}

response field	type
`id`*	`string`	Stable and URL-safe, `<kind>:<identifier>`. Clients hold this.
`kind`*	`"display" \| "window" \| "camera" \| "microphone" \| "systemAudio"`
`name`*	`string`	What the user calls it.
`model`*	`string`	What the hardware calls itself, or the owning application for a window.
`capabilities`*	`object`
`capabilities.video`	`object`
`capabilities.video.width`*	`integer`	Native pixels.
`capabilities.video.height`*	`integer`
`capabilities.video.maxFrameRate`*	`number`	The highest advertised rate; the signal's real rate can be lower.
`capabilities.audio`	`object`
`capabilities.audio.sampleRate`*	`number`
`capabilities.audio.channels`*	`integer`
`armed`*	`boolean`	Whether the capture session is live.
`active`	`object`	What the device is actually delivering; present only while armed.
`active.video`	`object`
`active.video.width`*	`integer`
`active.video.height`*	`integer`
`active.video.maxFrameRate`*	`number`
`active.audio`	`object`
`active.audio.sampleRate`*	`number`
`active.audio.channels`*	`integer`
`framesSeen`	`integer`	Frames or audio buffers delivered since arming; present only while armed.

Takes

Create reserves the paths and writes the manifest. Start is the cue. Stop finalises.

POST`/takes`

Create a take — snapshot the armed set, reserve paths, pre-flight the disk, write the manifest. Nothing records.

field	type
`name`	`string`
`destination`	`string`	Take folder relative to the output root. Default `takes/<yyyy-MM-dd>/<HHmmss>[-<name>]`.
`files`	`object`	File name per stream id, relative to the take folder.
`codec`	`"hevc" \| "prores"`
`expectedDuration`	`number`	Seconds, for the disk pre-flight. Default 1800.
`overwrite`	`boolean`	Reuse a destination that already exists. Never silently suffixed.

400: Malformed or missing JSON body.
401: No token, or the wrong one.
409: Destination already exists (code conflict), or a take is recording (code take_active).
507: The disk pre-flight refused the take.

The manifest (state `created`) and any pre-flight warnings.

→ {"id":4,"method":"POST","path":"/takes","body":{"name":"Episode 12","expectedDuration":3600}}
← {"id":4,"status":201,"body":{"take":{"id":"20260912T040433-fd9q","name":"Episode 12","state":"created","created":"2026-09-12T04:04:33.235Z","outputRoot":"/Users/gopher/Movies/Rheocles","destination":"takes/2026-09-11/210433-episode-12","version":"0.1.0","machine":{"hostname":"lens-macbook-pro.local","machineId":"CD3B7EE5-5E6C-5155-854A-72E4728555F7"},"streams":[{"id":"microphone:AppleUSBAudioEngine_Focusrite_Scarlett_2i2_USB_Y8CABR91C1CA8A_1_2","kind":"microphone","name":"Scarlett 2i2 USB","model":"Scarlett 2i2 USB:1235:8210","path":"scarlett-2i2-usb.wav","codec":"pcm_s24le","format":{"audio":{"sampleRate":48000,"channels":2}},"framesWritten":0,"events":[]}],"markers":[],"settings":{"codec":"hevc","expectedDuration":3600}},"warnings":[]}}

response field	type
`take`*	`object`	The manifest is the take. Rewritten atomically on every state change.
`take.id`*	`string`
`take.name`	`string`
`take.state`*	`"created" \| "recording" \| "complete" \| "incomplete"`
`take.reason`	`string`	Present only when `incomplete`.
`take.created`*	`string`
`take.started`	`string`
`take.stopped`	`string`
`take.outputRoot`*	`string`	Absolute, as it was at create.
`take.destination`*	`string`	Take folder, relative to the output root.
`take.version`*	`string`
`take.machine`*	`object`
`take.machine.hostname`*	`string`
`take.machine.machineId`*	`string`
`take.streams`*	`object[]`
`take.streams[].id`*	`string`
`take.streams[].kind`*	`"display" \| "window" \| "camera" \| "microphone" \| "systemAudio"`
`take.streams[].name`*	`string`
`take.streams[].model`*	`string`
`take.streams[].path`*	`string`	Relative to the take folder.
`take.streams[].codec`*	`string`	hevc, prores, or pcm_s24le.
`take.streams[].format`*	`object`
`take.streams[].started`	`string`
`take.streams[].stopped`	`string`
`take.streams[].timecode`	`string`	Start timecode HH:MM:SS:FF — the LOCAL time of day (the machine's own midnight) of the first written frame, nearest frame. The manifest's created/started/stopped are UTC.
`take.streams[].timeReference`	`integer`	Audio only. BWF TimeReference: samples since LOCAL midnight at the first sample — the sample-exact form of `timecode`.
`take.streams[].framesDropped`	`integer`	Video only. Frames the encoder was not ready for. Absent when zero.
`take.streams[].framesWritten`*	`integer`
`take.streams[].drift`	`number`	Frames × frame duration versus host elapsed, seconds.
`take.streams[].events`*	`object[]`
`take.streams[].error`	`string`
`take.markers`*	`object[]`
`take.markers[].t`*	`number`	Seconds from the cue.
`take.markers[].label`*	`string`
`take.settings`*	`object`
`take.settings.codec`*	`"hevc" \| "prores"`
`take.settings.expectedDuration`	`number`
`warnings`*	`string[]`

POST`/takes/{id}/start`

The cue. Every armed stream's writer starts on frames that are already flowing.

401: No token, or the wrong one.
404: No such stream or take.
409: The take is not created, or is not the active take.

The manifest, now `recording`.

→ {"id":7,"method":"POST","path":"/takes/20260912T040433-fd9q/start"}
← {"id":7,"status":200,"body":{"id":"20260912T040433-fd9q","state":"recording","started":"2026-09-12T04:04:33.347Z"}}

response field	type
`id`*	`string`
`name`	`string`
`state`*	`"created" \| "recording" \| "complete" \| "incomplete"`
`reason`	`string`	Present only when `incomplete`.
`created`*	`string`
`started`	`string`
`stopped`	`string`
`outputRoot`*	`string`	Absolute, as it was at create.
`destination`*	`string`	Take folder, relative to the output root.
`version`*	`string`
`machine`*	`object`
`machine.hostname`*	`string`
`machine.machineId`*	`string`
`streams`*	`object[]`
`streams[].id`*	`string`
`streams[].kind`*	`"display" \| "window" \| "camera" \| "microphone" \| "systemAudio"`
`streams[].name`*	`string`
`streams[].model`*	`string`
`streams[].path`*	`string`	Relative to the take folder.
`streams[].codec`*	`string`	hevc, prores, or pcm_s24le.
`streams[].format`*	`object`
`streams[].format.video`	`object`
`streams[].format.audio`	`object`
`streams[].started`	`string`
`streams[].stopped`	`string`
`streams[].timecode`	`string`	Start timecode HH:MM:SS:FF — the LOCAL time of day (the machine's own midnight) of the first written frame, nearest frame. The manifest's created/started/stopped are UTC.
`streams[].timeReference`	`integer`	Audio only. BWF TimeReference: samples since LOCAL midnight at the first sample — the sample-exact form of `timecode`.
`streams[].framesDropped`	`integer`	Video only. Frames the encoder was not ready for. Absent when zero.
`streams[].framesWritten`*	`integer`
`streams[].drift`	`number`	Frames × frame duration versus host elapsed, seconds.
`streams[].events`*	`object[]`
`streams[].events[].t`*	`number`
`streams[].events[].type`*	`"join" \| "leave"`
`streams[].error`	`string`
`markers`*	`object[]`
`markers[].t`*	`number`	Seconds from the cue.
`markers[].label`*	`string`
`settings`*	`object`
`settings.codec`*	`"hevc" \| "prores"`
`settings.expectedDuration`	`number`

POST`/takes/{id}/stop`

Finalize every writer and the manifest. Streams stay armed.

401: No token, or the wrong one.
404: No such stream or take.
409: The take is not recording.

The final manifest — `complete`, or `incomplete` with a reason.

→ {"id":8,"method":"POST","path":"/takes/20260912T040433-fd9q/stop"}
← {"id":8,"status":200,"body":{"id":"20260912T040433-fd9q","state":"complete","stopped":"2026-09-12T04:04:35.402Z"}}

response field	type
`id`*	`string`
`name`	`string`
`state`*	`"created" \| "recording" \| "complete" \| "incomplete"`
`reason`	`string`	Present only when `incomplete`.
`created`*	`string`
`started`	`string`
`stopped`	`string`
`outputRoot`*	`string`	Absolute, as it was at create.
`destination`*	`string`	Take folder, relative to the output root.
`version`*	`string`
`machine`*	`object`
`machine.hostname`*	`string`
`machine.machineId`*	`string`
`streams`*	`object[]`
`streams[].id`*	`string`
`streams[].kind`*	`"display" \| "window" \| "camera" \| "microphone" \| "systemAudio"`
`streams[].name`*	`string`
`streams[].model`*	`string`
`streams[].path`*	`string`	Relative to the take folder.
`streams[].codec`*	`string`	hevc, prores, or pcm_s24le.
`streams[].format`*	`object`
`streams[].format.video`	`object`
`streams[].format.audio`	`object`
`streams[].started`	`string`
`streams[].stopped`	`string`
`streams[].timecode`	`string`	Start timecode HH:MM:SS:FF — the LOCAL time of day (the machine's own midnight) of the first written frame, nearest frame. The manifest's created/started/stopped are UTC.
`streams[].timeReference`	`integer`	Audio only. BWF TimeReference: samples since LOCAL midnight at the first sample — the sample-exact form of `timecode`.
`streams[].framesDropped`	`integer`	Video only. Frames the encoder was not ready for. Absent when zero.
`streams[].framesWritten`*	`integer`
`streams[].drift`	`number`	Frames × frame duration versus host elapsed, seconds.
`streams[].events`*	`object[]`
`streams[].events[].t`*	`number`
`streams[].events[].type`*	`"join" \| "leave"`
`streams[].error`	`string`
`markers`*	`object[]`
`markers[].t`*	`number`	Seconds from the cue.
`markers[].label`*	`string`
`settings`*	`object`
`settings.codec`*	`"hevc" \| "prores"`
`settings.expectedDuration`	`number`

POST`/takes/{id}/join`

Start one stream's writer inside a running take, arming it first if cold. Stamped with the time it began.

field	type
`stream`*	`string`

401: No token, or the wrong one.
404: No such stream or take.
409: The take is not recording, or the stream is already recording in it.

The manifest with the joined stream.

→ {"id":10,"method":"POST","path":"/takes/20260912T045007-5kqn/join","body":{"stream":"microphone:BuiltInMicrophoneDevice"}}
← {"id":10,"status":200,"body":{"id":"20260912T045007-5kqn","state":"recording"}}

response field	type
`id`*	`string`
`name`	`string`
`state`*	`"created" \| "recording" \| "complete" \| "incomplete"`
`reason`	`string`	Present only when `incomplete`.
`created`*	`string`
`started`	`string`
`stopped`	`string`
`outputRoot`*	`string`	Absolute, as it was at create.
`destination`*	`string`	Take folder, relative to the output root.
`version`*	`string`
`machine`*	`object`
`machine.hostname`*	`string`
`machine.machineId`*	`string`
`streams`*	`object[]`
`streams[].id`*	`string`
`streams[].kind`*	`"display" \| "window" \| "camera" \| "microphone" \| "systemAudio"`
`streams[].name`*	`string`
`streams[].model`*	`string`
`streams[].path`*	`string`	Relative to the take folder.
`streams[].codec`*	`string`	hevc, prores, or pcm_s24le.
`streams[].format`*	`object`
`streams[].format.video`	`object`
`streams[].format.audio`	`object`
`streams[].started`	`string`
`streams[].stopped`	`string`
`streams[].timecode`	`string`	Start timecode HH:MM:SS:FF — the LOCAL time of day (the machine's own midnight) of the first written frame, nearest frame. The manifest's created/started/stopped are UTC.
`streams[].timeReference`	`integer`	Audio only. BWF TimeReference: samples since LOCAL midnight at the first sample — the sample-exact form of `timecode`.
`streams[].framesDropped`	`integer`	Video only. Frames the encoder was not ready for. Absent when zero.
`streams[].framesWritten`*	`integer`
`streams[].drift`	`number`	Frames × frame duration versus host elapsed, seconds.
`streams[].events`*	`object[]`
`streams[].events[].t`*	`number`
`streams[].events[].type`*	`"join" \| "leave"`
`streams[].error`	`string`
`markers`*	`object[]`
`markers[].t`*	`number`	Seconds from the cue.
`markers[].label`*	`string`
`settings`*	`object`
`settings.codec`*	`"hevc" \| "prores"`
`settings.expectedDuration`	`number`

POST`/takes/{id}/leave`

Finalize one stream's file; the stream stays armed and the take continues for the others.

field	type
`stream`*	`string`

401: No token, or the wrong one.
404: No such stream or take.
409: The take is not recording, or the stream is not recording in it.

The manifest with that stream finalized.

→ {"id":11,"method":"POST","path":"/takes/20260912T045007-5kqn/leave","body":{"stream":"microphone:BuiltInMicrophoneDevice"}}
← {"id":11,"status":200,"body":{"id":"20260912T045007-5kqn","state":"recording"}}

response field	type
`id`*	`string`
`name`	`string`
`state`*	`"created" \| "recording" \| "complete" \| "incomplete"`
`reason`	`string`	Present only when `incomplete`.
`created`*	`string`
`started`	`string`
`stopped`	`string`
`outputRoot`*	`string`	Absolute, as it was at create.
`destination`*	`string`	Take folder, relative to the output root.
`version`*	`string`
`machine`*	`object`
`machine.hostname`*	`string`
`machine.machineId`*	`string`
`streams`*	`object[]`
`streams[].id`*	`string`
`streams[].kind`*	`"display" \| "window" \| "camera" \| "microphone" \| "systemAudio"`
`streams[].name`*	`string`
`streams[].model`*	`string`
`streams[].path`*	`string`	Relative to the take folder.
`streams[].codec`*	`string`	hevc, prores, or pcm_s24le.
`streams[].format`*	`object`
`streams[].format.video`	`object`
`streams[].format.audio`	`object`
`streams[].started`	`string`
`streams[].stopped`	`string`
`streams[].timecode`	`string`	Start timecode HH:MM:SS:FF — the LOCAL time of day (the machine's own midnight) of the first written frame, nearest frame. The manifest's created/started/stopped are UTC.
`streams[].timeReference`	`integer`	Audio only. BWF TimeReference: samples since LOCAL midnight at the first sample — the sample-exact form of `timecode`.
`streams[].framesDropped`	`integer`	Video only. Frames the encoder was not ready for. Absent when zero.
`streams[].framesWritten`*	`integer`
`streams[].drift`	`number`	Frames × frame duration versus host elapsed, seconds.
`streams[].events`*	`object[]`
`streams[].events[].t`*	`number`
`streams[].events[].type`*	`"join" \| "leave"`
`streams[].error`	`string`
`markers`*	`object[]`
`markers[].t`*	`number`	Seconds from the cue.
`markers[].label`*	`string`
`settings`*	`object`
`settings.codec`*	`"hevc" \| "prores"`
`settings.expectedDuration`	`number`

POST`/takes/{id}/markers`

Append a marker at the current cue offset. Rheocles stamps when; the client says what.

field	type
`label`*	`string`

400: Malformed or missing JSON body.
401: No token, or the wrong one.
404: No such stream or take.
409: The take is not recording.

The manifest with the marker appended.

→ {"id":12,"method":"POST","path":"/takes/20260912T045007-5kqn/markers","body":{"label":"chapter 1"}}
← {"id":12,"status":200,"body":{"id":"20260912T045007-5kqn","markers":[{"t":2.042,"label":"chapter 1"}]}}

response field	type
`id`*	`string`
`name`	`string`
`state`*	`"created" \| "recording" \| "complete" \| "incomplete"`
`reason`	`string`	Present only when `incomplete`.
`created`*	`string`
`started`	`string`
`stopped`	`string`
`outputRoot`*	`string`	Absolute, as it was at create.
`destination`*	`string`	Take folder, relative to the output root.
`version`*	`string`
`machine`*	`object`
`machine.hostname`*	`string`
`machine.machineId`*	`string`
`streams`*	`object[]`
`streams[].id`*	`string`
`streams[].kind`*	`"display" \| "window" \| "camera" \| "microphone" \| "systemAudio"`
`streams[].name`*	`string`
`streams[].model`*	`string`
`streams[].path`*	`string`	Relative to the take folder.
`streams[].codec`*	`string`	hevc, prores, or pcm_s24le.
`streams[].format`*	`object`
`streams[].format.video`	`object`
`streams[].format.audio`	`object`
`streams[].started`	`string`
`streams[].stopped`	`string`
`streams[].timecode`	`string`	Start timecode HH:MM:SS:FF — the LOCAL time of day (the machine's own midnight) of the first written frame, nearest frame. The manifest's created/started/stopped are UTC.
`streams[].timeReference`	`integer`	Audio only. BWF TimeReference: samples since LOCAL midnight at the first sample — the sample-exact form of `timecode`.
`streams[].framesDropped`	`integer`	Video only. Frames the encoder was not ready for. Absent when zero.
`streams[].framesWritten`*	`integer`
`streams[].drift`	`number`	Frames × frame duration versus host elapsed, seconds.
`streams[].events`*	`object[]`
`streams[].events[].t`*	`number`
`streams[].events[].type`*	`"join" \| "leave"`
`streams[].error`	`string`
`markers`*	`object[]`
`markers[].t`*	`number`	Seconds from the cue.
`markers[].label`*	`string`
`settings`*	`object`
`settings.codec`*	`"hevc" \| "prores"`
`settings.expectedDuration`	`number`

GET`/takes/{id}`

The manifest — live while recording, from disk afterwards.

401: No token, or the wrong one.
404: No such stream or take.

The manifest.

→ {"id":6,"method":"GET","path":"/takes/20260912T040433-fd9q"}
← {"id":6,"status":200,"body":{"id":"20260912T040433-fd9q","state":"recording"}}

response field	type
`id`*	`string`
`name`	`string`
`state`*	`"created" \| "recording" \| "complete" \| "incomplete"`
`reason`	`string`	Present only when `incomplete`.
`created`*	`string`
`started`	`string`
`stopped`	`string`
`outputRoot`*	`string`	Absolute, as it was at create.
`destination`*	`string`	Take folder, relative to the output root.
`version`*	`string`
`machine`*	`object`
`machine.hostname`*	`string`
`machine.machineId`*	`string`
`streams`*	`object[]`
`streams[].id`*	`string`
`streams[].kind`*	`"display" \| "window" \| "camera" \| "microphone" \| "systemAudio"`
`streams[].name`*	`string`
`streams[].model`*	`string`
`streams[].path`*	`string`	Relative to the take folder.
`streams[].codec`*	`string`	hevc, prores, or pcm_s24le.
`streams[].format`*	`object`
`streams[].format.video`	`object`
`streams[].format.audio`	`object`
`streams[].started`	`string`
`streams[].stopped`	`string`
`streams[].timecode`	`string`	Start timecode HH:MM:SS:FF — the LOCAL time of day (the machine's own midnight) of the first written frame, nearest frame. The manifest's created/started/stopped are UTC.
`streams[].timeReference`	`integer`	Audio only. BWF TimeReference: samples since LOCAL midnight at the first sample — the sample-exact form of `timecode`.
`streams[].framesDropped`	`integer`	Video only. Frames the encoder was not ready for. Absent when zero.
`streams[].framesWritten`*	`integer`
`streams[].drift`	`number`	Frames × frame duration versus host elapsed, seconds.
`streams[].events`*	`object[]`
`streams[].events[].t`*	`number`
`streams[].events[].type`*	`"join" \| "leave"`
`streams[].error`	`string`
`markers`*	`object[]`
`markers[].t`*	`number`	Seconds from the cue.
`markers[].label`*	`string`
`settings`*	`object`
`settings.codec`*	`"hevc" \| "prores"`
`settings.expectedDuration`	`number`

GET`/takes`

Recent takes, newest first.

401: No token, or the wrong one.

Up to 50 summaries.

→ {"id":5,"method":"GET","path":"/takes"}
← {"id":5,"status":200,"body":[{"id":"20260912T040433-fd9q","name":"Episode 12","state":"complete","created":"2026-09-12T04:04:33.235Z","destination":"takes/2026-09-11/210433-episode-12","streams":5}]}

response field	type

Record

POST`/record`

Create and start in one call — the popover's Record button.

field	type
`name`	`string`
`destination`	`string`	Take folder relative to the output root. Default `takes/<yyyy-MM-dd>/<HHmmss>[-<name>]`.
`files`	`object`	File name per stream id, relative to the take folder.
`codec`	`"hevc" \| "prores"`
`expectedDuration`	`number`	Seconds, for the disk pre-flight. Default 1800.
`overwrite`	`boolean`	Reuse a destination that already exists. Never silently suffixed.

400: Malformed or missing JSON body.
401: No token, or the wrong one.
409: Destination already exists (code conflict), or a take is recording (code take_active).
507: The disk pre-flight refused the take.

The manifest (state `recording`) and any pre-flight warnings.

→ {"id":9,"method":"POST","path":"/record","body":{"name":"quick"}}
← {"id":9,"status":201,"body":{"take":{"id":"20260912T040500-k2pm","state":"recording"},"warnings":[]}}

response field	type
`take`*	`object`	The manifest is the take. Rewritten atomically on every state change.
`take.id`*	`string`
`take.name`	`string`
`take.state`*	`"created" \| "recording" \| "complete" \| "incomplete"`
`take.reason`	`string`	Present only when `incomplete`.
`take.created`*	`string`
`take.started`	`string`
`take.stopped`	`string`
`take.outputRoot`*	`string`	Absolute, as it was at create.
`take.destination`*	`string`	Take folder, relative to the output root.
`take.version`*	`string`
`take.machine`*	`object`
`take.machine.hostname`*	`string`
`take.machine.machineId`*	`string`
`take.streams`*	`object[]`
`take.streams[].id`*	`string`
`take.streams[].kind`*	`"display" \| "window" \| "camera" \| "microphone" \| "systemAudio"`
`take.streams[].name`*	`string`
`take.streams[].model`*	`string`
`take.streams[].path`*	`string`	Relative to the take folder.
`take.streams[].codec`*	`string`	hevc, prores, or pcm_s24le.
`take.streams[].format`*	`object`
`take.streams[].started`	`string`
`take.streams[].stopped`	`string`
`take.streams[].timecode`	`string`	Start timecode HH:MM:SS:FF — the LOCAL time of day (the machine's own midnight) of the first written frame, nearest frame. The manifest's created/started/stopped are UTC.
`take.streams[].timeReference`	`integer`	Audio only. BWF TimeReference: samples since LOCAL midnight at the first sample — the sample-exact form of `timecode`.
`take.streams[].framesDropped`	`integer`	Video only. Frames the encoder was not ready for. Absent when zero.
`take.streams[].framesWritten`*	`integer`
`take.streams[].drift`	`number`	Frames × frame duration versus host elapsed, seconds.
`take.streams[].events`*	`object[]`
`take.streams[].error`	`string`
`take.markers`*	`object[]`
`take.markers[].t`*	`number`	Seconds from the cue.
`take.markers[].label`*	`string`
`take.settings`*	`object`
`take.settings.codec`*	`"hevc" \| "prores"`
`take.settings.expectedDuration`	`number`
`warnings`*	`string[]`

Settings

Daemon-owned defaults, persisted to ~/Library/Application Support/Rheocles/settings.json.

GET`/settings`

The daemon's output root and default codec.

401: No token, or the wrong one.

Settings.

→ {"id":13,"method":"GET","path":"/settings"}
← {"id":13,"status":200,"body":{"outputRoot":"/Users/gopher/Movies/Rheocles","codec":"hevc"}}

response field	type
`outputRoot`*	`string`	Absolute path new takes land under.
`codec`*	`"hevc" \| "prores"`

PATCH`/settings`

Change the output root and/or default codec. The root cannot move while a take is active.

field	type
`outputRoot`	`string`	Absolute path.
`codec`	`"hevc" \| "prores"`

400: Malformed or missing JSON body.
401: No token, or the wrong one.
409: The output root cannot change while a take is active.

The full settings after the change.

→ {"id":14,"method":"PATCH","path":"/settings","body":{"codec":"prores"}}
← {"id":14,"status":200,"body":{"outputRoot":"/Users/gopher/Movies/Rheocles","codec":"prores"}}

response field	type
`outputRoot`*	`string`	Absolute path new takes land under.
`codec`*	`"hevc" \| "prores"`

Token

POST`/token/rotate`

Issue a new bearer token; the old one stops working after this response.

401: No token, or the wrong one.

The new token.

→ {"id":15,"method":"POST","path":"/token/rotate"}
← {"id":15,"status":200,"body":{"token":"9f3c00112233445566778899aabbccddeeff00112233445566778899aabbccdd"}}

response field	type
`token`*	`string`

Events

State, levels, drift, joins, errors — pushed as they happen.

GET`/events`

The Server-Sent Events stream — every event, one-way.

text/event-stream; each event is one data: <json> line (see x-events). EventSource cannot set headers, so the bearer token is accepted as ?access_token= here as well as in the Authorization header. The same events reach every authenticated WebSocket client.

field	type
`?access_token`	`string`	The bearer token, for EventSource which cannot set a header.

401: No token, or the wrong one.

The event stream.

Preview

GET`/preview/{stream}`

One preview frame, on demand. Nothing is captured when nobody is looking; one preview at a time.

A polite second opener grabs a single frame and closes the device, so preview never disturbs an armed or recording take. Video streams answer a small JPEG (longest side 640); audio streams answer the current peak level as JSON, for the popover's meter.

401: No token, or the wrong one.
404: No such stream or take.
503: The device delivered no frame to preview (code no_frame), or is unavailable.

A JPEG for video streams, or a JSON level for audio streams.

Answers image/jpeg or application/json.

→ {"id":16,"method":"GET","path":"/preview/display:56A96CFC-7F21-168E-0857-D6964E3302DB"}
← {"id":16,"status":200,"contentType":"image/jpeg","base64":"/9j/4AAQSk…"}

response field	type
`levelDb`*	`number`	Peak dBFS of a short sample.

WebSocket

Everything above, full duplex, on port 7448.

WS`ws://127.0.0.1:7448/`

One socket carries every command and every event.

The first frame must authenticate; until it does, every command is answered 401 and no event is delivered. A browser WebSocket cannot set an Authorization header, so the frame is the only way. One JSON object per text frame. id is echoed untouched; method, path, query and body are the HTTP request's. status is the HTTP status the same command would give. A JSON body is inline in body; a binary body (a preview JPEG) comes as base64 with its contentType instead. Unsolicited frames with an event key and no id; the same objects GET /events delivers (see x-events).

→ {"auth":"<token>"}
← {"id":null,"status":200,"body":{"authenticated":true}}
→ {"id":4,"method":"POST","path":"/takes","query":{},"body":{"name":"Episode 12"}}
← {"id":4,"status":201,"body":{"take":{"id":"20260912T040433-fd9q","state":"created"}}}
← {"id":16,"status":200,"contentType":"image/jpeg","base64":"/9j/4AAQSk…"}

Event types

Delivered on GET /events as data: lines, and on the WebSocket as objects with an event key and no id — the same bytes on both.

event	when	data
`levels`	Per-stream peak level (audio, dBFS), frames written and drift, ~4x/s while recording.	`{"event":"levels","take":"20260912T045007-5kqn","streams":[{"id":"microphone:BuiltInMicrophoneDevice","levelDb":-18.3,"framesWritten":96000,"drift":0}]}`
`marker`	A marker was added to the active take.	`{"event":"marker","take":"20260912T045007-5kqn","marker":{"t":2.042,"label":"chapter 1"}}`
`stalled`	An armed or recording stream stopped delivering frames.	`{"event":"stalled","stream":{"id":"camera:0x2300000fd9009c","kind":"camera","name":"Elgato 4K X","model":"UVC Camera VendorID_4057 ProductID_156","capabilities":{"video":{"width":3840,"height":2160,"maxFrameRate":30}},"armed":true,"active":{"video":{"width":1280,"height":720,"maxFrameRate":30}},"framesSeen":0}}`
`settings`	The daemon's settings changed.	`{"event":"settings","settings":{"outputRoot":"/Users/gopher/Movies/Rheocles","codec":"prores"}}`
`take`	A take changed state — created, recording, complete or incomplete. Carries the manifest.	`{"event":"take","take":{"id":"20260912T040433-fd9q","name":"Episode 12","state":"recording","created":"2026-09-12T04:04:33.235Z","started":"2026-09-12T04:04:33.347Z","outputRoot":"/Users/gopher/Movies/Rheocles","destination":"takes/2026-09-11/210433-episode-12","version":"0.1.0","machine":{"hostname":"lens-macbook-pro.local","machineId":"CD3B7EE5-5E6C-5155-854A-72E4728555F7"},"streams":[],"markers":[],"settings":{"codec":"hevc"}}}`
`stream`	A stream's armed state changed.	`{"event":"stream","stream":{"id":"microphone:BuiltInMicrophoneDevice","kind":"microphone","name":"MacBook Pro Microphone","model":"Digital Mic","capabilities":{"audio":{"sampleRate":48000,"channels":1}},"armed":true,"active":{"audio":{"sampleRate":48000,"channels":1}},"framesSeen":0}}`

Conventions

Discovery

GET/

Streams

GET/streams

POST/streams/{id}/arm

Takes

POST/takes

POST/takes/{id}/start

POST/takes/{id}/stop

POST/takes/{id}/join

POST/takes/{id}/leave

POST/takes/{id}/markers

GET/takes/{id}

GET/takes