Overview

Send-only alarm ingest API for DIY smart homes.

Core API v1

The OpenAlarm core / alarm API is the send-only endpoint your smart home calls to arm, disarm, and fire alarms. OpenAlarm is a messenger, not a monitor - these calls dispatch alerts to the contacts you have chosen; they never reach professional monitoring.

:::caution[Pre-release] This API is in active design and is not yet live. The request contract below - paths, methods, authentication, and the 401 / 403 / 404 responses - is what the API is being built against. Success responses are shown as 2XX because the exact status code and response body are still being finalized; they are intentionally left undefined here rather than guessed. :::

Authentication

Every request carries an account-level API key, sent either as X-API-Key: <key> (canonical) or Authorization: Bearer <key> (equivalent - the two are OR-ed). The key is send-only: it authorizes the ingest actions below and nothing else - no reads, no configuration, no account access. It opens the gate; it does not own data. See the Authentication guide.

GET or POST, bodyless

Every endpoint accepts GET or POST - the two are equivalent, and requests are bodyless (the URL is the whole call). Use GET for webhook sources that can only issue a GET (UniFi Protect, simple webhooks); use POST where your client supports it. Because the API key travels in a header - never in the URL - a scanned or prefetched URL cannot fire an alarm on its own.

Modes and defaults

Each alarm has three predefined modes - Home, Away, Night (plus Off, reached via disarm). Arming and triggering come as matched pairs, and two bare shortcuts keep the common paths trivial:

• arm with no mode defaults to Away (the most conservative posture) and stores the mode.
• trigger with no mode fires the alarm’s stored mode policy, falling back to Away if no mode was ever armed. A trigger is always fireable and never depends on prior state.

Information

• OpenAPI version: 3.1.0

Operations

POST

/v1/{alarmId}/arm

POST

/v1/{alarmId}/arm/{mode}

POST

/v1/{alarmId}/disarm

POST

/v1/{alarmId}/panic/{panicId}

POST

/v1/{alarmId}/trigger

POST

/v1/{alarmId}/trigger/{mode}

Authentication

ApiKeyHeader

The account-level API key. The canonical form.

Security scheme type: apiKey

Header parameter name: X-API-Key

BearerAuth

The same account-level API key, sent as a bearer token. Equivalent to X-API-Key.

Security scheme type: http