Review Home Camera Events with an Assistant

Building an assistant that reviews HomeKit camera events is conditional. A compatible home hub, an active iCloud+ subscription, and a HomeKit Secure Video-certified camera must all be in place before any clip data exists to review. There is no public Figment REST endpoint for HomeKit Secure Video clip metadata. What Figment provides is an account-level connection your app can verify before handing off to your native HomeKit integration on a supported app target.

What HomeKit Secure Video records

When a camera detects motion, the home hub — a HomePod mini, HomePod, or Apple TV 4K — analyzes the footage locally on-device, classifies the event, and uploads an end-to-end encrypted clip to iCloud. Analysis never leaves your home unencrypted. Each clip carries one motion label: people, animals, vehicles, packages, or unclassified motion. Compatible cameras with face recognition enabled can also include a matched person name drawn from the user's Photos library.

Clips are stored for a rolling 10 days of activity. That is the full scope your review loop has to work with. Camera footage does not count against the account's iCloud storage quota. (Apple iCloud: HomeKit Secure Video)

Prerequisites: hub, plan, and camera

All three must be active and working before any review is possible.

The hub is not optional. It performs all local analysis and encryption before anything reaches iCloud. If the hub goes offline or reboots, clips from that period are never created. Build gap reporting into your assistant from the start.

The iCloud+ tier sets the camera ceiling. If a user asks why some cameras are missing from their review, their subscription tier is the first thing to check.

What Apple's HomeKit camera APIs provide

Apple's HMCameraProfile class gives an app stream controls and snapshot controls per camera. It is available on iOS, iPadOS, Mac Catalyst, tvOS, visionOS, and watchOS — not on native macOS. An ordinary macOS daemon cannot import HomeKit and reach camera controls through HMCameraProfile; the app target must be iOS or Mac Catalyst. (Apple developer documentation — HMCameraProfile)

HomeKit Secure Video recordings are distinct from the live stream. Clips are stored end-to-end encrypted in iCloud and viewable in the Home app. Apple does not publish a public REST API for retrieving clip metadata outside the native HomeKit framework on a supported app target. Plan accordingly: Figment's Apple Connect handles the account-level connection and consent; your native iOS or Mac Catalyst code accesses the HomeKit data.

Clip selection worksheet

The following is an integration design for a developer-owned native iOS or Mac Catalyst app holding the HomeKit entitlement.

Before the session

• Confirm the hub is reachable and online.
• Confirm the user's iCloud+ tier supports all cameras they expect to see.
• Initialize HMHomeManager and verify authorizationStatus is authorized.
• Enumerate cameras; note each camera's current online or offline state.

Scoping the time window

• Ask the user (or derive from context) the period to review: last hour, since sunset, last 48 hours.
• Keep the range within 10 days. If the requested window extends beyond the storage limit, say so before continuing.

Applying filters

• Motion label: people, animals, vehicles, packages, any motion.
• For cameras with face recognition, optionally filter by matched person name.
• Activity zones the user configured already constrain what was recorded. Your assistant inherits those zones without needing to modify them.

What to surface

• Timestamp, camera name, motion type, duration, and matched person name when present.
• An explicit gap entry for any camera that was offline during the requested window.
• Leave video playback to the Home app. The assistant adds value by synthesizing the event list, not by streaming footage.

Account connection with Figment

Figment's Apple Connect provides a user-approved connection to the user's Apple account. Use the connection status endpoint to verify the account is active before starting your HomeKit session:

curl https://figment.so/api/apple-connect/v1/connections/con_... \
  -H "Authorization: Bearer ACCESS_TOKEN"

The response includes connection.services, where each service entry has a state field. Possible states include connecting, needs_approval, syncing, ready, offline, reconnect_required, and revoked. A non-2xx response or a service not in ready state means the account needs attention — direct the user to /apple-connect/account to resolve the issue. Access tokens are short-lived; refresh before the session starts, not after the first failed call.

Planning for hub and camera gaps

Hub rebooted mid-window. Clips from before the reboot exist; the gap during the reboot has no records. Query the period, get nothing, and report the gap — do not imply the camera was idle.

Camera offline while hub ran. A single camera can drop off while the rest of the system stays connected. Check per-camera status and include that in the summary.

iCloud+ tier limit reached. If the user added more cameras than their plan supports, those additional cameras do not record. This appears as missing clips, not an error.

The Home service sits in Figment's conditional cluster because hub model, hub uptime, iCloud+ tier, and camera compatibility are all outside the developer's control. A trustworthy assistant surfaces these conditions rather than hiding them.

Connect Apple Account to give your app a user-approved connection to their Apple data.

For scene and device control alongside camera review, see Give an Agent Permission to Run Home Scenes. To bring location context into the same session, see Connect Find My Devices to an Assistant and Use Shared Find My Locations in Approved Workflows. For the full access model, see OAuth for iCloud: Connect Apple Data to Your App.