API endpoints

A curated reference of the controller’s /api/v1 surface, grouped by family. For the authentication model, the RBAC + audit pattern, and error shapes, see Controller API.

Conventions:

• All application routes are under /api/v1; GET /metrics and GET /healthz are at the root.
• Successful responses are { "data": ... }; some writes return 201/202; deletes and logout return 204.
• Perm is the exact RBAC permission checked. Agent rows are authenticated by a node credential, not a user permission (the listed label is the audit permission).

Auth & session — /api/v1/auth

Method & path	Perm	Purpose
POST /auth/login	—	Issue a session token.
POST /auth/logout	—	Revoke the current session.
GET /auth/me	—	Current user + resolved permissions.

OIDC — /api/v1/auth/oidc

Method & path	Perm	Purpose
GET /auth/oidc/config	—	Public OIDC config.
GET /auth/oidc/login	—	Start the login redirect.
GET /auth/oidc/callback	—	Complete login (redirect with token).
GET /auth/oidc/discovery	auth:manage	Fetch IdP discovery doc.

Access / RBAC — /api/v1/auth/*

Method & path	Perm	Purpose
GET /auth/users · POST /auth/users	auth:manage	List / create users.
GET /auth/users/:id	auth:manage	User detail + action states.
PATCH /auth/users/:id/access	auth:manage	Update roles/grants/groups.
PATCH /auth/users/:id/password · /status · DELETE /auth/users/:id	auth:manage	Lifecycle (reset/enable-disable/delete).
GET /auth/groups · POST /auth/groups	auth:manage	List / create groups.
GET /auth/groups/:id	auth:manage	Group detail + members.
PATCH /auth/groups/:id · DELETE /auth/groups/:id	auth:manage	Update name/description / delete (cascade).
PUT /auth/groups/:id/members	auth:manage	Replace membership by member ids.
GET /auth/access-policies · PATCH /auth/access-policies	auth:manage	Read / replace access policies.

Audit — /api/v1/audit-events

Method & path	Perm	Purpose
GET /audit-events	audit:read	List/filter events.
GET|POST /audit-events/export	audit:read	Export (filtered / selected).
GET /audit-events/facets	audit:read	Filter facets.
GET /audit-events/:id	audit:read	Detail + before/after.

Nodes — /api/v1/nodes

Method & path	Perm	Purpose
GET /nodes · GET|POST /nodes/export	node:read	List / export inventory (scoped).
GET /nodes/:id · /:id/actions	node:read	Detail / action summaries.
GET /nodes/:id/meters · GET /meter-events	node:read	Meter snapshot / SSE stream.
GET /nodes/agent-release	node:read	Latest agent release (update check).
POST /nodes/enroll	node:manage	Enroll node (returns credential).
PATCH /nodes/:id · /:id/interfaces/:iid	node:manage	Update node / interface.
PUT /nodes/:id/channel-rooms	node:manage	Assign node channels to rooms.
POST /nodes/:id/credentials/rotate	node:manage	Rotate node controller token.
GET /nodes/:id/ssh-credential · POST /:id/ssh-credential/rotate	node:manage	Read public SSH key / rotate keypair (private key never returned).
POST /nodes/:id/bootstrap-token	node:manage	Mint a single-use, short-TTL day-0 bootstrap token.
GET /nodes/:id/lifecycle-jobs	node:read	List lifecycle runs.
POST /nodes/:id/lifecycle/:action	node:manage	Run an allowlisted lifecycle action.
POST /nodes/:id/listen · GET /:id/listen/stream · DELETE /:id/listen/:sid	listen:monitor	Start ({enhance}) / stream / stop live listen.

Agent service routes (node-credential)

Method & path	Audit perm	Purpose
GET /nodes/:id/config	node:control	Node config + cache policies + capacity.
GET /nodes/:id/channel-map-assignments	node:control	Assigned channel maps.
POST /nodes/:id/heartbeat	node:control	Node heartbeat.
POST /nodes/:id/inventory	node:control	Reconcile interfaces from discovered inventory (startup).
POST /nodes/:id/meter-frame	node:control	Push a meter frame.
POST /nodes/:id/listen/chunk	node:control	Ingest live-listen audio (?rendition).
POST /nodes/:id/health-events	health:acknowledge	Sync a health event.
GET /nodes/:id/recording-jobs/next	recording:control	Poll the next queued job (peek, no lease).
POST /nodes/:id/recording-jobs/claim-next	recording:control	Atomically claim the next queued job.
POST /nodes/:id/recording-jobs/claim-next-group	recording:control	Claim the next queued job + its capture-group siblings (one shared capture).
POST /recording-jobs/:jid/claim	recording:control	Claim a specific queued job by id.
POST /recording-jobs/:jid/heartbeat	recording:control	Job heartbeat.
GET /recording-jobs/:jid	recording:control/recording:read	Read job (dual-mode auth).
POST /recording-jobs/:jid/cancelled · /failed	recording:control	Terminal job state.
PUT /recordings/:rid/cache-file	recording:control	Upload a captured/rendered file (?rendition=raw|enhanced); the primary completes the job, raw is supplementary.

Onboarding & runner routes (special auth)

These two routes are not authenticated by a node credential or a user session — see Node onboarding.

Method & path	Auth	Purpose
POST /nodes/:id/bootstrap	single-use bootstrap token	Day-0: accept node-generated SSH key + inventory, mint controller token.
GET /nodes/:id/ssh-credential/material	runner token (RAKKR_RUNNER_TOKEN)	Runner fetch of the decrypted SSH key (+ ?mintToken=1 for a fresh token).

Recordings — /api/v1/recordings

Method & path	Perm	Purpose
GET /recordings · /facets · /:id · /:id/context · /:id/actions	recording:read	Library reads (scoped).
GET|POST /recordings/export	recording:read	Export manifest (filtered / selected).
POST /recordings	recording:create	Start an ad-hoc recording.
POST /recordings/:id/stop	recording:control	Stop a recording.
POST /recordings/:id/playback · GET /:id/stream	recording:playback	Start / stream playback.
POST /recordings/:id/download · GET /:id/file	recording:download	Prepare / download file.
PATCH /recordings/:id/metadata · /bulk-metadata	recording:edit	Edit / bulk-organize.
DELETE /recordings/:id · POST /recordings/bulk-delete	recording:delete	Delete terminal recordings.

Recording jobs & uploads

Method & path	Perm	Purpose
GET /recording-jobs · /:id · /:id/actions · GET|POST /export	recording:read	Job reads / export.
POST /recording-jobs/:id/retry · /bulk-retry · /bulk-stop	recording:control	Retry / stop jobs.
GET /upload-queue · /:id · /:id/actions	recording:read	Queue reads.
POST /recordings/:id/upload-queue · /bulk-upload-queue · POST /upload-queue/:id/retry	recording:control	Enqueue / retry uploads.
GET /upload-runner · /actions	recording:read	Runner status.
POST /upload-runner/run	recording:control	Trigger a runner pass.

Schedules — /api/v1/schedules

Method & path	Perm	Purpose
GET /schedules · /:id · /:id/occurrences · /:id/actions · GET|POST /export	schedule:read	Reads / occurrences / export.
GET /schedules/calendar	schedule:read	Windowed occurrences across all schedules.
POST /schedules · PATCH /:id · DELETE /:id	schedule:manage	Create / update / delete.
POST /schedules/:id/run-now · /skip-next	schedule:manage	Force / skip the next occurrence.
POST /schedules/:scheduleId/move-occurrence	schedule:manage	Drag-to-reschedule a single occurrence.

Rooms — /api/v1/rooms

Room identity CRUD is inventory-adjacent (node:read / node:manage); the roster (access control) is auth:manage.

Method & path	Perm	Purpose
GET /rooms	node:read	List rooms.
POST /rooms	node:manage	Create a room.
GET /rooms/:roomId	node:read	Room detail.
PATCH /rooms/:roomId	node:manage	Update a room.
DELETE /rooms/:roomId	node:manage	Delete a room.
GET /rooms/:roomId/overview	node:read	Aggregated room page payload.
GET /rooms/:roomId/roster	auth:manage	Read the room roster.
PUT /rooms/:roomId/roster	auth:manage	Replace the manual room roster.

Settings & retention — /api/v1/settings/*

Each settings family supports GET list, GET /:id, and GET /:id/actions reads under settings:read. Mutations require settings:manage.

Family	Read	Manage
Recording profiles	settings:read	POST / PATCH /settings/recording-profiles/:id
Watchdog policies	settings:read	POST / PATCH /settings/watchdog-policies/:id (+ calibrate)
Upload destinations / policies	settings:read	PATCH/POST destinations & policies
Channel-map templates / assignments / plans	settings:read	create/update templates; PUT assignments (+ bulk, rollback); stage/apply plans
Retention policies	settings:read	POST / PATCH /settings/retention-policies/:id
Controller	settings:read	PATCH /settings/controller (weekStartsOn + scheduling defaults)

Switchers — /api/v1/settings/switchers

Method & path	Perm	Purpose
GET /settings/switchers · /:id	switcher:read	List / read switcher config.
GET /settings/switcher-mapping-options	switcher:read	Rooms/users for the map editor.
GET /settings/switchers/:id/mappings	switcher:read	Read input→room / output→user maps.
POST /settings/switchers	switcher:manage	Create a switcher.
PATCH /settings/switchers/:id	switcher:manage	Update a switcher.
DELETE /settings/switchers/:id	switcher:manage	Delete a switcher.
POST /settings/switchers/:id/test	switcher:manage	Connection test.
GET /settings/switchers/:id/config-snapshot	switcher:manage	Read a device config snapshot.
POST /settings/switchers/:id/restore	switcher:manage	Restore a snapshot to the device.
PUT /settings/switchers/:id/mappings	switcher:map	Replace-all input/output mappings.

Health — /api/v1/health-events

Method & path	Perm	Purpose
GET /health-events · /:id · /:id/actions · GET|POST /export	health:read	Reads / export.
POST /health-events · /bulk-lifecycle	health:acknowledge	Create / bulk lifecycle.
POST /health-events/:id/acknowledge · /suppress · /resolve · /reopen	health:acknowledge	Single-event lifecycle.

Status & metrics

Method & path	Perm	Purpose
GET /api/v1/status	node:read	Aggregated scoped status (nodes, recordings, health, uptime).
GET /metrics	metrics:read	Prometheus exposition (root path).
GET /healthz	—	Liveness.
GET /readyz	—	Readiness (503 while the database is unreachable).