Official Protect API released in 5.3

[shaunco]

Unifi Protect 5.3 added an official (with documentation!) Protect API:

I can't seem to find the documentation online, but in the Protect management console, click the gear icon, then Control Plane, and go to the Integrations tab. From there, there is a link to documentation:

That link is hosted somewhere on your controller/NVR, but is quite nice:

[bdraco]

That's great, once it reaches feature parity with the undocumented API we can switch over to it

[shaunco]

What appears to be missing? I didn't catch anything missing on my, admittedly quick, scan of the unofficial and official APIs.

[jasperslits]

I gave it a try earlier today and some observations below:

Bootstrap

https://{host}/proxy/protect/api/bootstrap doesn't support X-API-KEY header for authentication and still requires the cookie. This makes sense as the bootstrap endpoint is not part of the official documentation.
So there's definitely more work than changing the authentication mechanisms as this seems a fundamental piece.

Ring settings for Chimes

The documentation states that the volume attribute should be returned for a chime and the onofficial API returns the correct value of 80, but the official one (https://{host}/proxy/protect/integration/v1/chimes/65c4d8d6034c4b03e40004fa) returns an empty array for ringSettings.

{
    "id": "65c4d8d6034c4b03e40004fa",
    "modelKey": "chime",
    "state": "CONNECTED",
    "name": "Chime hall",
    "cameraIds": [
        "61684e1203053d038700077c"
    ],
    "ringSettings": []
}

Privacy zones

Another thing is that fields like privacy zones are not returned in the official API so actions like unifiprotect.remove_privacy_zone won't work. I assume that's not a commonly used action but it's a breaking change nonethless.

Snapshots

Making a snapshot is supported via v1/cameras/{id}/snapshot official API endpoint but it doesn't support the timestamp so this is another breaking change.

There are for sure more differences between the official and unofficial one that make switching over complex.

[RaHehl]

I’m also using this here as a notebook:

Authorization:

I’m generally in favor of the API key approach, but it would be desirable to be able to restrict its permissions—e.g., to read-only or live-only. In principle, I think that for the migration it would be good if, for a certain period of time, we could either access the public API using the API key or, even better, use our existing credentials to access the public API. I don’t currently have time for an all-at-once migration; I can only work incrementally. It would be great if we could turn a user/pass into an API Key so we can seemlessly migrate folks

If you call the public API in the browser using private-API authentication, you get:

{
  "error": "Failed to authenticate request using 'apiKey'",
  "name": "UNAUTHENTICATED",
  "type": "apiKey"
}

And if I call the private API with the API key, I get a 500 error and find these in the protect api log:

2025-05-17T19:06:58.177Z - error: 500 GET /api/bootstrap Cannot read properties of undefined (reading 'pk') 
TypeError: Cannot read properties of undefined (reading 'pk')
    at e.exports.call (/usr/share/unifi-protect/app/webpack:/unifi-protect/src/middleware/api/rest/routes/bootstrap.ts:132:35)
    at _next (/usr/share/unifi-protect/app/webpack:/unifi-protect/src/middleware/api/Router.js:107:35)
    at e.exports.handle (/usr/share/unifi-protect/app/webpack:/unifi-protect/src/middleware/api/Router.js:114:12)
    at _next (/usr/share/unifi-protect/app/webpack:/unifi-protect/src/middleware/api/rest/RestRouter.js:122:13)
    at e.exports.handle (/usr/share/unifi-protect/app/webpack:/unifi-protect/src/middleware/api/rest/RestRouter.js:143:12)
    at Layer.handle [as handle_request] (/usr/share/unifi-protect/app/node_modules/express/lib/router/layer.js:95:5)
    at trim_prefix (/usr/share/unifi-protect/app/node_modules/express/lib/router/index.js:328:13)
    at /usr/share/unifi-protect/app/node_modules/express/lib/router/index.js:286:9
    at Function.process_params (/usr/share/unifi-protect/app/node_modules/express/lib/router/index.js:346:12)
    at next (/usr/share/unifi-protect/app/node_modules/express/lib/router/index.js:280:10)
    at initialize (/usr/share/unifi-protect/app/node_modules/passport/lib/middleware/initialize.js:98:5)
    at Layer.handle [as handle_request] (/usr/share/unifi-protect/app/node_modules/express/lib/router/layer.js:95:5)
    at trim_prefix (/usr/share/unifi-protect/app/node_modules/express/lib/router/index.js:328:13)
    at /usr/share/unifi-protect/app/node_modules/express/lib/router/index.js:286:9
    at Function.process_params (/usr/share/unifi-protect/app/node_modules/express/lib/router/index.js:346:12)
    at next (/usr/share/unifi-protect/app/node_modules/express/lib/router/index.js:280:10)

NFC and Fingerprint:

The feature flags are apparently filtered here for comparison:

G4 Doorbell Pro Poe (with AI Port)

Public Api:

"featureFlags": {
      "supportFullHdSnapshot": true,
      "hasHdr": true,
      "smartDetectTypes": [
        "person",
        "vehicle",
        "animal",
        "face",
        "licensePlate",
        "package"
      ],
      "smartDetectAudioTypes": [],
      "videoModes": [
        "default",
        "homekit",
        "sport",
        "slowShutter"
      ],
      "hasMic": true,
      "hasLedStatus": true,
      "hasSpeaker": true
    },

Private Api:

"featureFlags": {
        "canAdjustIrLedLevel": false,
        "maxScaleDownLevel": 0,
        "canMagicZoom": false,
        "canOpticalZoom": false,
        "canTouchFocus": false,
        "hasAccelerometer": false,
        "hasVerticalFlip": true,
        "hasAec": true,
        "hasBluetooth": false,
        "hasChime": false,
        "hasExternalIr": false,
        "hasIcrSensitivity": true,
        "hasInfrared": true,
        "hasLdc": true,
        "hasLedIr": true,
        "hasLedStatus": true,
        "hasLineIn": false,
        "hasMic": true,
        "hasPrivacyMask": true,
        "hasRtc": false,
        "hasSdCard": false,
        "hasSpeaker": true,
        "hasWifi": false,
        "hasHdr": true,
        "hasAutoICROnly": true,
        "videoModes": [
          "default",
          "homekit",
          "sport",
          "slowShutter"
        ],
        "videoModeMaxFps": [30, 24, 30, 20],
        "hasMotionZones": true,
        "hasLcdScreen": true,
        "hasFingerprintSensor": true,
        "mountPositions": [],
        "smartDetectTypes": [
          "person",
          "vehicle",
          "animal",
          "face",
          "licensePlate",
          "package"
        ],
        "smartDetectAudioTypes": [],
        "supportDoorAccessConfig": true,
        "supportNfc": true,
        "supportLpDetectionWithoutVehicle": false,
        "supportCustomRingtone": true,
        "lensType": null,
        "lensModel": null,
        "motionAlgorithms": [
          "enhanced"
        ],
        "hasSquareEventThumbnail": true,
        "hasPackageCamera": true,
        "audio": [],
        "audioCodecs": [
          "aac",
          "opus"
        ],
        "videoCodecs": [
          "h264",
          "h265",
          "mjpg"
        ],
        "audioStyle": [],
        "isDoorbell": true,
        "isPtz": false,
        "hasColorLcdScreen": true,
        "hasLiveviewTracking": true,
        "hasLineCrossing": true,
        "hasLineCrossingCounting": true,
        "hasFlash": false,
        "flashRange": null,
        "hasLuxCheck": true,
        "presetTour": false,
        "hasEdgeRecording": false,
        "hasLprReflex": false,
        "hasSmokeCover": false,
        "streamEncryptable": true,
        "hasManualPersonOfInterest": false,
        "hasHallwayMode": false,
        "supportFullHdSnapshot": true,
        "privacyMaskCapability": {
          "maxMasks": 16,
          "rectangleOnly": false
        },

Even though I fundamentally have no problem with the filtering, it does raise questions about how quickly we’ll get access to new features in the future.

And specifically, under this heading, flags like hasFingerprintSensor, supportNfc, and isDoorbell are missing.

Access to keyrings is also absent, although I could personally do without keyrings if the API would return the matching user UUID on a scan event and, for NFC, additionally the NFC ID (so that Protect can handle unknown cards). You’d still need at least a user resource to map that back to a name.

Bootstrap:

The missing fields drastically increase the number of API calls depending on the size of your setup—especially since, for example, the RTSP URLs are omitted in GET https://YOUR_CONSOLE_IP/proxy/protect/integration/v1/cameras meaning you then have to retrieve them one camera at a time via GET https://YOUR_CONSOLE_IP/proxy/protect/integration/v1/cameras/{id}/rtsps-stream Additionally, the AI Port resource is completely absent—even though, admittedly, there are currently not many meaningful use cases for it

I can't comment on the AI key or UI super link because i don’t have the hardware.

Additionally, the AI Port resource is completely absent—even though, admittedly, there are currently not many meaningful use cases for it.

Event Delivery & WebSocket Mismatch:

The big issues for users have always been the speed at which smart detect, motion, and license plate events are delivered. I think the license plate events delivered over the WebSocket API still don’t match what’s shown in the UI. It seems like the server sends a message when the model initially detects a plate but never updates it after finishing processing to get the final value, so there’s a significant mismatch between the data coming down the WebSocket pipe and what the user sees in the UI.

[RaHehl]

#482 addresses the topic of authorization and allows us to automatically generate an API key for the current user. In my opinion, this is suitable as an intermediate step and for the migration. The biggest open issue is that Bootstrap is apparently not present in the new API, which, if it stays that way, means a lot more API requests and major rebuilds. From an architectural point of view, I would welcome it if something similar were provided in the public API. The API key should then be cached and, to avoid generating garbage, only be created once per user.

[RaHehl]

WebSocket:

I took a look at the topic of WebSocket for events via the public API to check whether the events for face detection contain all the necessary information.

Using an Insomnia client, I connected a WebSocket to:
https://YOUR_CONSOLE_IP/proxy/protect/integration/v1/subscribe/events

However, in its current state, we can't really make use of it. This was the first message I received:

{"item":{"id":"683842c603464203e43d1868","modelKey":"event","type":"smartDetectZone","start":1748517571853,"device":"****","smartDetectTypes":["face"]},"type":"add"}

And then there was a second one:

{"item":{"id":"683842c603464203e43d1868","modelKey":"event","type":"smartDetectZone","start":1748517571853,"end":1748517581453,"device":"****","smartDetectTypes":["face","person"]},"type":"update"}

So, the takeaway is: this doesn't really help us, as we can't determine whose face was detected through this method. I haven't tested LPR (License Plate Recognition), but I assume it's similar.

There also doesn't seem to be any other REST method or similar option to retrieve more detailed information about the event.