The API and tokens
Everything the web app does goes through a versioned HTTP API under /api/v1. This page explains how to authenticate, how to create a scoped token, the conventions every endpoint follows, the change feed, live video for your own clients, and webhooks. The full endpoint list is in the endpoint reference, and every scope is described in Token scopes.
Base address and versions
Section titled “Base address and versions”All examples use https://nvr.example.com. The API lives at:
https://nvr.example.com/api/v1Every API response carries X-Aperture-Api-Version: v1. The same endpoints are also mounted without the version, under /api/…; those responses add Deprecation: true and Link: </api/v1>; rel="successor-version". Use /api/v1 in anything you write. (One address stays unversioned on purpose: the single sign-on callback, /api/auth/oidc/callback.)
GET /api/v1/version needs no sign-in and tells a client whether it speaks this server’s contract:
{ "apiVersions": ["v1"], "serverVersion": "…", "schemaVersion": 36 }What “frozen” means
Section titled “What “frozen” means”On an install, v1 becomes a frozen contract the moment the first API token is created or third-party extensions are turned on; GET /api/v1/capabilities reports when as apiV1FrozenAt. From then on, v1 changes only by addition: new endpoints, new optional request fields, new response fields. A breaking change needs a new version. Two consequences for your code:
- Tolerate unknown response fields. Responses can gain fields in any release.
- The extension surface is not part of the freeze. Paths under
/api/v1/ext/are first-party machinery for the web app and the extension SDK and may change (frozenExemptin the capabilities).
Ways to authenticate
Section titled “Ways to authenticate”| Credential | How it is sent | Authority | For |
|---|---|---|---|
| Session cookie | aperture_session cookie |
The signed-in user, all of it | The web app |
| API token | Authorization: Bearer apt_… |
Its scopes, within its owner’s role and cameras | Scripts, integrations |
| Stream token | ?token=… on the live WebSocket |
Live view of one camera, opening within 5 minutes | Live video players |
| CLI token | Authorization: Bearer <cli token> |
A full administrator | nvrctl on the server itself |
API tokens
Section titled “API tokens”An API token is apt_ followed by 48 hex characters. Send it as a Bearer token on every request. Aperture stores only its SHA-256 hash, so it is shown once, when you create it.
A token:
- holds only the scopes you granted, and if you chose cameras, only those cameras;
- never exceeds its owner: it acts with the owner’s current role and camera access, so an administrator-only endpoint also needs an administrator owner, and a viewer’s token sees only the viewer’s cameras;
- stops working when it expires, when it is revoked, or when its owner is disabled, and is deleted with its owner;
- is refused, whatever its scopes, on session-only endpoints: users, tokens, your own password, two-factor, passkeys and devices, backup, restore, restart, purge, reindex and extension management.
There is no endpoint to change a token’s scopes. Create a new token and revoke the old one.
The CLI token
Section titled “The CLI token”The installer’s nvrctl console authenticates with a token in /var/lib/aperture/data/cli.token, readable only by root. It is a full administrator credential that also reaches session-only endpoints. Use it on the server for maintenance and recovery, never in an integration. See nvrctl.
Create a token
Section titled “Create a token”- Open Integrations › API Tokens and click Create token.
- Give it a Name and choose when it Expires: No expiry, 30 days, 90 days or 1 year.
- Choose Scopes. Live view only selects
media:live. Everything selects every scope (“Includes managing cameras, storage, automations and arming the alarm.”). Or tick scopes one by one; at least one is required. - Optionally tick Restrict to specific cameras and choose them. Without it, the token reaches all cameras you can see.
- Click Create token, then copy the token: “Copy your token now — it won’t be shown again.”
The list shows each token’s Name, the first characters of the API key, and when it was Created, Last used and Expires. The bin button (Revoke token) deletes it at once.
Integrations is visible to administrators only. Any signed-in user can manage their own tokens through the API with their session, at /api/v1/tokens:
{ "name": "garage-script", "expiresInDays": 90, "scopes": ["cameras:read", "events:read"], "cameraGrants": [] }The response is {"token": {…}, "secret": "apt_…"}. An empty cameraGrants means all cameras the owner can see.
Quick start
Section titled “Quick start”export APERTURE=https://nvr.example.comexport TOKEN=apt_… # paste your token
# Who am I, and what does this server support?curl -s -H "Authorization: Bearer $TOKEN" "$APERTURE/api/v1/auth/me"curl -s -H "Authorization: Bearer $TOKEN" "$APERTURE/api/v1/capabilities"
# The cameras you may see (cameras:read)curl -s -H "Authorization: Bearer $TOKEN" "$APERTURE/api/v1/cameras"
# A current picture (media:read)curl -s -H "Authorization: Bearer $TOKEN" -o driveway.jpg \ "$APERTURE/api/v1/cameras/<camera id>/snapshot.jpg"
# Events of the last hour (events:read); from and to are unix millisecondsnow=$(date +%s000)curl -s -H "Authorization: Bearer $TOKEN" \ "$APERTURE/api/v1/events?from=$((now - 3600000))&to=$now&limit=100"Conventions
Section titled “Conventions”Errors
Section titled “Errors”Every error is JSON with a human-readable error and a machine-readable code. Match on code, never on the English text.
{ "error": "missing required scope: events:read", "code": "forbidden.scope" }| Code | Status | Meaning |
|---|---|---|
validation |
400 | Malformed body, unknown field, invalid value or cursor |
unauthenticated |
401 | No valid credential |
forbidden |
403 | Wrong role, a session-only endpoint, or a cross-origin browser write |
forbidden.scope |
403 | The token lacks a required scope |
forbidden.camera |
403 | The camera is outside the caller’s access |
forbidden.extension |
403 | A route that acts as one extension, called with a credential that is not that extension’s own token or a signed-in session; see Routes that act as the extension |
not_found |
404 | No such resource, or no such API path |
method_not_allowed |
405 | The path exists, the method does not |
conflict |
409 | The current state does not allow it |
precondition_failed |
412 | If-Match does not match the current resource |
payload_too_large |
413 | The body exceeds the size limit |
precondition_required |
428 | A token write without If-Match |
rate_limited |
429 | Too many requests; see Retry-After |
unavailable |
503 | A subsystem is not available (for example single sign-on not configured) |
internal |
500 | Server error |
An unknown path under /api/v1 returns the JSON not_found error, never the web app’s HTML page.
Strict requests, tolerant responses
Section titled “Strict requests, tolerant responses”A request body may contain only the fields its endpoint accepts. Any other field is rejected with 400 validation, and the message names the field. The usual cause is sending a fetched object straight back: responses include read-only fields such as id, etag or createdAt that a write does not accept. Send only the fields you mean to change; the id belongs in the path and the ETag in the If-Match header.
Responses are the opposite: they can gain fields at any time. Arrays are always arrays, never null, even when empty.
Most timestamps are unix milliseconds, and fields named …Ms always are. Check the unit where it matters: the activity log’s ts and its from/to filters are unix seconds.
Concurrency: ETag and If-Match
Section titled “Concurrency: ETag and If-Match”Configuration resources carry an ETag: in the ETag header of a single-resource GET, and as an etag field on each item of a list. Send it back as If-Match when you change or delete the resource. If the resource changed in the meantime, the write fails with 412; read it again and retry. If-Match: * matches any existing version.
For tokens, If-Match is required on these writes; without it they fail with 428. Sessions and the CLI token may leave it out. Resources with ETags include cameras, users, notification channels and rules, automations, webhooks, storage destinations, schedules, zones, and the settings, site and detection documents.
# Read the schedule and its ETagcurl -s -D headers.txt -o schedule.json -H "Authorization: Bearer $TOKEN" \ "$APERTURE/api/v1/cameras/<camera id>/schedule"grep -i '^etag' headers.txt
# Write it back with that ETag (schedules:write, administrator owner)curl -s -X PUT -H "Authorization: Bearer $TOKEN" -H 'If-Match: "<etag>"' \ -H "Content-Type: application/json" -d @new-schedule.json \ "$APERTURE/api/v1/cameras/<camera id>/schedule"Pagination
Section titled “Pagination”Long collections use keyset pagination: GET /events, GET /system/audit and GET /cameras/{id}/segments. Pass limit (up to 1000) and follow the X-Next-Cursor response header:
curl -s -D - -H "Authorization: Bearer $TOKEN" "$APERTURE/api/v1/events?limit=500"# X-Next-Cursor: <cursor>curl -s -H "Authorization: Bearer $TOKEN" "$APERTURE/api/v1/events?limit=500&cursor=<cursor>"The header is present only when the page was full. When it is missing, you have reached the end. Treat the cursor as opaque; a malformed one is rejected with 400. Default page sizes: 200 for /events and /system/audit, 100 for segments. /system/audit returns at most 500 entries per page; a larger limit is treated as 500.
Idempotency-Key
Section titled “Idempotency-Key”POST /export and POST /shares accept an Idempotency-Key header. A repeated request with the same key, from the same user to the same path, within 24 hours returns the first response again, marked Idempotent-Replay: true, instead of starting a second export. Only successful responses are stored, so a failed attempt can be retried with the same key.
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -H "Idempotency-Key: $(cat /proc/sys/kernel/random/uuid)" \ -d '{"cameraId":"<camera id>","from":1763200000000,"to":1763200300000}' \ "$APERTURE/api/v1/export"An export covers at most 4 hours.
Limits
Section titled “Limits”| Limit | Value |
|---|---|
| JSON request body | 1 MiB |
| Multipart upload (backup restore) | 256 MiB |
| Detection model upload | 2 GiB |
| Requests before sign-in | burst 30, then 10 per second, per client address |
| Session and CLI requests | burst 240, then 120 per second, per user |
| Token requests | burst 40, then 20 per second, shared by all tokens of one owner |
Beyond a rate limit the API answers 429 with Retry-After: 1. Token and session traffic are counted separately, so a busy script cannot slow down the web app.
Cross-origin browsers
Section titled “Cross-origin browsers”Aperture sends no CORS headers. A web page served from another origin cannot call the API from the browser; call it from a server, or use the live WebSocket, which browsers do not restrict by origin.
The change feed
Section titled “The change feed”GET /api/v1/feed (scope events:read) is a Server-Sent Events stream of what changes in Aperture, so a client does not have to poll.
curl -N -H "Authorization: Bearer $TOKEN" "$APERTURE/api/v1/feed?types=event.created"Each message is one JSON envelope:
{ "id": 4821, "type": "event.created", "ts": 1763200000000, "camera": "<camera id>", "data": { "eventId": "…", "eventType": "motion", "score": 0.42 } }- Types include
event.created,event.closed,detection.created,camera.state,alarm.state,export.progress,config.updated,storage.updatedandautomation.updated. Filter with?types=and?cameras=(comma-separated). - Camera access applies to every message: you receive only messages about cameras you may see.
- Resuming: event messages carry an SSE
id. On reconnect, send it asLast-Event-ID(EventSource does this for you), or pass?lastEventId=on the first connect, and missed events are replayed from the database. If the cursor is older than the oldest kept event, you get a{"type":"reset"}message: fetch your state again. - Current state: on connect the feed also sends the latest state messages (camera state and similar), which are not replayable.
- A keep-alive comment arrives every 25 seconds. A token that is revoked or expires mid-stream is cut off within 60 seconds.
OpenAPI and capabilities
Section titled “OpenAPI and capabilities”GET /api/v1/openapi.json returns an OpenAPI 3 description generated from the same route table that enforces access, so the scopes it lists are the ones the server checks. Each operation lists its parameters and error responses and, as extensions, x-required-scopes, x-requires-admin, x-session-only and x-camera-scoped. It describes the request and response bodies of the routes an app uses, checked against the real responses in the tests. Any signed-in credential can fetch it. The endpoint reference is generated from it.
GET /api/v1/capabilities (any credential, no scope) reports which optional subsystems are on (detection, homeAssistant, homeKit, onvif, weather, audio), which contract features exist (cursorPagination, changeFeed, coverageEndpoint, idempotencyKey, etagIfMatch), deprecations, and apiV1FrozenAt. Check it instead of assuming a feature from a version number.
Live video in your own client
Section titled “Live video in your own client”Browsers cannot put an Authorization header on a WebSocket, so live video is authorized by a token in the address.
-
Ask for a stream token (scope
media:live, camera-scoped):Terminal window curl -s -H "Authorization: Bearer $TOKEN" "$APERTURE/api/v1/cameras/<camera id>/stream-token"{ "token": "…", "wsUrl": "/api/v1/cameras/<camera id>/ws?token=…", "hasSub": true, "expiresIn": 300 } -
Within
expiresInseconds (5 minutes), openwss://nvr.example.compluswsUrl. Add&q=subfor the camera’s sub stream whenhasSubis true. Once open, the connection may stay open longer. Each new connection, including a reconnect, needs a token that is still valid: ask for a new one when the old one is near its expiry. -
Speak go2rtc’s WebSocket protocol, which Aperture proxies:
- MSE (fragmented MP4): send
{"type":"mse","value":"avc1.640029,mp4a.40.2"}with the codecs you can play. You receive{"type":"mse","value":"<MIME type with codecs>"}, then binary fMP4 fragments. - WebRTC: send
{"type":"webrtc/offer","value":"<SDP offer>"}and your ICE candidates as{"type":"webrtc/candidate","value":"<candidate>"}. You receivewebrtc/answerandwebrtc/candidatemessages.
- MSE (fragmented MP4): send
A client that cannot make the extra request can pass an API token with media:live directly as ?token=apt_…. Prefer stream tokens: a long-lived token in a URL ends up in proxy logs.
For players on your network, the RTSP restream is simpler: rtsp://<server>:8554/cam_<camera id>, without a login. See ONVIF and RTSP and Live streaming.
Recorded footage is available as an HLS playlist: GET /api/v1/cameras/<camera id>/hls?from=<ms>&to=<ms> (scope media:read).
Webhooks
Section titled “Webhooks”Integrations › Webhooks sends every event as a signed JSON POST to an address you choose. Click Add webhook, enter a Name and a URL, and save. Send test posts {"type":"test","message":"Aperture webhook test","ts":…}.
An event delivery looks like this:
{ "type": "event", "ts": 1763200001234, "event": { "id": "…", "cameraId": "…", "eventType": "motion", "startTs": 1763200000000, "endTs": 0, "score": 0.42, "topLabel": "person", "objects": ["person"] }, "link": "https://nvr.example.com/playback?camera=…&t=1763200000000", "thumbUrl": "https://nvr.example.com/api/events/…/thumb.jpg"}topLabel and objects appear only when objects were recognised; endTs is 0 while the event is still going on. thumbUrl needs authentication (events:read). link and thumbUrl are built from APERTURE_PUBLIC_URL.
Each delivery is sent with Content-Type: application/json, User-Agent: Aperture-Webhook/1 and
X-Aperture-Signature: sha256=<hex HMAC-SHA256 of the raw body, keyed with the webhook's secret>Aperture generates the secret when you create the webhook. The app does not display it; read it with GET /api/v1/webhooks (administrator, scope automation:read), or set your own by passing secret when you create the webhook through the API. To check a delivery in a shell:
printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //'# compare with the part after "sha256=" in X-Aperture-SignatureA delivery is tried up to 3 times, 2 and 4 seconds apart, with a 10-second timeout each; GET /api/v1/webhooks/<id>/deliveries lists the results. Through the API, a webhook’s events list limits it to certain event types (empty means all).
Related: Token scopes, Endpoint reference, Extensions, Security model and hardening.