Provisioning API

The provisioning API at /api/v1 sets Huntress up from code: create a place with its sensors, enrol people, register alarm panels, and read back the tokens each device needs. It is built to be run again and again; nothing it does is destructive.

API keys#

1. An Owner or Admin opens My account → API keys and creates a key: a name, a scope and an optional expiry.
2. Copy the key at once. It is shown once; Huntress stores only its SHA-256 hash.
3. Send it in every request: Authorization: Bearer hnt_….

• A key looks like hnt_<8-character id>_<43-character secret>. Only the id is ever shown or logged afterwards.
• Scopes: sites:read lists and reads; sites:write also creates (it implies read). The same two scopes cover places, people and panels.
• A key works only while the member who created it is still an Owner or Admin. If they are demoted or removed, their keys are suspended or revoked at once.
• An organisation can have 20 active keys. You can revoke a key at any time; the list shows each key's status, last use and the address it was last used from.
• HTTPS is required (ApiKeys:RequireHttps, default on outside development). Behind a proxy, ForwardedHeaders must restore the original scheme.
• Limits: 120 requests per minute per key, and 20 failed authentications per 5 minutes per client address, after which that client is refused for the rest of the window.
• Keys never authenticate through cookies, and a signed-in browser session never authenticates the API.

Endpoints#

How “ensure” behaves#

• Idempotent. The call matches by name. What exists is left as it is, what is missing is created, and the answer lists everything with a created flag, so the same script can run on every deployment.
• Additive. It never changes a setting, never deletes and never takes over a panel's encryption key. A place only gains missing sensors; a panel only gains missing zones.
• All or nothing. If anything conflicts, for example a sensor with that name but another type, or an account code that belongs to another organisation, the answer is 409 with the reasons and nothing is written.
• Validated. Bad input answers 400 with a list of the offending fields. A body over 256 KB answers 413.
• Limits per request: 200 sensors, 200 people, 50 panels and 200 zones per panel (zone numbers up to 65535). Names are up to 100 characters, descriptions up to 500.

A place with sensors#

`type` is the numeric id of the sensor type; see the table below

curl -X POST https://<host>/api/v1/sites/ensure \
  -H "Authorization: Bearer hnt_…" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Warehouse North",
        "description": "Main warehouse",
        "sensors": [
          { "name": "Dock door",  "type": 14 },
          { "name": "Freezer 1",  "type": 72 },
          { "name": "Gate camera", "type": 104 }
        ]
      }'

{
  "id": 7, "name": "Warehouse North", "created": true,
  "sensors": [
    { "id": 31, "name": "Dock door", "type": 14, "typeName": "Door Magnetic Contact", "unit": "", "status": "Unknown",
      "lastSeen": "2026-10-12T09:00:00Z", "token": "6f1c2a3e-…", "created": true },
    …
  ]
}

People#

curl -X POST https://<host>/api/v1/people/ensure -H "Authorization: Bearer hnt_…" \
  -H "Content-Type: application/json" \
  -d '{ "people": [ { "name": "Anna Berg", "pulseEnabled": true } ] }'

Each person is created with a Pulse tracker, and the answer holds its token: the key to give the person's phone. Pulse is off unless the request sets pulseEnabled to true; while it is off the token refuses every event, and for someone who already exists it is switched on from their page, never through the API.

Alarm panels#

curl -X POST https://<host>/api/v1/panels/ensure -H "Authorization: Bearer hnt_…" \
  -H "Content-Type: application/json" \
  -d '{ "panels": [ { "name": "Main panel", "siteName": "Warehouse North",
        "zones": [ { "number": 1, "name": "Dock door" }, { "number": 2, "name": "Office PIR" } ] } ] }'

The panel is created in a place that already exists (named by siteName). If you give no accountCode Huntress generates a random 8-character one and returns it. An account code is unique across all organisations, so a code that is taken is a 409.

Sensor type ids#

type in an ensure request is the numeric id of a sensor type. Every selectable type is accepted, as are Temperature, Humidity and Air Quality (marked API only), which are hidden from the interface's pickers. The Pulse tracker is created through people, not here.

The Hunt API and the provisioning API#

They are separate on purpose. A device holds a token that lets it report as one sensor; a script holds an API key that lets it manage the setup. Neither can do the other's job. Interactive API documentation (Swagger) is served only in development builds; this page is the reference for production. Signed in, My account → Provisioning API has the same reference with your own server's address in every example, in curl, PowerShell and Python.