Endpoint reference
This page lists all 218 operations on 171 paths of the Aperture API (v1). It is generated from the OpenAPI document the server builds from its own route table, so the scopes and access rules shown are the ones the server enforces. For authentication, errors, pagination, ETags and the change feed, read The API and tokens first; each scope is explained in Token scopes.
How to read this page
Section titled “How to read this page”Paths are relative to the base address https://nvr.example.com/api/v1. Send a token as Authorization: Bearer apt_…; the web app uses its session cookie.
| Column | Meaning |
|---|---|
| Token scopes | Scopes an API token must hold. Sessions and the CLI token are not checked against scopes. |
| Access | Public: no sign-in. Signed in: any credential. Admin: the user, or the token’s owner, must be an administrator. Session only: refused to API tokens. Camera: the {id} in the path is a camera the caller must be allowed to see. |
| Parameters | Path parameters, then query parameters the document declares. Endpoints read more query parameters than are declared here, and a declared default can differ from the endpoint’s real one: see Pagination for page sizes. |
| Errors | Error statuses the document lists for the operation. Every error body has the shape shown under Error. |
| Summary | The operation’s summary from the document. |
| Request | The request body schema. |
| Response | The success response schema. |
The success statuses in the document (200, 201, 204) are derived from the HTTP method and are not listed here; check the response you get. Paths under /ext/ are first-party machinery for the web app and the extension SDK and are not part of the frozen v1 contract.
The live WebSocket GET /cameras/{id}/ws is listed as public because it does not take the usual credentials: it checks the token in its token query parameter instead. See Live video in your own client.
| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /alarm |
Whether the system is armed | alarm:arm |
Signed in | 200: Alarm (application/json) | 401, 403, 429 | ||
PUT /alarm |
Arm or disarm (admin only) | alarm:arm |
Admin | AlarmReq (application/json) | 200: Alarm (application/json) | 400, 401, 403, 412, 428, 429 |
API tokens
Section titled “API tokens”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /tokens |
The caller’s personal API tokens | not for tokens | Session only | 200: APIToken[] (application/json) | 401, 403, 429 | ||
POST /tokens |
Create a personal API token | not for tokens | Session only | CreateTokenReq (application/json) | 200: CreatedToken (application/json) | 400, 401, 403, 429 | |
DELETE /tokens/{id} |
Revoke one of the caller’s tokens | not for tokens | Session only | id (string) |
400, 401, 403, 404, 412, 428, 429 |
Automations
Section titled “Automations”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /automations |
Automations | automation:read |
Admin | 200: AutomationWithETag[] (application/json) | 401, 403, 429 | ||
POST /automations |
Create an automation | automation:write |
Admin | AutomationRequest (application/json) | 200: Automation (application/json) | 400, 401, 403, 429 | |
PUT /automations/{id} |
Replace an automation | automation:write |
Admin | id (string) |
AutomationRequest (application/json) | 200: Automation (application/json) | 400, 401, 403, 404, 412, 428, 429 |
DELETE /automations/{id} |
Delete an automation | automation:write |
Admin | id (string) |
400, 401, 403, 404, 412, 428, 429 | ||
POST /automations/{id}/test |
automation:write |
Admin | id (string) |
400, 401, 403, 404, 429 |
Camera groups
Section titled “Camera groups”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /camera-groups |
Camera groups | cameras:read |
Signed in | 200: CameraGroup[] (application/json) | 401, 403, 429 | ||
POST /camera-groups |
cameras:write |
Admin | 400, 401, 403, 429 | ||||
PUT /camera-groups/{id} |
cameras:write |
Admin | id (string) |
400, 401, 403, 404, 412, 428, 429 | |||
DELETE /camera-groups/{id} |
cameras:write |
Admin | id (string) |
400, 401, 403, 404, 412, 428, 429 |
Cameras
Section titled “Cameras”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /cameras |
Cameras the caller may see | cameras:read |
Signed in | includeDisabled in query (boolean) |
200: Camera[] (application/json) | 401, 403, 429 | |
POST /cameras |
Add a camera (admin) | cameras:write |
Admin | CameraReq (application/json) | 201: CameraConfig (application/json) | 400, 401, 403, 429 | |
POST /cameras/reorder |
cameras:write |
Admin | 400, 401, 403, 429 | ||||
POST /cameras/test |
cameras:write |
Admin | 400, 401, 403, 429 | ||||
GET /cameras/{id} |
One camera | cameras:read |
Camera | id (string) |
200: Camera (application/json) | 401, 403, 404, 429 | |
PUT /cameras/{id} |
Change a camera (admin) | cameras:write |
Admin | id (string) |
CameraReq (application/json) | 200: CameraConfig (application/json) | 400, 401, 403, 404, 412, 428, 429 |
DELETE /cameras/{id} |
cameras:write |
Admin | id (string) |
400, 401, 403, 404, 412, 428, 429 | |||
GET /cameras/{id}/coverage |
Recorded coverage as merged ranges | coverage:read |
Camera | id (string), from in query (integer), to in query (integer), tolerance_ms in query (integer, default 2000) |
200: CoverageRange[] (application/json) | 400, 401, 403, 404, 429 | |
GET /cameras/{id}/destinations |
Where a camera’s footage is recorded and mirrored | storage:read |
Camera | id (string) |
200: CameraDestinations (application/json) | 401, 403, 404, 429 | |
PUT /cameras/{id}/destinations |
storage:write |
Admin, Camera | id (string) |
400, 401, 403, 404, 412, 428, 429 | |||
GET /cameras/{id}/events |
A camera’s events in a window | events:read |
Camera | id (string), from in query (integer), to in query (integer) |
200: Event[] (application/json) | 401, 403, 404, 429 | |
GET /cameras/{id}/frame |
A still from recorded footage | media:read |
Camera | id (string), t in query (integer) |
200: string (image/jpeg) | 400, 401, 403, 404, 410, 429, 500 | |
PUT /cameras/{id}/groups |
cameras:write |
Admin | id (string) |
400, 401, 403, 404, 412, 428, 429 | |||
GET /cameras/{id}/hls |
HLS VOD playlist of recorded footage | media:read |
Camera | id (string), from in query (integer), to in query (integer) |
200: string (application/vnd.apple.mpegurl) | 401, 403, 404, 429 | |
POST /cameras/{id}/lease |
Protect a range of footage from retention | media:read |
Camera | id (string) |
LeaseReq (application/json) | 201: Lease (application/json) | 400, 401, 403, 404, 429 |
DELETE /cameras/{id}/lease/{leaseId} |
Release a lease | media:read |
Camera | id (string), leaseId (string) |
400, 401, 403, 404, 412, 428, 429 | ||
GET /cameras/{id}/onvif |
cameras:read |
Admin, Camera | id (string) |
401, 403, 404, 429 | |||
PUT /cameras/{id}/onvif |
cameras:write |
Admin, Camera | id (string) |
400, 401, 403, 404, 412, 428, 429 | |||
PUT /cameras/{id}/onvif/imaging |
cameras:write |
Admin, Camera | id (string) |
400, 401, 403, 404, 412, 428, 429 | |||
DELETE /cameras/{id}/recordings |
media:write |
Camera | id (string) |
400, 401, 403, 404, 412, 428, 429 | |||
GET /cameras/{id}/schedule |
A camera’s recording schedule windows | schedules:read |
Camera | id (string) |
200: ScheduleWindow[] (application/json) | 401, 403, 404, 429 | |
PUT /cameras/{id}/schedule |
Set a camera’s recording schedule (admin) | schedules:write |
Admin | id (string) |
ScheduleReq (application/json) | 200: StatusOK (application/json) | 400, 401, 403, 404, 412, 428, 429 |
GET /cameras/{id}/seg/{seg} |
One recorded segment (MPEG-TS) | media:read |
Camera | id (string), seg (string), Range in header (string) |
200: string (video/mp2t) | 401, 403, 404, 429 | |
GET /cameras/{id}/segments |
Recorded segments overlapping a window | segments:read |
Camera | id (string), limit in query (integer, default 100, max 1000), cursor in query (string), from in query (integer), to in query (integer) |
200: Segment[] (application/json) | 400, 401, 403, 404, 429 | |
GET /cameras/{id}/sensor |
The Home Assistant sensor reading on this camera’s overlay | cameras:read |
Camera | id (string) |
200: CameraSensor (application/json) | 401, 403, 404, 429 | |
GET /cameras/{id}/snapshot.jpg |
Current frame as JPEG | media:read |
Camera | id (string) |
200: string (image/jpeg) | 401, 403, 404, 429, 503 | |
GET /cameras/{id}/stream-token |
Mint a short-lived live-view token | media:live |
Camera | id (string) |
200: StreamToken (application/json) | 401, 403, 404, 429 | |
GET /cameras/{id}/tracks |
Where recognised objects were over a window | events:read |
Camera | id (string), from in query (integer), to in query (integer) |
200: TrackPoint[] (application/json) | 401, 403, 404, 429 | |
GET /cameras/{id}/vendor |
cameras:read |
Admin, Camera | id (string) |
401, 403, 404, 429 | |||
PUT /cameras/{id}/vendor |
cameras:write |
Admin, Camera | id (string) |
400, 401, 403, 404, 412, 428, 429 | |||
GET /cameras/{id}/ws |
Live view WebSocket | Public | id (string), token in query (string), q in query (string) |
401, 404, 429 | |||
GET /cameras/{id}/zones |
A camera’s motion ignore mask | zones:read |
Camera | id (string) |
200: MotionMask (application/json) | 401, 403, 404, 429 | |
PUT /cameras/{id}/zones |
Set a camera’s motion ignore mask (admin) | zones:write |
Admin | id (string) |
MotionMaskReq (application/json) | 200: MotionMask (application/json) | 400, 401, 403, 404, 412, 428, 429 |
Capabilities
Section titled “Capabilities”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /capabilities |
Optional subsystems and contract features that are live | Signed in | 200: Capabilities (application/json) | 401, 429 |
Change feed
Section titled “Change feed”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /feed |
Change feed (Server-Sent Events) | events:read |
Signed in | types in query (string), cameras in query (string), lastEventId in query (integer), Last-Event-ID in header (integer) |
200: string (text/event-stream) | 401, 403, 429 |
Events
Section titled “Events”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /events |
Events across the cameras the caller may see | events:read |
Signed in | limit in query (integer, default 200, max 1000), cursor in query (string), from in query (integer), to in query (integer) |
200: Event[] (application/json) | 400, 401, 403, 429 | |
GET /events/{id} |
One event | events:read |
Signed in | id (string) |
200: Event (application/json) | 401, 403, 404, 429 | |
GET /events/{id}/detections |
An event’s detected objects | events:read |
Signed in | id (string) |
200: EventObject[] (application/json) | 401, 403, 404, 429 | |
GET /events/{id}/thumb.jpg |
An event’s thumbnail | events:read |
Signed in | id (string), w in query (integer) |
200: string (image/jpeg) | 400, 401, 403, 404, 429 |
Exports
Section titled “Exports”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /export |
The caller’s exports (newest first, at most 100) | media:read |
Signed in | 200: ExportView[] (application/json) | 401, 403, 429 | ||
POST /export |
Export a clip | media:write |
Signed in | Idempotency-Key in header (string) |
ExportReq (application/json) | 201: ExportJob (application/json) | 400, 401, 403, 404, 429 |
GET /export/{id} |
One export | media:read |
Signed in | id (string) |
200: ExportView (application/json) | 401, 403, 404, 429 | |
DELETE /export/{id} |
Delete an export and its file | media:write |
Signed in | id (string) |
200: StatusOK (application/json) | 400, 401, 403, 404, 412, 428, 429 | |
GET /export/{id}/download |
Download a finished export | media:read |
Signed in | id (string) |
200: string (application/zip), 200: string (video/mp4) | 401, 403, 404, 409, 410, 429 |
Extensions
Section titled “Extensions”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /ext |
not for tokens | Admin, Session only | 401, 403, 429 | ||||
POST /ext/gate |
not for tokens | Admin, Session only | 400, 401, 403, 429 | ||||
DELETE /ext/gate |
not for tokens | Admin, Session only | 400, 401, 403, 412, 428, 429 | ||||
POST /ext/install |
not for tokens | Admin, Session only | 400, 401, 403, 429 | ||||
POST /ext/install/confirm |
not for tokens | Admin, Session only | 400, 401, 403, 429 | ||||
POST /ext/install/url |
not for tokens | Admin, Session only | 400, 401, 403, 429 | ||||
GET /ext/nav |
Signed in | 401, 429 | |||||
GET /ext/panels |
Signed in | 401, 429 | |||||
GET /ext/store |
not for tokens | Admin, Session only | 401, 403, 429 | ||||
POST /ext/store/install |
not for tokens | Admin, Session only | 400, 401, 403, 429 | ||||
DELETE /ext/{id} |
not for tokens | Admin, Session only | id (string) |
400, 401, 403, 404, 412, 428, 429 | |||
POST /ext/{id}/broker |
not for tokens | Session only | id (string) |
400, 401, 403, 404, 429 | |||
PUT /ext/{id}/cameras |
not for tokens | Admin, Session only | id (string) |
400, 401, 403, 404, 412, 428, 429 | |||
POST /ext/{id}/disable |
not for tokens | Admin, Session only | id (string) |
400, 401, 403, 404, 429 | |||
POST /ext/{id}/enable |
not for tokens | Admin, Session only | id (string) |
400, 401, 403, 404, 429 | |||
POST /ext/{id}/fetch |
Signed in | id (string) |
400, 401, 403, 404, 429 | ||||
GET /ext/{id}/files |
not for tokens | Admin, Session only | id (string) |
401, 403, 404, 429 | |||
GET /ext/{id}/files/{path} |
not for tokens | Admin, Session only | id (string), path (string) |
401, 403, 404, 429 | |||
PUT /ext/{id}/files/{path} |
not for tokens | Admin, Session only | id (string), path (string) |
400, 401, 403, 404, 412, 428, 429 | |||
GET /ext/{id}/kv |
Signed in | id (string) |
401, 403, 404, 429 | ||||
GET /ext/{id}/kv/{key} |
Signed in | id (string), key (string) |
401, 403, 404, 429 | ||||
PUT /ext/{id}/kv/{key} |
Signed in | id (string), key (string) |
400, 401, 403, 404, 412, 428, 429 | ||||
DELETE /ext/{id}/kv/{key} |
Signed in | id (string), key (string) |
400, 401, 403, 404, 412, 428, 429 | ||||
GET /ext/{id}/logs |
not for tokens | Admin, Session only | id (string) |
401, 403, 404, 429 | |||
POST /ext/{id}/pin |
not for tokens | Admin, Session only | id (string) |
400, 401, 403, 404, 429 | |||
DELETE /ext/{id}/pin |
not for tokens | Admin, Session only | id (string) |
400, 401, 403, 404, 412, 428, 429 | |||
POST /ext/{id}/revert |
not for tokens | Admin, Session only | id (string) |
400, 401, 403, 404, 429 | |||
GET /ext/{id}/settings |
Signed in | id (string) |
401, 403, 404, 429 | ||||
PUT /ext/{id}/settings |
not for tokens | Admin, Session only | id (string) |
400, 401, 403, 404, 412, 428, 429 | |||
GET /ext/{id}/update |
not for tokens | Admin, Session only | id (string) |
401, 403, 404, 429 | |||
POST /ext/{id}/update |
not for tokens | Admin, Session only | id (string) |
400, 401, 403, 404, 429 |
First-run setup
Section titled “First-run setup”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
POST /setup |
Public | 400, 429 | |||||
GET /setup/status |
Whether the first administrator still has to be created (public) | Public | 200: SetupStatus (application/json) | 429 |
Integrations
Section titled “Integrations”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /integrations/live-key |
not for tokens | Admin, Session only | 401, 403, 429 | ||||
POST /integrations/live-key/roll |
not for tokens | Admin, Session only | 400, 401, 403, 429 |
Notifications
Section titled “Notifications”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /notify/channels |
The caller’s notification channels | automation:read |
Signed in | 200: NotifyChannel[] (application/json) | 401, 403, 429 | ||
POST /notify/channels |
Add a notification channel | automation:write |
Signed in | CreateChannelReq (application/json) | 201: NotifyChannel (application/json) | 400, 401, 403, 429 | |
PUT /notify/channels/{id} |
Rename, enable or disable a notification channel | automation:write |
Signed in | id (string) |
UpdateChannelReq (application/json) | 200: NotifyChannel (application/json) | 400, 401, 403, 404, 412, 428, 429 |
DELETE /notify/channels/{id} |
Delete a notification channel | automation:write |
Signed in | id (string) |
200: StatusOK (application/json) | 400, 401, 403, 404, 412, 428, 429 | |
POST /notify/channels/{id}/test |
Send a test notification through a channel | automation:write |
Signed in | id (string) |
200: StatusSent (application/json) | 400, 401, 403, 404, 429, 502 | |
GET /notify/rules |
The caller’s notification rules | automation:read |
Signed in | 200: NotifyRuleItem[] (application/json) | 401, 403, 429 | ||
POST /notify/rules |
Add a notification rule | automation:write |
Signed in | RuleReq (application/json) | 201: NotifyRule (application/json) | 400, 401, 403, 429 | |
PUT /notify/rules/{id} |
Replace a notification rule | automation:write |
Signed in | id (string) |
RuleReq (application/json) | 200: NotifyRule (application/json) | 400, 401, 403, 404, 412, 428, 429 |
DELETE /notify/rules/{id} |
Delete a notification rule | automation:write |
Signed in | id (string) |
200: StatusOK (application/json) | 400, 401, 403, 404, 412, 428, 429 | |
POST /notify/rules/{id}/test |
Send a test notification through every channel of a rule | automation:write |
Signed in | id (string) |
200: RuleTest (application/json) | 400, 401, 403, 404, 429, 502 | |
GET /notify/stream |
In-app notifications (Server-Sent Events) | events:read |
Signed in | 200: string (text/event-stream) | 401, 403, 429 |
OpenAPI document
Section titled “OpenAPI document”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /openapi.json |
Signed in | 401, 429 |
Public links
Section titled “Public links”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /public/event-thumb |
Public | 429 |
Share links
Section titled “Share links”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /shares |
Share links | media:read |
Signed in | user in query (string), all in query (boolean) |
200: Share[] (application/json) | 401, 403, 429 | |
POST /shares |
Create a share link for a finished export | media:write |
Signed in | Idempotency-Key in header (string) |
ShareReq (application/json) | 201: CreatedShare (application/json) | 400, 401, 403, 404, 409, 429 |
DELETE /shares/{id} |
Revoke a share link | media:write |
Signed in | id (string) |
200: StatusOK (application/json) | 400, 401, 403, 404, 412, 428, 429 |
Sign-in and account
Section titled “Sign-in and account”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
POST /auth/2fa/disable |
not for tokens | Session only | 400, 401, 403, 429 | ||||
POST /auth/2fa/enable |
not for tokens | Session only | 400, 401, 403, 429 | ||||
POST /auth/2fa/setup |
not for tokens | Session only | 400, 401, 403, 429 | ||||
POST /auth/login |
Sign in with email and password | Public | LoginReq (application/json) | 200: application/json | 400, 401, 403, 429 | ||
POST /auth/login/2fa |
Complete a two-factor sign-in | Public | Login2FAReq (application/json) | 200: SignIn (application/json) | 400, 401, 404, 429 | ||
POST /auth/logout |
End this session (public: harmless without one) | Public | 200: StatusOK (application/json) | 400, 429 | |||
GET /auth/me |
The signed-in user | Signed in | 200: User (application/json) | 401, 404, 429 | |||
GET /auth/oidc/callback |
Public | 429 | |||||
GET /auth/oidc/login |
Public | 429 | |||||
GET /auth/oidc/status |
Whether single sign-on is offered (public) | Public | 200: OIDCStatus (application/json) | 429 | |||
POST /auth/pair |
Sign the phone app in with a pairing code (public) | Public | PairRedeemReq (application/json) | 200: SignIn (application/json) | 400, 401, 403, 429 | ||
POST /auth/pair/code |
Make a one-time code that pairs the phone app (session-only) | not for tokens | Session only | 200: PairCode (application/json) | 400, 401, 403, 429 | ||
GET /auth/pair/code/status |
What became of the caller’s latest pairing code (session-only) | not for tokens | Session only | 200: PairStatus (application/json) | 401, 403, 429 | ||
POST /auth/passkey/login/begin |
Public | 400, 429 | |||||
POST /auth/passkey/login/finish |
Public | 400, 429 | |||||
POST /auth/passkey/register/begin |
not for tokens | Session only | 400, 401, 403, 429 | ||||
POST /auth/passkey/register/finish |
not for tokens | Session only | 400, 401, 403, 429 | ||||
GET /auth/passkeys |
The caller’s passkeys | Signed in | 200: WebAuthnCred[] (application/json) | 401, 429 | |||
DELETE /auth/passkeys/{id} |
not for tokens | Session only | id (string) |
400, 401, 403, 404, 412, 428, 429 | |||
POST /auth/password |
not for tokens | Session only | 400, 401, 403, 429 | ||||
GET /auth/sessions |
The caller’s signed-in devices (session-only) | not for tokens | Session only | 200: SessionList (application/json) | 401, 403, 429 | ||
POST /auth/sessions/revoke-others |
Sign out every other device | not for tokens | Session only | 200: RevokedOthers (application/json) | 400, 401, 403, 429 | ||
DELETE /auth/sessions/{id} |
Sign one of the caller’s devices out | not for tokens | Session only | id (string) |
200: StatusOK (application/json) | 400, 401, 403, 404, 412, 428, 429 |
System
Section titled “System”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /system/addresses |
This server’s id and addresses (for the phone app) | Signed in | 200: ServerAddrs (application/json) | 401, 429 | |||
GET /system/astro |
Sun and moon for a day at the site | site:read |
Signed in | date in query (string) |
200: Astro (application/json) | 400, 401, 403, 429 | |
GET /system/audit |
Audit log | system:read |
Admin | limit in query (integer, default 200, max 500), cursor in query (string), action in query (string), actor in query (string), from in query (integer), to in query (integer), offset in query (integer) |
200: AuditPage (application/json) | 400, 401, 403, 429 | |
GET /system/audit/verify |
Verify the audit log’s hash chain | system:read |
Admin | 200: AuditVerify (application/json) | 401, 403, 429 | ||
GET /system/backup |
not for tokens | Admin, Session only | 401, 403, 429 | ||||
GET /system/bitrate |
Recorded throughput per minute | system:read |
Signed in | minutes in query (integer, default 30, max 240) |
200: Bitrate (application/json) | 401, 403, 429 | |
GET /system/diagnostics |
Support bundle | system:read |
Admin | 200: string (application/gzip) | 401, 403, 429 | ||
GET /system/geo/resolve |
site:read |
Admin | 401, 403, 429 | ||||
GET /system/geocode |
site:read |
Admin | 401, 403, 429 | ||||
GET /system/hardware |
Hardware profile and what the server detects about itself | site:read |
Signed in | 200: Hardware (application/json) | 401, 403, 429 | ||
PUT /system/hardware |
Confirm the hardware profile | site:write |
Admin | HardwareProfileRequest (application/json) | 200: HardwareSaved (application/json) | 400, 401, 403, 412, 428, 429 | |
GET /system/health |
Liveness probe (public) | Public | 200: StatusOK (application/json) | 429 | |||
GET /system/interop |
ONVIF server and HomeKit bridge state | site:read |
Admin | 200: Interop (application/json) | 401, 403, 429 | ||
PUT /system/interop |
site:write |
Admin | 400, 401, 403, 412, 428, 429 | ||||
GET /system/metrics |
Prometheus metrics | system:read |
Admin | 200: string (text/plain) | 401, 403, 429 | ||
GET /system/oidc |
Single sign-on (OIDC) settings | site:read |
Admin | 200: OIDCSettings (application/json) | 401, 403, 429 | ||
PUT /system/oidc |
site:write |
Admin | 400, 401, 403, 412, 428, 429 | ||||
PUT /system/playback |
site:write |
Admin | 400, 401, 403, 412, 428, 429 | ||||
POST /system/purge |
not for tokens | Admin, Session only | 400, 401, 403, 429 | ||||
POST /system/reindex |
not for tokens | Admin, Session only | 400, 401, 403, 429 | ||||
POST /system/restart |
not for tokens | Admin, Session only | 400, 401, 403, 429 | ||||
POST /system/restore |
not for tokens | Admin, Session only | 400, 401, 403, 429 | ||||
GET /system/settings |
App-wide display settings | site:read |
Signed in | 200: Settings (application/json) | 401, 403, 429 | ||
PUT /system/settings |
Update app-wide display settings | site:write |
Admin | SettingsReq (application/json) | 200: Settings (application/json) | 400, 401, 403, 412, 428, 429 | |
GET /system/site |
The site profile (location, timezone, units) | site:read |
Signed in | 200: Site (application/json) | 401, 403, 429 | ||
PUT /system/site |
Set the site profile | site:write |
Admin | SiteRequest (application/json) | 200: Site (application/json) | 400, 401, 403, 412, 428, 429 | |
GET /system/status |
Live health snapshot | system:read |
Admin | includeDisabled in query (boolean) |
200: SystemStatus (application/json) | 401, 403, 429 | |
GET /system/version |
Server build version (public) | Public | 200: ServerVersion (application/json) | 429 |
System: detection
Section titled “System: detection”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /system/detection |
Object-detection configuration | detection:read |
Admin | 200: DetectionConfig (application/json) | 401, 403, 429 | ||
PUT /system/detection |
detection:write |
Admin | 400, 401, 403, 412, 428, 429 | ||||
POST /system/detection/test |
detection:write |
Admin | 400, 401, 403, 429 |
System: Home Assistant
Section titled “System: Home Assistant”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /system/ha |
Home Assistant (MQTT) settings | site:read |
Admin | 200: HASettings (application/json) | 401, 403, 429 | ||
PUT /system/ha |
site:write |
Admin | 400, 401, 403, 412, 428, 429 | ||||
GET /system/ha/sensors |
site:read |
Admin | 401, 403, 429 |
System: integrations
Section titled “System: integrations”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /system/integrations/eufy |
site:read |
Admin | 401, 403, 429 | ||||
PUT /system/integrations/eufy |
not for tokens | Admin, Session only | 400, 401, 403, 412, 428, 429 | ||||
POST /system/integrations/eufy/captcha |
not for tokens | Admin, Session only | 400, 401, 403, 429 | ||||
POST /system/integrations/eufy/verify-code |
not for tokens | Admin, Session only | 400, 401, 403, 429 |
System: object recognition
Section titled “System: object recognition”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /system/ai |
detection:read |
Admin | 401, 403, 429 | ||||
POST /system/ai/cancel |
detection:write |
Admin | 400, 401, 403, 429 | ||||
POST /system/ai/disable |
detection:write |
Admin | 400, 401, 403, 429 | ||||
POST /system/ai/enable |
detection:write |
Admin | 400, 401, 403, 429 | ||||
DELETE /system/ai/files |
detection:write |
Admin | 400, 401, 403, 412, 428, 429 | ||||
GET /system/ai/gpu |
What this machine needs before Aperture can use an NVIDIA GPU | detection:read |
Admin | 200: GPUSetup (application/json) | 401, 403, 429 | ||
POST /system/ai/models |
detection:write |
Admin | 400, 401, 403, 429 | ||||
DELETE /system/ai/models/{id} |
detection:write |
Admin | id (string) |
400, 401, 403, 404, 412, 428, 429 | |||
GET /system/ai/plan |
detection:read |
Admin | 401, 403, 429 |
System: storage
Section titled “System: storage”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /system/storage |
Storage usage within the allocation | storage:read |
Signed in | includeDisabled in query (boolean) |
200: Storage (application/json) | 401, 403, 429 | |
PUT /system/storage |
storage:write |
Admin | 400, 401, 403, 412, 428, 429 | ||||
GET /system/storage/disk |
The whole recordings disk (allocation wizard) | storage:read |
Admin | 200: DiskStats (application/json) | 401, 403, 429 | ||
GET /system/storage/locations |
Storage locations | storage:read |
Admin | 200: StorageLocations (application/json) | 401, 403, 429 | ||
POST /system/storage/locations |
storage:write |
Admin | 400, 401, 403, 429 | ||||
POST /system/storage/locations/allocate |
storage:write |
Admin | 400, 401, 403, 429 | ||||
POST /system/storage/locations/allocate/preview |
storage:read |
Admin | 400, 401, 403, 429 | ||||
POST /system/storage/locations/assign |
storage:write |
Admin | 400, 401, 403, 429 | ||||
POST /system/storage/locations/reorder |
storage:write |
Admin | 400, 401, 403, 429 | ||||
POST /system/storage/locations/test |
storage:write |
Admin | 400, 401, 403, 429 | ||||
PUT /system/storage/locations/{id} |
storage:write |
Admin | id (string) |
400, 401, 403, 404, 412, 428, 429 | |||
DELETE /system/storage/locations/{id} |
storage:write |
Admin | id (string) |
400, 401, 403, 404, 412, 428, 429 | |||
POST /system/storage/reserve |
storage:write |
Admin | 400, 401, 403, 429 |
System: weather
Section titled “System: weather”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /system/weather |
Weather source configuration and state (admin) | site:read |
Admin | 200: WeatherConfig (application/json) | 401, 403, 429 | ||
PUT /system/weather |
site:write |
Admin | 400, 401, 403, 412, 428, 429 | ||||
GET /system/weather/at |
The weather sample current at a moment | site:read |
Signed in | ts in query (integer) |
200: WeatherSample (application/json) | 400, 401, 403, 404, 429 | |
GET /system/weather/now |
Current weather sample and poller state | site:read |
Signed in | 200: WeatherNow (application/json) | 401, 403, 429 | ||
GET /system/weather/range |
Weather samples in a window | site:read |
Signed in | from in query (integer), to in query (integer) |
200: WeatherRange (application/json) | 400, 401, 403, 429 |
| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /users |
All user accounts | not for tokens | Admin, Session only | 200: UserListItem[] (application/json) | 401, 403, 429 | ||
POST /users |
Create a user account | not for tokens | Admin, Session only | UserReq (application/json) | 201: CreatedUser (application/json) | 400, 401, 403, 409, 429 | |
GET /users/me/preferences |
The caller’s UI preferences (a free-form JSON object) | Signed in | 200: object (application/json) | 401, 429 | |||
PUT /users/me/preferences |
Replace the caller’s UI preferences | Signed in | object (application/json) | 200: object (application/json) | 400, 401, 412, 428, 429 | ||
PUT /users/{id} |
Change a user account | not for tokens | Admin, Session only | id (string) |
UserReq (application/json) | 200: UserListItem (application/json) | 400, 401, 403, 404, 412, 428, 429 |
DELETE /users/{id} |
Delete a user account | not for tokens | Admin, Session only | id (string) |
200: StatusOK (application/json) | 400, 401, 403, 404, 412, 428, 429 |
Version
Section titled “Version”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /version |
API contract version (public, pre-auth) | Public | 200: APIVersion (application/json) | 429 |
Web push
Section titled “Web push”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /push/devices |
The account’s phones registered for push (session-only) | not for tokens | Session only | 200: PushDevice[] (application/json) | 401, 403, 429 | ||
POST /push/devices |
Register the phone app for push notifications (app session only) | not for tokens | Session only | PushRegisterReq (application/json) | 201: PushDevice (application/json) | 400, 401, 403, 429, 503 | |
PATCH /push/devices/{id} |
Change what a phone is notified about | not for tokens | Session only | id (string) |
PushSettingsReq (application/json) | 200: PushDevice (application/json) | 401, 403, 404, 429 |
DELETE /push/devices/{id} |
Stop push notifications to a phone | not for tokens | Session only | id (string) |
200: StatusOK (application/json) | 400, 401, 403, 404, 412, 428, 429 | |
POST /push/devices/{id}/test |
Send a test notification to a phone | not for tokens | Session only | id (string) |
200: PushTest (application/json) | 400, 401, 403, 404, 429, 502 | |
GET /push/key |
The server’s Web Push (VAPID) public key | automation:read |
Signed in | 200: PushKey (application/json) | 401, 403, 429 | ||
POST /push/subscribe |
automation:write |
Signed in | 400, 401, 403, 429 | ||||
POST /push/unsubscribe |
automation:write |
Signed in | 400, 401, 403, 429 |
Webhooks
Section titled “Webhooks”| Endpoint | Summary | Token scopes | Access | Parameters | Request | Response | Errors |
|---|---|---|---|---|---|---|---|
GET /webhooks |
Webhooks | automation:read |
Admin | 200: WebhookListItem[] (application/json) | 401, 403, 429 | ||
POST /webhooks |
Create a webhook | automation:write |
Admin | WebhookRequest (application/json) | 200: Webhook (application/json) | 400, 401, 403, 429 | |
PUT /webhooks/{id} |
Replace a webhook | automation:write |
Admin | id (string) |
WebhookRequest (application/json) | 200: Webhook (application/json) | 400, 401, 403, 404, 412, 428, 429 |
DELETE /webhooks/{id} |
Delete a webhook | automation:write |
Admin | id (string) |
400, 401, 403, 404, 412, 428, 429 | ||
GET /webhooks/{id}/deliveries |
A webhook’s latest deliveries | automation:read |
Admin | id (string) |
200: WebhookDelivery[] (application/json) | 401, 403, 404, 429 | |
POST /webhooks/{id}/test |
automation:write |
Admin | id (string) |
400, 401, 403, 404, 429 |
Components
Section titled “Components”Security schemes
Section titled “Security schemes”| Name | Type | Description |
|---|---|---|
bearerAuth |
http, bearer | A scoped Personal Access Token (apt_…). The array value lists the scopes this operation requires. |
cookieAuth |
apiKey, in cookie, aperture_session |
First-party web session; bypasses scope checks. |
APIToken
Section titled “APIToken”| Field | Type | Required | Description |
|---|---|---|---|
cameraGrants |
string[] | yes | |
createdAt |
integer | yes | |
expiresAt |
integer | yes | |
id |
string | yes | |
lastUsed |
integer | yes | |
name |
string | yes | |
prefix |
string | yes | |
scopes |
string[] | yes | |
userId |
string | yes |
APIVersion
Section titled “APIVersion”| Field | Type | Required | Description |
|---|---|---|---|
apiVersions |
string[] | yes | Contract versions this server speaks, e.g. [“v1”]. |
schemaVersion |
integer | yes | Database schema migration level. |
serverVersion |
string | yes |
| Field | Type | Required | Description |
|---|---|---|---|
armed |
boolean | yes |
AlarmReq
Section titled “AlarmReq”| Field | Type | Required | Description |
|---|---|---|---|
armed |
boolean | yes |
| Field | Type | Required | Description |
|---|---|---|---|
configured |
boolean | yes | |
date |
string | no | YYYY-MM-DD. |
moon |
MoonIllumination | no | |
sun |
SunTimes | no | |
timezone |
string | no |
AuditEntry
Section titled “AuditEntry”| Field | Type | Required | Description |
|---|---|---|---|
action |
string | yes | |
actorEmail |
string | yes | |
actorId |
string | yes | |
detail |
string | yes | |
hash |
string | yes | |
id |
integer | yes | |
ip |
string | yes | |
target |
string | yes | |
ts |
integer | yes | |
ua |
string | yes |
AuditPage
Section titled “AuditPage”| Field | Type | Required | Description |
|---|---|---|---|
actions |
string[] | yes | |
entries |
AuditEntry[] | yes |
AuditVerify
Section titled “AuditVerify”| Field | Type | Required | Description |
|---|---|---|---|
firstTamperedId |
integer | yes | Id of the first entry whose hash does not chain; 0 when intact. |
intact |
boolean | yes |
Automation
Section titled “Automation”| Field | Type | Required | Description |
|---|---|---|---|
actions |
yes | ||
conditions |
yes | ||
cooldownMs |
integer | yes | |
createdAt |
integer | yes | |
enabled |
boolean | yes | |
id |
string | yes | |
lastFired |
integer | yes | |
name |
string | yes | |
trigger |
yes |
AutomationRequest
Section titled “AutomationRequest”| Field | Type | Required | Description |
|---|---|---|---|
actions |
no | ||
conditions |
no | ||
cooldownMs |
integer | no | |
createdAt |
integer | no | |
enabled |
boolean | no | |
id |
string | no | |
lastFired |
integer | no | |
name |
string | no | |
trigger |
no |
AutomationWithETag
Section titled “AutomationWithETag”| Field | Type | Required | Description |
|---|---|---|---|
actions |
yes | ||
conditions |
yes | ||
cooldownMs |
integer | yes | |
createdAt |
integer | yes | |
enabled |
boolean | yes | |
etag |
string | yes | This item’s ETag: send it as If-Match on a write to it. Read-only — never send it in a body. |
id |
string | yes | |
lastFired |
integer | yes | |
name |
string | yes | |
trigger |
yes |
Bitrate
Section titled “Bitrate”| Field | Type | Required | Description |
|---|---|---|---|
buckets |
BitrateBucket[] | yes | |
currentBps |
integer | yes |
BitrateBucket
Section titled “BitrateBucket”| Field | Type | Required | Description |
|---|---|---|---|
bps |
integer | yes | Bits per second averaged over the minute. |
ts |
integer | yes | Minute start, unix ms. |
Camera
Section titled “Camera”| Field | Type | Required | Description |
|---|---|---|---|
audioDetection |
boolean | yes | |
audioThreshold |
number | yes | |
cooldownMs |
integer | yes | |
createdAtMs |
integer | yes | |
detectMethod |
string | yes | Object-detection override: empty = inherit, off, bridge or local. |
enabled |
boolean | yes | |
fps |
integer | yes | |
haPublish |
boolean | yes | Published to Home Assistant / HomeKit. |
id |
string | yes | |
locationId |
string | yes | Storage location for new footage; empty = the default. |
minDurationMs |
integer | yes | |
motionDetection |
boolean | yes | |
motionThreshold |
number | yes | |
name |
string | yes | |
online |
boolean | no | Video is arriving from the camera. Present only for enabled cameras. |
postrollMs |
integer | yes | |
prerollMs |
integer | yes | |
recordFps |
integer | yes | 0 = as the camera sends it. |
recordHeight |
integer | yes | Record at most this tall (px); 0 = as the camera sends it. |
recordKbps |
integer | yes | 0 = automatic. |
recordMode |
string | yes | never, motion, continuous or scheduled. |
recordingNow |
boolean | yes | The recorder should be writing this camera right now (mode + schedule). |
retentionDays |
integer | yes | |
rtspMainUrl |
string | yes | Admins only, login masked; empty for everyone else. |
rtspSubUrl |
string | yes | Admins only, login masked; empty when the camera has no sub stream or the caller is not an admin. |
sortOrder |
integer | yes | |
storageQuotaBytes |
integer | yes | |
tempSensor |
string | yes | Home Assistant sensor entity shown on the overlay; empty = weather. |
updatedAtMs |
integer | yes | |
vendor |
string | yes | Vendor marking that enables local controls (e.g. reolink); empty = none. |
CameraConfig
Section titled “CameraConfig”| Field | Type | Required | Description |
|---|---|---|---|
audioDetection |
boolean | yes | |
audioThreshold |
number | yes | |
cooldownMs |
integer | yes | |
createdAtMs |
integer | yes | |
detectMethod |
string | yes | Object-detection override: empty = inherit, off, bridge or local. |
enabled |
boolean | yes | |
fps |
integer | yes | |
haPublish |
boolean | yes | Published to Home Assistant / HomeKit. |
id |
string | yes | |
locationId |
string | yes | Storage location for new footage; empty = the default. |
minDurationMs |
integer | yes | |
motionDetection |
boolean | yes | |
motionThreshold |
number | yes | |
name |
string | yes | |
postrollMs |
integer | yes | |
prerollMs |
integer | yes | |
recordFps |
integer | yes | 0 = as the camera sends it. |
recordHeight |
integer | yes | Record at most this tall (px); 0 = as the camera sends it. |
recordKbps |
integer | yes | 0 = automatic. |
recordMode |
string | yes | never, motion, continuous or scheduled. |
retentionDays |
integer | yes | |
rtspMainUrl |
string | yes | Admins only, login masked; empty for everyone else. |
rtspSubUrl |
string | yes | Admins only, login masked; empty when the camera has no sub stream or the caller is not an admin. |
sortOrder |
integer | yes | |
storageQuotaBytes |
integer | yes | |
tempSensor |
string | yes | Home Assistant sensor entity shown on the overlay; empty = weather. |
updatedAtMs |
integer | yes | |
vendor |
string | yes | Vendor marking that enables local controls (e.g. reolink); empty = none. |
CameraDestination
Section titled “CameraDestination”| Field | Type | Required | Description |
|---|---|---|---|
locationId |
string | yes | Storage location id; empty = the default location. |
primary |
boolean | yes | New footage is written here (the others are mirrors). |
retentionDays |
integer | yes |
CameraDestinations
Section titled “CameraDestinations”| Field | Type | Required | Description |
|---|---|---|---|
cameraId |
string | yes | |
destinations |
CameraDestination[] | yes |
CameraGroup
Section titled “CameraGroup”| Field | Type | Required | Description |
|---|---|---|---|
cameraIds |
string[] | yes | |
createdAt |
integer | yes | |
id |
string | yes | |
name |
string | yes | |
sortOrder |
integer | yes | |
updatedAt |
integer | yes |
CameraReq
Section titled “CameraReq”| Field | Type | Required | Description |
|---|---|---|---|
audioDetection |
boolean | no | |
audioThreshold |
number | no | |
cooldownMs |
integer | no | |
detectMethod |
string | no | |
enabled |
boolean | no | |
fps |
integer | no | |
haPublish |
boolean | no | |
locationId |
string | no | Storage location for new footage; empty = the default. PUT: an id that names no location is a 400. |
minDurationMs |
integer | no | |
motionDetection |
boolean | no | |
motionThreshold |
number | no | |
name |
string | no | |
postrollMs |
integer | no | |
prerollMs |
integer | no | |
recordFps |
integer | no | |
recordHeight |
integer | no | |
recordKbps |
integer | no | |
recordMode |
string | no | never, motion, continuous or scheduled; empty or absent = keep (PUT) or the default (POST). Anything else is a 400. |
retentionDays |
integer | no | |
rtspMainUrl |
string | no | |
rtspSubUrl |
string | no | |
sortOrder |
integer | no | |
storageQuotaBytes |
integer | no | |
tempSensor |
string | no | |
vendor |
string | no |
CameraSensor
Section titled “CameraSensor”| Field | Type | Required | Description |
|---|---|---|---|
sensor |
yes |
Capabilities
Section titled “Capabilities”| Field | Type | Required | Description |
|---|---|---|---|
apiV1FrozenAt |
string | yes | Unix ms (as a string) when v1 was frozen; empty until then. |
apiVersions |
string[] | yes | |
deprecations |
CapabilityDeprecation[] | yes | |
features |
CapabilityFeatures | yes | |
frozenExempt |
string[] | yes | Path prefixes exempt from the v1 freeze (first-party host machinery). |
schemaVersion |
integer | yes | |
serverVersion |
string | yes | |
subsystems |
CapabilitySubsystems | yes |
CapabilityDeprecation
Section titled “CapabilityDeprecation”| Field | Type | Required | Description |
|---|---|---|---|
successor |
string | yes | |
sunset |
string | yes | Retirement date; null while none is set. |
surface |
string | yes |
CapabilityFeatures
Section titled “CapabilityFeatures”| Field | Type | Required | Description |
|---|---|---|---|
changeFeed |
boolean | yes | |
coverageEndpoint |
boolean | yes | |
cursorPagination |
boolean | yes | |
etagIfMatch |
boolean | yes | |
idempotencyKey |
boolean | yes | |
pdtSeek |
boolean | yes | Seek by the HLS EXT-X-PROGRAM-DATE-TIME tags instead of /segments arithmetic. |
CapabilitySubsystems
Section titled “CapabilitySubsystems”| Field | Type | Required | Description |
|---|---|---|---|
audio |
boolean | yes | At least one camera has audio detection on. |
detection |
boolean | yes | Object detection is on. |
homeAssistant |
boolean | yes | |
homeKit |
boolean | yes | |
onvif |
boolean | yes | |
weather |
boolean | yes | A site location is configured (weather, astro, event conditions). |
CoverageRange
Section titled “CoverageRange”| Field | Type | Required | Description |
|---|---|---|---|
end |
integer | yes | |
start |
integer | yes |
CreateChannelReq
Section titled “CreateChannelReq”| Field | Type | Required | Description |
|---|---|---|---|
config |
object | no | Type-specific settings, write-only (never returned). ntfy: server, topic, token; telegram: token, chatId; discord: webhookUrl; webhook: url; email: host, port, from, to, username, password. |
name |
string | no | Default: the type. |
type |
string | yes | webpush, ntfy, telegram, discord, webhook or email. |
CreateTokenReq
Section titled “CreateTokenReq”| Field | Type | Required | Description |
|---|---|---|---|
cameraGrants |
string[] | no | Camera ids the token is limited to; empty = every camera the owner may see. |
expiresInDays |
integer | no | 0 = never expires. |
name |
string | yes | |
scopes |
string[] | yes | At least one scope (see x-required-scopes on each operation). |
CreatedShare
Section titled “CreatedShare”| Field | Type | Required | Description |
|---|---|---|---|
expiresAt |
integer | yes | Unix seconds; 0 = never. |
id |
string | yes | |
label |
string | yes | |
maxViews |
integer | yes | |
url |
string | yes | The public link (shown only now). Absolute when the server’s public URL is configured, else server-relative. |
CreatedToken
Section titled “CreatedToken”| Field | Type | Required | Description |
|---|---|---|---|
secret |
string | yes | The bearer secret (apt_…). Shown exactly once. |
token |
APIToken | yes |
CreatedUser
Section titled “CreatedUser”| Field | Type | Required | Description |
|---|---|---|---|
cameraIds |
string[] | yes | Cameras a viewer may see. |
disabled |
boolean | yes | |
email |
string | yes | |
etag |
string | yes | The If-Match value for writes to this user. |
generated |
boolean | yes | tempPassword was generated by the server (no password was sent). |
id |
string | yes | |
name |
string | yes | |
role |
string | yes | admin or viewer. |
tempPassword |
string | yes | The account’s first password, shown only now; it must be changed at first sign-in. |
DetectedAccelerator
Section titled “DetectedAccelerator”| Field | Type | Required | Description |
|---|---|---|---|
kind |
string | yes | tpu, npu, gpu or vpu. |
name |
string | yes | |
path |
string | yes |
DetectionConfig
Section titled “DetectionConfig”| Field | Type | Required | Description |
|---|---|---|---|
bridgeApi |
string | yes | deepstack or generic. |
bridgeUrl |
string | yes | |
burst |
integer | yes | |
device |
string | no | auto, cpu or cuda. |
labels |
object | yes | Per-label minimum confidence; non-empty = only these labels. Null when unset. |
minConfidence |
number | yes | |
mode |
string | yes | off, bridge or local. |
model |
string | no | |
modelPath |
string | yes | |
packageMode |
string | no | auto, live or separate. |
packages |
string[] | no | Cameras watching for packages. |
sensitivity |
string | no | low, normal or high. |
DiskStats
Section titled “DiskStats”| Field | Type | Required | Description |
|---|---|---|---|
allocatedBytes |
integer | yes | |
apertureUsedBytes |
integer | yes | |
balloonBytes |
integer | yes | The hard-reservation file. |
freeBytes |
integer | yes | |
marginBytes |
integer | yes | |
maxAllocatableBytes |
integer | yes | |
otherBytes |
integer | yes | |
totalBytes |
integer | yes |
| Field | Type | Required | Description |
|---|---|---|---|
code |
string | yes | Machine-readable code: validation, unauthenticated, forbidden, forbidden.scope, forbidden.camera, forbidden.extension, not_found, method_not_allowed, conflict, precondition_required, precondition_failed, idempotency_conflict, rate_limited, payload_too_large, unavailable, internal. |
details |
object | no | |
error |
string | yes | Human-readable message. |
| Field | Type | Required | Description |
|---|---|---|---|
cameraId |
string | yes | |
conditions |
EventConditions | no | |
endTs |
integer | yes | Unix ms; while ongoing, the time of the response (legacy — prefer endTsMs). |
endTsMs |
integer | yes | Unix ms; null while the event is ongoing. |
id |
string | yes | |
motionCells |
integer[] | no | Indices of the coarse motion-grid cells active during the event. |
objectSummary |
string | no | Short list of detected labels, e.g. “person, car”. |
objects |
EventObject[] | no | |
ongoing |
boolean | yes | |
reviewed |
boolean | yes | |
saved |
boolean | yes | |
score |
number | yes | |
seq |
integer | yes | Monotonic cursor (strictly increasing, not gapless); the /feed id of its event.created. |
startTs |
integer | yes | Unix ms. |
thumbUrl |
string | no | Server-relative thumbnail path; present when the event has one. |
topLabel |
string | no | Highest-confidence detected object label. |
type |
string | yes | What triggered it, e.g. motion or audio. |
EventConditions
Section titled “EventConditions”| Field | Type | Required | Description |
|---|---|---|---|
conditionCode |
integer | no | WMO weather code. |
isNight |
boolean | yes | |
precipMm |
number | no | |
tempC |
number | no | |
windSpeedMs |
number | no |
EventObject
Section titled “EventObject”| Field | Type | Required | Description |
|---|---|---|---|
confidence |
number | yes | |
h |
number | yes | |
id |
integer | yes | |
label |
string | yes | |
ts |
integer | no | |
w |
number | yes | |
x |
number | yes | |
y |
number | yes |
ExportJob
Section titled “ExportJob”| Field | Type | Required | Description |
|---|---|---|---|
audio |
boolean | yes | |
burnIn |
boolean | yes | |
cameraId |
string | yes | |
cameraIds |
string[] | yes | |
cameraName |
string | yes | |
createdAt |
integer | yes | |
error |
string | yes | |
finishedAt |
integer | yes | |
fromTs |
integer | yes | |
id |
string | yes | |
mode |
string | yes | |
progress |
number | yes | |
sizeBytes |
integer | yes | |
speed |
integer | yes | |
status |
string | yes | |
toTs |
integer | yes | |
userId |
string | yes |
ExportReq
Section titled “ExportReq”| Field | Type | Required | Description |
|---|---|---|---|
audio |
boolean | no | |
burnIn |
boolean | no | Burn the timestamp into the picture. |
cameraId |
string | no | One camera (or use cameraIds). |
cameraIds |
string[] | no | Several cameras. |
from |
integer | yes | Unix ms. |
mode |
string | no | For several cameras: zip (default) or composite. |
speed |
integer | no | 0/1 = realtime; N = N× timelapse (max 240). |
to |
integer | yes | Unix ms; at most 4 hours after from. |
ExportView
Section titled “ExportView”| Field | Type | Required | Description |
|---|---|---|---|
audio |
boolean | yes | |
burnIn |
boolean | yes | |
cameraId |
string | yes | |
cameraIds |
string[] | yes | |
cameraName |
string | yes | |
createdAt |
integer | yes | |
deletesAt |
integer | yes | |
error |
string | yes | |
finishedAt |
integer | yes | |
fromTs |
integer | yes | |
id |
string | yes | |
mode |
string | yes | |
progress |
number | yes | |
sharedLinks |
integer | yes | |
sizeBytes |
integer | yes | |
speed |
integer | yes | |
status |
string | yes | |
toTs |
integer | yes | |
userId |
string | yes |
FeedAlarmState
Section titled “FeedAlarmState”| Field | Type | Required | Description |
|---|---|---|---|
armed |
boolean | yes |
FeedCameraState
Section titled “FeedCameraState”| Field | Type | Required | Description |
|---|---|---|---|
state |
string | yes | online or offline. |
FeedCameraUpdated
Section titled “FeedCameraUpdated”| Field | Type | Required | Description |
|---|---|---|---|
cameraId |
string | yes | The camera whose configuration, motion mask or schedule was saved; refetch it. |
FeedConfigUpdated
Section titled “FeedConfigUpdated”| Field | Type | Required | Description |
|---|---|---|---|
domain |
string | yes |
FeedDetectionCreated
Section titled “FeedDetectionCreated”| Field | Type | Required | Description |
|---|---|---|---|
eventId |
string | yes |
FeedEventClosed
Section titled “FeedEventClosed”| Field | Type | Required | Description |
|---|---|---|---|
endTsMs |
integer | yes | |
eventId |
string | yes |
FeedEventCreated
Section titled “FeedEventCreated”| Field | Type | Required | Description |
|---|---|---|---|
eventId |
string | yes | |
eventType |
string | yes | |
score |
number | yes |
FeedExportProgress
Section titled “FeedExportProgress”| Field | Type | Required | Description |
|---|---|---|---|
exportId |
string | yes | |
progress |
number | yes |
FeedMessage
Section titled “FeedMessage”| Field | Type | Required | Description |
|---|---|---|---|
camera |
string | no | The camera the message is about, when there is one. |
data |
no | Type-specific payload (FeedEventCreated, FeedEventClosed, …). | |
id |
integer | no | Durable messages: the event seq (also the SSE id). Ephemeral: an in-process counter. Absent on reset. |
ts |
integer | no | Unix ms. Absent on reset. |
type |
string | yes |
GPUInfo
Section titled “GPUInfo”| Field | Type | Required | Description |
|---|---|---|---|
branch |
string | yes | |
deviceId |
string | yes | |
family |
string | yes | |
minDriver |
integer | no | |
name |
string | yes | |
openModules |
boolean | yes | |
openRequired |
boolean | yes | |
pci |
string | yes |
GPUSetup
Section titled “GPUSetup”| Field | Type | Required | Description |
|---|---|---|---|
driver |
string | no | |
driverOpen |
boolean | no | |
gpu |
GPUInfo | no | |
kernel |
string | yes | |
os |
OSInfo | yes | |
ready |
boolean | yes | |
secureBoot |
string | no | |
smi |
string | no | |
steps |
SetupStep[] | yes | |
sudo |
boolean | yes | |
vm |
string | no |
HASettings
Section titled “HASettings”| Field | Type | Required | Description |
|---|---|---|---|
broker |
string | yes | |
connected |
boolean | yes | |
enabled |
boolean | yes | |
hasPassword |
boolean | yes | |
prefix |
string | yes | |
sensorTopic |
string | yes | |
streams |
HAStream[] | yes | |
username |
string | yes |
HAStream
Section titled “HAStream”| Field | Type | Required | Description |
|---|---|---|---|
cameraId |
string | yes | |
name |
string | yes | |
rtsp |
string | yes |
Hardware
Section titled “Hardware”| Field | Type | Required | Description |
|---|---|---|---|
detected |
HardwareDetected | yes | |
profile |
yes |
HardwareAccelerator
Section titled “HardwareAccelerator”| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | |
name |
string | yes |
HardwareAcceleratorRequest
Section titled “HardwareAcceleratorRequest”| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | |
name |
string | yes |
HardwareDetected
Section titled “HardwareDetected”| Field | Type | Required | Description |
|---|---|---|---|
accelerators |
DetectedAccelerator[] | yes | |
arch |
string | yes | |
board |
string | no | Single-board computers: the board model. |
cpuModel |
string | yes | |
cpuQuota |
number | yes | Cores Aperture’s cgroup may use; 0 = unlimited. |
logicalCpus |
integer | yes | |
memLimitBytes |
integer | yes | Aperture’s cgroup memory limit; 0 = unlimited. |
memTotalBytes |
integer | yes | |
virtual |
string | no | Hypervisor, when this is a virtual machine. |
HardwareProfile
Section titled “HardwareProfile”| Field | Type | Required | Description |
|---|---|---|---|
accelerator |
yes | ||
cpuId |
string | yes | Catalogue id of the CPU. |
cpuName |
string | yes | |
nicGbps |
number | yes | Network link, Gbit/s (0.01..800). |
ramGb |
number | yes | Memory Aperture may use, GB (0.25..16384). |
threads |
integer | yes | CPU threads Aperture may use (1..2048). |
updatedAt |
integer | yes |
HardwareProfileRequest
Section titled “HardwareProfileRequest”| Field | Type | Required | Description |
|---|---|---|---|
accelerator |
HardwareAcceleratorRequest | no | |
cpuId |
string | yes | Catalogue id of the CPU. |
cpuName |
string | yes | |
nicGbps |
number | yes | Network link, Gbit/s (0.01..800). |
ramGb |
number | yes | Memory Aperture may use, GB (0.25..16384). |
threads |
integer | yes | CPU threads Aperture may use (1..2048). |
updatedAt |
integer | no |
HardwareSaved
Section titled “HardwareSaved”| Field | Type | Required | Description |
|---|---|---|---|
profile |
HardwareProfile | yes |
Interop
Section titled “Interop”| Field | Type | Required | Description |
|---|---|---|---|
homekit |
InteropService | yes | |
onvif |
InteropService | yes |
InteropService
Section titled “InteropService”| Field | Type | Required | Description |
|---|---|---|---|
addr |
string | no | ONVIF: listen address. |
available |
boolean | yes | Built into this binary. |
enabled |
boolean | yes | |
error |
string | no | Why it last failed to start or stopped. |
pin |
string | no | HomeKit: pairing code. |
running |
boolean | yes |
| Field | Type | Required | Description |
|---|---|---|---|
cameraId |
string | yes | |
expiresAt |
integer | yes | |
fromTs |
integer | yes | |
holder |
string | yes | |
id |
string | yes | |
toTs |
integer | yes |
LeaseReq
Section titled “LeaseReq”| Field | Type | Required | Description |
|---|---|---|---|
fromTs |
integer | yes | Unix ms. |
toTs |
integer | yes | Unix ms; must exceed fromTs. |
ttlSec |
integer | no | Seconds to hold the lease (default and maximum 7200). |
LocationCamera
Section titled “LocationCamera”| Field | Type | Required | Description |
|---|---|---|---|
cameraId |
string | yes | |
name |
string | yes | |
primary |
boolean | yes | New footage is written here (otherwise it is mirrored here). |
retentionDays |
integer | yes |
Login2FAReq
Section titled “Login2FAReq”| Field | Type | Required | Description |
|---|---|---|---|
client |
string | no | “app” signs in as the phone app: the response carries sessionToken and sets no cookie. The token works as Authorization: Bearer and as the aperture_session cookie. Omit in a browser. |
code |
string | yes | TOTP code or a one-time recovery code. |
deviceName |
string | no | App sign-in: the device’s name, shown in the signed-in devices list (at most 80 characters). |
platform |
string | no | App sign-in, required with client “app”: ios, ipados or android. |
token |
string | yes | |
trustDevice |
boolean | no | Remember this device so its next password sign-in skips the code. Default true. |
LoginReq
Section titled “LoginReq”| Field | Type | Required | Description |
|---|---|---|---|
client |
string | no | “app” signs in as the phone app: the response carries sessionToken and sets no cookie. The token works as Authorization: Bearer and as the aperture_session cookie. Omit in a browser. |
deviceName |
string | no | App sign-in: the device’s name, shown in the signed-in devices list (at most 80 characters). |
email |
string | yes | |
password |
string | yes | |
platform |
string | no | App sign-in, required with client “app”: ios, ipados or android. |
MoonIllumination
Section titled “MoonIllumination”| Field | Type | Required | Description |
|---|---|---|---|
angle |
number | yes | |
fraction |
number | yes | |
name |
string | yes | |
phase |
number | yes |
MotionMask
Section titled “MotionMask”| Field | Type | Required | Description |
|---|---|---|---|
cols |
integer | yes | |
ignore |
integer[] | yes | |
rows |
integer | yes |
MotionMaskReq
Section titled “MotionMaskReq”| Field | Type | Required | Description |
|---|---|---|---|
cols |
integer | no | Grid columns, 0..64. |
ignore |
integer[] | no | Row-major cell indices to ignore; out-of-range and repeated ones are dropped. |
rows |
integer | no | Grid rows, 0..36. |
NotifyChannel
Section titled “NotifyChannel”| Field | Type | Required | Description |
|---|---|---|---|
createdAt |
integer | yes | Unix seconds. |
enabled |
boolean | yes | |
etag |
string | yes | If-Match value for writes to this channel. |
id |
string | yes | |
name |
string | yes | |
type |
string | yes | webpush, ntfy, telegram, discord, webhook or email. |
NotifyRule
Section titled “NotifyRule”| Field | Type | Required | Description |
|---|---|---|---|
cameras |
string[] | yes | |
channels |
string[] | yes | |
conditions |
RuleConditions | yes | |
cooldownSec |
integer | yes | |
createdAt |
integer | yes | |
enabled |
boolean | yes | |
eventTypes |
string[] | yes | |
id |
string | yes | |
name |
string | yes | |
quietEnd |
integer | yes | |
quietStart |
integer | yes | |
userId |
string | yes |
NotifyRuleConditions
Section titled “NotifyRuleConditions”| Field | Type | Required | Description |
|---|---|---|---|
objects |
string[] | yes | Require one of these detected labels. |
onlyPrecip |
boolean | yes | |
timeOfDay |
string | yes | Empty, day or night. |
NotifyRuleItem
Section titled “NotifyRuleItem”| Field | Type | Required | Description |
|---|---|---|---|
cameras |
string[] | yes | Camera ids; empty or null = all. |
channels |
string[] | yes | Channel ids to notify. |
conditions |
NotifyRuleConditions | yes | |
cooldownSec |
integer | yes | |
createdAt |
integer | yes | Unix seconds. |
enabled |
boolean | yes | |
etag |
string | yes | If-Match value for writes to this rule. |
eventTypes |
string[] | yes | Event types; empty or null = all. |
id |
string | yes | |
name |
string | yes | |
quietEnd |
integer | yes | |
quietStart |
integer | yes | Quiet hours start, minutes after local midnight. |
userId |
string | yes |
NotifyStreamMessage
Section titled “NotifyStreamMessage”| Field | Type | Required | Description |
|---|---|---|---|
body |
string | yes | |
camera |
string | yes | Camera name. |
cameraId |
string | yes | |
thumbUrl |
string | yes | Signed, time-limited thumbnail URL; empty when the event has none. |
title |
string | yes | |
ts |
integer | yes | Event start, unix ms. |
type |
string | yes | Event type, e.g. motion. |
url |
string | yes | Where the notification should open. |
OIDCSettings
Section titled “OIDCSettings”| Field | Type | Required | Description |
|---|---|---|---|
allowMissingEmailVerified |
boolean | yes | |
autoCreate |
boolean | yes | |
clientId |
string | yes | |
domain |
string | yes | Allowed email domain; empty = any. |
enabled |
boolean | yes | |
hasSecret |
boolean | yes | |
issuer |
string | yes | |
name |
string | yes | Button label. |
redirectUrl |
string | yes |
OIDCStatus
Section titled “OIDCStatus”| Field | Type | Required | Description |
|---|---|---|---|
enabled |
boolean | yes | |
name |
string | yes | Button label for the single sign-on provider. |
OSInfo
Section titled “OSInfo”| Field | Type | Required | Description |
|---|---|---|---|
codename |
string | no | |
id |
string | yes | |
pretty |
string | yes | |
repoDist |
string | no | |
supported |
boolean | yes | |
version |
string | yes |
PairCode
Section titled “PairCode”| Field | Type | Required | Description |
|---|---|---|---|
code |
string | yes | The one-time code (22 characters, base64url). |
expiresAtMs |
integer | yes | When it stops working (5 minutes after it was made). |
qrPng |
string | yes | A QR code of url: data:image/png;base64,… |
url |
string | yes | aperture://pair?v=1&id= |
PairRedeemReq
Section titled “PairRedeemReq”| Field | Type | Required | Description |
|---|---|---|---|
client |
string | no | “app” signs in as the phone app: the response carries sessionToken and sets no cookie. The token works as Authorization: Bearer and as the aperture_session cookie. Omit in a browser. |
code |
string | yes | The one-time code from the QR code (POST /auth/pair/code). |
deviceName |
string | no | App sign-in: the device’s name, shown in the signed-in devices list (at most 80 characters). |
platform |
string | no | App sign-in, required with client “app”: ios, ipados or android. |
PairStatus
Section titled “PairStatus”| Field | Type | Required | Description |
|---|---|---|---|
deviceName |
string | no | used: the name the phone app sent. |
expiresAtMs |
integer | no | pending and expired: when the code stops or stopped working. |
platform |
string | no | used: ios, ipados or android. |
sessionId |
string | no | used: the phone’s new session, as listed by GET /auth/sessions. |
state |
string | yes | What became of the caller’s latest pairing code: none (none made since the server started), pending, used or expired. |
usedAtMs |
integer | no | used: when the phone was paired. |
PushDevice
Section titled “PushDevice”| Field | Type | Required | Description |
|---|---|---|---|
cameras |
string[] | yes | Camera ids, or null for every camera the account may see. |
createdAtMs |
integer | yes | |
current |
boolean | yes | Registered by the session making this request. |
deviceName |
string | yes | |
enabled |
boolean | yes | |
id |
string | yes | |
kinds |
string[] | yes | Any of person, vehicle, animal, package, motion, audio. |
lastError |
string | yes | Why the last failed delivery failed; empty for none. |
lastErrorAtMs |
integer | yes | |
lastSentAtMs |
integer | yes | The last notification the relay accepted; 0 for none. |
locale |
string | yes | |
platform |
string | yes | ios, ipados or android. |
relayUrl |
string | yes | |
updatedAtMs |
integer | yes |
PushKey
Section titled “PushKey”| Field | Type | Required | Description |
|---|---|---|---|
publicKey |
string | yes | VAPID application server key (base64url). |
PushRegisterReq
Section titled “PushRegisterReq”| Field | Type | Required | Description |
|---|---|---|---|
deviceId |
string | yes | The id the relay gave the phone (base64url, 16 to 128 characters). |
deviceName |
string | no | Shown in the list of phones (at most 80 characters). Default: the name the app signed in with. |
locale |
string | no | The phone’s language, e.g. de-DE (letters, digits, - and _). |
payloadKey |
string | yes | Standard base64 of 32 random bytes made on the phone: the AES-256-GCM key notifications are encrypted with. Write-only. |
platform |
string | no | ios, ipados or android. Default: the platform the app signed in with. |
relaySecret |
string | yes | The secret the relay gave the phone: base64url (no padding) of 32 bytes. Requests to the relay are signed with HMAC-SHA256 keyed with those 32 bytes. Write-only. |
relayUrl |
string | yes | The push relay the phone registered with. It must be one of the server’s allowed relays (APERTURE_PUSH_RELAYS, by default https://push.aperturenvr.com). |
PushSettingsReq
Section titled “PushSettingsReq”| Field | Type | Required | Description |
|---|---|---|---|
cameras |
string[] | no | Camera ids to be told about, or null for every camera the account may see. |
enabled |
boolean | no | Turn this phone’s notifications on or off. |
kinds |
string[] | no | Any of person, vehicle, animal, package, motion, audio. |
PushTest
Section titled “PushTest”| Field | Type | Required | Description |
|---|---|---|---|
status |
string | yes | “sent” (200), or “queued” (202) when the relay had not answered within 5 s; the push continues either way. |
RevokedOthers
Section titled “RevokedOthers”| Field | Type | Required | Description |
|---|---|---|---|
forgotten |
integer | yes | Trusted devices forgotten. |
signedOut |
integer | yes | Sessions ended. |
RuleConditions
Section titled “RuleConditions”| Field | Type | Required | Description |
|---|---|---|---|
objects |
string[] | yes | |
onlyPrecip |
boolean | yes | |
timeOfDay |
string | yes |
RuleConditionsRequest
Section titled “RuleConditionsRequest”| Field | Type | Required | Description |
|---|---|---|---|
objects |
string[] | no | |
onlyPrecip |
boolean | no | |
timeOfDay |
string | no |
RuleReq
Section titled “RuleReq”| Field | Type | Required | Description |
|---|---|---|---|
cameras |
string[] | no | Camera ids; empty = all. |
channels |
string[] | no | Channel ids to notify. |
conditions |
RuleConditionsRequest | no | |
cooldownSec |
integer | no | |
enabled |
boolean | no | |
eventTypes |
string[] | no | Event types; empty = all. |
name |
string | no | |
quietEnd |
integer | no | |
quietStart |
integer | no | Quiet hours start, minutes after local midnight (-1 = none; on create 0 with quietEnd 0 = none). |
RuleTest
Section titled “RuleTest”| Field | Type | Required | Description |
|---|---|---|---|
sent |
integer | yes | Channels that took the test message. |
ScheduleReq
Section titled “ScheduleReq”| Field | Type | Required | Description |
|---|---|---|---|
windows |
ScheduleWindowReq[] | no | Every window; an empty list clears the schedule. |
ScheduleWindow
Section titled “ScheduleWindow”| Field | Type | Required | Description |
|---|---|---|---|
endMin |
integer | yes | Minutes after local midnight; after startMin. |
startMin |
integer | yes | Minutes after local midnight. |
weekday |
integer | yes | 0 = Sunday … 6 = Saturday. |
ScheduleWindowReq
Section titled “ScheduleWindowReq”| Field | Type | Required | Description |
|---|---|---|---|
endMin |
integer | no | Minutes after local midnight, 0..1440; after startMin. |
startMin |
integer | no | Minutes after local midnight, 0..1440. |
weekday |
integer | no | 0 = Sunday … 6 = Saturday. |
Segment
Section titled “Segment”| Field | Type | Required | Description |
|---|---|---|---|
durationMs |
integer | yes | |
endTs |
integer | yes | Unix ms. |
hasMotion |
boolean | yes | |
id |
string | yes | |
startTs |
integer | yes | Unix ms. |
Sensor
Section titled “Sensor”| Field | Type | Required | Description |
|---|---|---|---|
deviceClass |
string | yes | |
entityId |
string | yes | |
name |
string | yes | |
unit |
string | yes | |
updatedAt |
integer | yes | |
value |
string | yes |
ServerAddrs
Section titled “ServerAddrs”| Field | Type | Required | Description |
|---|---|---|---|
local |
string[] | yes | http addresses of this machine on its networks, at the web port. |
name |
string | yes | The site name (Settings). |
remote |
string | yes | The configured public address (APERTURE_PUBLIC_URL) when it is https, otherwise null. |
serverId |
string | yes | This server’s stable id: the same whichever address it is reached at. |
ServerVersion
Section titled “ServerVersion”| Field | Type | Required | Description |
|---|---|---|---|
commit |
string | yes | |
version |
string | yes |
Session
Section titled “Session”| Field | Type | Required | Description |
|---|---|---|---|
client |
string | yes | “app” for the phone app, empty for a browser. |
createdAtMs |
integer | yes | |
current |
boolean | yes | The session making this request. |
deviceName |
string | yes | The phone app’s device name; empty for a browser. |
expiresAtMs |
integer | yes | |
id |
string | yes | |
ip |
string | yes | |
lastSeenAtMs |
integer | yes | |
platform |
string | yes | The phone app’s platform (ios, ipados, android); empty for a browser. |
trusted |
boolean | yes | Its device skips the two-factor code. |
userAgent |
string | yes |
SessionList
Section titled “SessionList”| Field | Type | Required | Description |
|---|---|---|---|
sessions |
Session[] | yes | |
trustedDevices |
integer | yes | Devices that skip the two-factor code. |
Settings
Section titled “Settings”| Field | Type | Required | Description |
|---|---|---|---|
hardwareEncoding |
string | yes | auto (re-encode on a hardware encoder when one works) or off (always the CPU). |
overviewTempSensor |
string | yes | Home Assistant entity shown as the overview temperature; empty = weather. |
recordQuality |
string | yes | high (main streams) or low (sub streams where a camera has one). |
siteName |
string | yes | |
spotlightsEnabled |
boolean | yes |
SettingsReq
Section titled “SettingsReq”| Field | Type | Required | Description |
|---|---|---|---|
hardwareEncoding |
string | no | auto or off: whether cameras recorded at a lower quality are re-encoded on a hardware encoder (a GPU) when one works, or always on the CPU. |
overviewTempSensor |
string | no | Home Assistant entity; empty = weather. |
recordQuality |
string | no | high or low (low = record sub streams). |
siteName |
string | no | Empty = the default name. |
spotlightsEnabled |
boolean | no |
SetupStatus
Section titled “SetupStatus”| Field | Type | Required | Description |
|---|---|---|---|
needsSetup |
boolean | yes | True until the first administrator exists (POST /setup). |
SetupStep
Section titled “SetupStep”| Field | Type | Required | Description |
|---|---|---|---|
commands |
string[] | no | |
detail |
string | no | |
id |
string | yes | |
link |
string | no | |
note |
string | no | |
state |
string | yes | |
title |
string | yes |
| Field | Type | Required | Description |
|---|---|---|---|
createdAt |
integer | yes | Unix seconds. |
createdBy |
string | yes | User id. |
expiredReason |
string | yes | Why it no longer plays: revoked, time, views or clip; empty while active. |
expiresAt |
integer | yes | Unix seconds; 0 = never. |
exportId |
string | yes | |
hasPassword |
boolean | yes | |
id |
string | yes | |
label |
string | yes | |
maxViews |
integer | yes | |
revoked |
boolean | yes | |
sizeBytes |
integer | yes | Disk the link keeps on the NVR; 0 once its clip is gone. |
status |
string | yes | active or expired. |
views |
integer | yes |
ShareReq
Section titled “ShareReq”| Field | Type | Required | Description |
|---|---|---|---|
expiresHours |
integer | no | 0 = never expires. |
exportId |
string | yes | |
label |
string | no | Default: “ |
maxViews |
integer | no | 0 = unlimited. |
password |
string | no | Optional viewer password. |
SignIn
Section titled “SignIn”| Field | Type | Required | Description |
|---|---|---|---|
email |
string | yes | |
id |
string | yes | |
mustChangePassword |
boolean | yes | |
name |
string | yes | |
passkeys |
integer | yes | Number of registered passkeys. |
preferences |
object | yes | The user’s UI preferences (free-form JSON object, PUT /users/me/preferences). |
role |
string | yes | admin or viewer. |
sessionToken |
string | no | Phone-app sign-in only: the session token. Send it as Authorization: Bearer, or as the aperture_session cookie (the video player). It slides with use and ends after 90 days unused, 365 days after sign-in, or when revoked; a 401 means sign in again. |
twoFactor |
boolean | yes | TOTP two-factor sign-in is on. |
| Field | Type | Required | Description |
|---|---|---|---|
addressLabel |
string | yes | |
configured |
boolean | yes | |
elevationM |
number | yes | |
lat |
number | yes | |
lon |
number | yes | |
timezone |
string | yes | |
units |
Units | yes |
SiteRequest
Section titled “SiteRequest”| Field | Type | Required | Description |
|---|---|---|---|
addressLabel |
string | no | |
configured |
boolean | no | |
elevationM |
number | no | |
lat |
number | no | |
lon |
number | no | |
timezone |
string | no | |
units |
UnitsRequest | no |
StatusCamera
Section titled “StatusCamera”| Field | Type | Required | Description |
|---|---|---|---|
cameraId |
string | yes | |
coveragePercent |
integer | no | Continuous cameras: today’s recorded share of the day so far. |
enabled |
boolean | yes | |
lastSegmentTs |
integer | yes | Unix ms; 0 = none. |
liveOk |
boolean | yes | |
name |
string | yes | |
online |
boolean | yes | Video is arriving from the camera. |
recordDecoder |
string | no | Re-encoding only: where the stream is decoded, cpu or gpu. |
recordEncoder |
string | no | How the recording is made now: copy (the stream as the camera sends it), cpu (re-encoded with libx264) or nvenc (re-encoded on an NVIDIA GPU). Absent while no recorder runs. |
recordEncoderNote |
string | no | Why a re-encoding camera isn’t fully on the GPU: hardwareOff, noHardware, sessionLimit, hardwareFailed, gpuDecodeFailed or unsupported; reencodeFailed when re-encoding kept failing and the original stream is recorded. |
recordMode |
string | yes | |
recordingExpected |
boolean | yes | |
recordingOk |
boolean | yes | A segment arrived within the grace window. |
recordingState |
string | yes | recording, notScheduled, off or failed (only failed is a problem). |
restartsToday |
integer | no | |
watchdogLastSeen |
integer | no | Unix ms the watchdog last saw footage. |
watchdogStale |
boolean | no |
StatusGo2RTC
Section titled “StatusGo2RTC”| Field | Type | Required | Description |
|---|---|---|---|
reachable |
boolean | yes | |
streams |
integer | yes | Streams registered with go2rtc. |
StatusHA
Section titled “StatusHA”| Field | Type | Required | Description |
|---|---|---|---|
connected |
boolean | yes | |
enabled |
boolean | yes |
StatusHWEncoder
Section titled “StatusHWEncoder”| Field | Type | Required | Description |
|---|---|---|---|
available |
boolean | yes | The driver, its libraries and ffmpeg support are present and its last test encode, if any, passed. |
device |
string | no | The GPU, when available and known. |
encoder |
string | no | The hardware encoder Aperture knows for this platform: nvenc (NVIDIA). |
name |
string | no | Its name for people, e.g. NVIDIA NVENC. |
reason |
string | no | Why it is not available. |
sessionLimit |
integer | yes | Sessions the driver allows at once (machine-wide); 0 = no limit. Cameras past it re-encode on the CPU. |
sessionsInUse |
integer | yes | Encoder sessions Aperture’s recorders hold. |
setting |
string | yes | auto or off (PUT /system/settings hardwareEncoding). |
StatusOK
Section titled “StatusOK”| Field | Type | Required | Description |
|---|---|---|---|
status |
string | yes | Always “ok”. |
StatusSent
Section titled “StatusSent”| Field | Type | Required | Description |
|---|---|---|---|
status |
string | yes | Always “sent”. |
StatusStorage
Section titled “StatusStorage”| Field | Type | Required | Description |
|---|---|---|---|
allocatedBytes |
integer | yes | Default (local) location only. |
freeBytes |
integer | yes | |
totalAllocatedBytes |
integer | yes | Every enabled destination. |
totalFreeBytes |
integer | yes | |
usedBytes |
integer | yes |
Storage
Section titled “Storage”| Field | Type | Required | Description |
|---|---|---|---|
allocatedBytes |
integer | yes | 0 = no allocation set (unlimited). |
appBytes |
integer | yes | |
cameras |
StorageCamera[] | yes | |
capBytes |
integer | yes | Same as allocatedBytes. |
dataDir |
string | yes | |
defaultPath |
string | yes | |
diskFreeBytes |
integer | yes | |
diskTotalBytes |
integer | yes | |
estimatedFullSeconds |
integer | yes | How long the allocation holds at that rate; 0 = unknown. |
freeInAllocationBytes |
integer | yes | |
locations |
StorageLocation[] | yes | |
path |
string | yes | Current recordings directory. |
recordedBytes |
integer | yes | |
recordingCameras |
integer | yes | |
recordingRateBps |
integer | yes | Bytes per second written by continuously recording cameras. |
sharedClipBytes |
integer | yes | Exported clips kept by live share links. |
sharedClipLinks |
integer | yes | |
totalAllocatedBytes |
integer | yes | |
totalFreeInAllocationBytes |
integer | yes | |
totalUsedBytes |
integer | yes | |
usedBytes |
integer | yes |
StorageCamera
Section titled “StorageCamera”| Field | Type | Required | Description |
|---|---|---|---|
bytes |
integer | yes | |
cameraId |
string | yes | |
count |
integer | yes | |
name |
string | yes | |
newestTs |
integer | yes | Unix ms. |
oldestTs |
integer | yes | Unix ms. |
StorageLocation
Section titled “StorageLocation”| Field | Type | Required | Description |
|---|---|---|---|
allocationBytes |
integer | yes | |
cameraCount |
integer | yes | |
cameras |
LocationCamera[] | yes | |
config |
object | yes | Type-specific settings (path, host, share, …); never a credential. |
createdAt |
integer | no | Configured locations only. |
diskFreeBytes |
integer | no | |
diskTotalBytes |
integer | no | When the destination reports its capacity. |
enabled |
boolean | yes | |
etag |
string | no | Configured locations only: the If-Match value for writes to it. |
hasCredential |
boolean | yes | |
id |
string | yes | Empty for the built-in default location. |
isDefault |
boolean | yes | |
name |
string | yes | |
sortOrder |
integer | yes | |
type |
string | yes | local, smb or sftp. |
updatedAt |
integer | no | Configured locations only. |
usedBytes |
integer | yes |
StorageLocations
Section titled “StorageLocations”| Field | Type | Required | Description |
|---|---|---|---|
dataDir |
string | yes | |
locations |
StorageLocation[] | yes |
StreamToken
Section titled “StreamToken”| Field | Type | Required | Description |
|---|---|---|---|
expiresIn |
integer | yes | Seconds the token stays valid for opening a socket. |
hasSub |
boolean | yes | A low-quality sub stream exists (append &q=sub to wsUrl). |
token |
string | yes | |
wsUrl |
string | yes | Server-relative WebSocket path carrying the token (/api/v1/cameras/{id}/ws?token=…). |
SunTimes
Section titled “SunTimes”| Field | Type | Required | Description |
|---|---|---|---|
alwaysDown |
boolean | yes | |
alwaysUp |
boolean | yes | |
dawn |
integer | yes | |
dusk |
integer | yes | |
goldenHour |
integer | yes | |
goldenHourEnd |
integer | yes | |
nadir |
integer | yes | |
nauticalDawn |
integer | yes | |
nauticalDusk |
integer | yes | |
night |
integer | yes | |
nightEnd |
integer | yes | |
solarNoon |
integer | yes | |
sunrise |
integer | yes | |
sunriseEnd |
integer | yes | |
sunset |
integer | yes | |
sunsetStart |
integer | yes |
SystemStatus
Section titled “SystemStatus”| Field | Type | Required | Description |
|---|---|---|---|
cameras |
StatusCamera[] | yes | |
go2rtc |
StatusGo2RTC | yes | |
hardwareEncoder |
StatusHWEncoder | no | |
homeAssistant |
StatusHA | yes | |
liveDownCount |
integer | yes | |
recDownCount |
integer | yes | |
storage |
StatusStorage | yes | |
uptimeSec |
integer | yes | |
version |
string | yes | |
weather |
WeatherStatus | yes |
TrackPoint
Section titled “TrackPoint”| Field | Type | Required | Description |
|---|---|---|---|
confidence |
number | yes | |
eventId |
string | yes | |
h |
number | yes | |
label |
string | yes | |
obj |
integer | yes | |
ts |
integer | yes | |
w |
number | yes | |
x |
number | yes | |
y |
number | yes |
TwoFactorChallenge
Section titled “TwoFactorChallenge”| Field | Type | Required | Description |
|---|---|---|---|
token |
string | yes | Pass to POST /auth/login/2fa with the code; valid for a few minutes. |
twoFactorRequired |
boolean | yes | Always true. |
| Field | Type | Required | Description |
|---|---|---|---|
pressure |
string | yes | |
temp |
string | yes | |
wind |
string | yes |
UnitsRequest
Section titled “UnitsRequest”| Field | Type | Required | Description |
|---|---|---|---|
pressure |
string | no | |
temp |
string | no | |
wind |
string | no |
UpdateChannelReq
Section titled “UpdateChannelReq”| Field | Type | Required | Description |
|---|---|---|---|
enabled |
boolean | no | Absent = unchanged. |
name |
string | no | Empty or absent = unchanged. |
| Field | Type | Required | Description |
|---|---|---|---|
email |
string | yes | |
id |
string | yes | |
mustChangePassword |
boolean | yes | |
name |
string | yes | |
passkeys |
integer | yes | Number of registered passkeys. |
preferences |
object | yes | The user’s UI preferences (free-form JSON object, PUT /users/me/preferences). |
role |
string | yes | admin or viewer. |
twoFactor |
boolean | yes | TOTP two-factor sign-in is on. |
UserListItem
Section titled “UserListItem”| Field | Type | Required | Description |
|---|---|---|---|
cameraIds |
string[] | yes | Cameras a viewer may see. |
disabled |
boolean | yes | |
email |
string | yes | |
etag |
string | yes | The If-Match value for writes to this user. |
id |
string | yes | |
name |
string | yes | |
role |
string | yes | admin or viewer. |
UserReq
Section titled “UserReq”| Field | Type | Required | Description |
|---|---|---|---|
cameraIds |
string[] | no | The cameras a viewer may see. PUT: replaces the list (absent = unchanged); every id must name a camera. |
disabled |
boolean | no | PUT only; absent = unchanged. |
email |
string | no | POST: required. PUT: ignored (an account’s email cannot be changed). |
name |
string | no | PUT: empty or absent = unchanged. |
password |
string | no | POST: the temporary password (at least 8 characters; generated when absent). PUT: a new password, 8..72 bytes. |
role |
string | no | admin or viewer. POST: anything else = viewer; PUT: anything else = unchanged. |
WeatherConfig
Section titled “WeatherConfig”| Field | Type | Required | Description |
|---|---|---|---|
current |
yes | Null until the poller has fetched a sample since the server started. | |
enabled |
boolean | yes | |
intervalMin |
integer | yes | |
source |
string | yes | |
status |
WeatherStatus | yes |
WeatherNow
Section titled “WeatherNow”| Field | Type | Required | Description |
|---|---|---|---|
configured |
boolean | yes | |
connected |
boolean | yes | |
lastUpdated |
integer | yes | |
sample |
yes | ||
source |
string | yes |
WeatherRange
Section titled “WeatherRange”| Field | Type | Required | Description |
|---|---|---|---|
samples |
WeatherSample[] | yes |
WeatherSample
Section titled “WeatherSample”| Field | Type | Required | Description |
|---|---|---|---|
cloudPct |
number | no | |
conditionCode |
integer | no | |
dewpointC |
number | no | |
feelsLikeC |
number | no | |
humidityPct |
number | no | |
precipMm |
number | no | |
precipProbPct |
number | no | |
pressureHpa |
number | no | |
source |
string | no | |
tempC |
number | no | |
ts |
integer | yes | |
uvIndex |
number | no | |
visibilityM |
number | no | |
windDirDeg |
number | no | |
windGustMs |
number | no | |
windSpeedMs |
number | no |
WeatherStatus
Section titled “WeatherStatus”| Field | Type | Required | Description |
|---|---|---|---|
configured |
boolean | yes | A site location is set. |
connected |
boolean | yes | The last fetch succeeded. |
enabled |
boolean | yes | |
lastError |
string | no | |
lastUpdated |
integer | yes | |
source |
string | yes |
WebAuthnCred
Section titled “WebAuthnCred”| Field | Type | Required | Description |
|---|---|---|---|
createdAt |
integer | yes | |
id |
string | yes | |
lastUsed |
integer | yes | |
name |
string | yes |
Webhook
Section titled “Webhook”| Field | Type | Required | Description |
|---|---|---|---|
createdAt |
integer | yes | |
enabled |
boolean | yes | |
events |
string[] | yes | |
id |
string | yes | |
name |
string | yes | |
secret |
string | no | |
url |
string | yes |
WebhookDelivery
Section titled “WebhookDelivery”| Field | Type | Required | Description |
|---|---|---|---|
code |
integer | yes | |
detail |
string | no | |
event |
string | yes | |
id |
string | yes | |
status |
string | yes | |
ts |
integer | yes | |
webhookId |
string | yes |
WebhookListItem
Section titled “WebhookListItem”| Field | Type | Required | Description |
|---|---|---|---|
createdAt |
integer | yes | |
enabled |
boolean | yes | |
etag |
string | yes | The If-Match value for writes to this webhook. |
events |
string[] | yes | |
id |
string | yes | |
name |
string | yes | |
secret |
string | no | HMAC signing key of the deliveries. |
url |
string | yes |
WebhookRequest
Section titled “WebhookRequest”| Field | Type | Required | Description |
|---|---|---|---|
createdAt |
integer | no | |
enabled |
boolean | no | |
events |
string[] | no | |
id |
string | no | |
name |
string | no | |
secret |
string | no | |
url |
string | no |
Related: The API and tokens, Token scopes, Security model and hardening.