Skip to content

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.

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
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
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
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
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
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
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
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
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
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
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
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
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
Endpoint Summary Token scopes Access Parameters Request Response Errors
GET /openapi.json Signed in 401, 429
Endpoint Summary Token scopes Access Parameters Request Response Errors
GET /public/event-thumb Public 429
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
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
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
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
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
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
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
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
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
Endpoint Summary Token scopes Access Parameters Request Response Errors
GET /version API contract version (public, pre-auth) Public 200: APIVersion (application/json) 429
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
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
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.
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
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
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
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
Field Type Required Description
actions string[] yes
entries AuditEntry[] yes
Field Type Required Description
firstTamperedId integer yes Id of the first entry whose hash does not chain; 0 when intact.
intact boolean yes
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
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
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
Field Type Required Description
buckets BitrateBucket[] yes
currentBps integer yes
Field Type Required Description
bps integer yes Bits per second averaged over the minute.
ts integer yes Minute start, unix ms.
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.
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.
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
Field Type Required Description
cameraId string yes
destinations CameraDestination[] yes
Field Type Required Description
cameraIds string[] yes
createdAt integer yes
id string yes
name string yes
sortOrder integer yes
updatedAt integer yes
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
Field Type Required Description
sensor yes
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
Field Type Required Description
successor string yes
sunset string yes Retirement date; null while none is set.
surface string yes
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.
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).
Field Type Required Description
end integer yes
start integer yes
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.
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).
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.
Field Type Required Description
secret string yes The bearer secret (apt_…). Shown exactly once.
token APIToken yes
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.
Field Type Required Description
kind string yes tpu, npu, gpu or vpu.
name string yes
path string yes
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.
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.
Field Type Required Description
conditionCode integer no WMO weather code.
isNight boolean yes
precipMm number no
tempC number no
windSpeedMs number no
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
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
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.
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
Field Type Required Description
armed boolean yes
Field Type Required Description
state string yes online or offline.
Field Type Required Description
cameraId string yes The camera whose configuration, motion mask or schedule was saved; refetch it.
Field Type Required Description
domain string yes
Field Type Required Description
eventId string yes
Field Type Required Description
endTsMs integer yes
eventId string yes
Field Type Required Description
eventId string yes
eventType string yes
score number yes
Field Type Required Description
exportId string yes
progress number yes
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 ., or reset; see GET /feed.
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
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
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
Field Type Required Description
cameraId string yes
name string yes
rtsp string yes
Field Type Required Description
detected HardwareDetected yes
profile yes
Field Type Required Description
id string yes
name string yes
Field Type Required Description
id string yes
name string yes
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.
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
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
Field Type Required Description
profile HardwareProfile yes
Field Type Required Description
homekit InteropService yes
onvif InteropService yes
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
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).
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
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.
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.
Field Type Required Description
angle number yes
fraction number yes
name string yes
phase number yes
Field Type Required Description
cols integer yes
ignore integer[] yes
rows integer yes
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.
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.
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
Field Type Required Description
objects string[] yes Require one of these detected labels.
onlyPrecip boolean yes
timeOfDay string yes Empty, day or night.
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
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.
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
Field Type Required Description
enabled boolean yes
name string yes Button label for the single sign-on provider.
Field Type Required Description
codename string no
id string yes
pretty string yes
repoDist string no
supported boolean yes
version string yes
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=&name=&local=&remote=<public address, when https>&code=
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.
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.
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
Field Type Required Description
publicKey string yes VAPID application server key (base64url).
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).
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.
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.
Field Type Required Description
forgotten integer yes Trusted devices forgotten.
signedOut integer yes Sessions ended.
Field Type Required Description
objects string[] yes
onlyPrecip boolean yes
timeOfDay string yes
Field Type Required Description
objects string[] no
onlyPrecip boolean no
timeOfDay string no
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).
Field Type Required Description
sent integer yes Channels that took the test message.
Field Type Required Description
windows ScheduleWindowReq[] no Every window; an empty list clears the schedule.
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.
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.
Field Type Required Description
durationMs integer yes
endTs integer yes Unix ms.
hasMotion boolean yes
id string yes
startTs integer yes Unix ms.
Field Type Required Description
deviceClass string yes
entityId string yes
name string yes
unit string yes
updatedAt integer yes
value string yes
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.
Field Type Required Description
commit string yes
version string yes
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
Field Type Required Description
sessions Session[] yes
trustedDevices integer yes Devices that skip the two-factor code.
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
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
Field Type Required Description
needsSetup boolean yes True until the first administrator exists (POST /setup).
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
Field Type Required Description
expiresHours integer no 0 = never expires.
exportId string yes
label string no Default: “ clip”.
maxViews integer no 0 = unlimited.
password string no Optional viewer password.
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
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
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
Field Type Required Description
reachable boolean yes
streams integer yes Streams registered with go2rtc.
Field Type Required Description
connected boolean yes
enabled boolean yes
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).
Field Type Required Description
status string yes Always “ok”.
Field Type Required Description
status string yes Always “sent”.
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
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
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.
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
Field Type Required Description
dataDir string yes
locations StorageLocation[] yes
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=…).
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
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
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
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
Field Type Required Description
pressure string no
temp string no
wind string no
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.
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.
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.
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
Field Type Required Description
configured boolean yes
connected boolean yes
lastUpdated integer yes
sample yes
source string yes
Field Type Required Description
samples WeatherSample[] yes
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
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
Field Type Required Description
createdAt integer yes
id string yes
lastUsed integer yes
name string yes
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
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
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
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.