/clear

GET

/v1/alarm/{alarmId}/clear

Code sample: cURL

curl --request GET \
  --url https://api.openalarm.io/v1/alarm/k7m3x9q2f8d4w1b5n6p0r3t7v2x5z9c4/clear \
  --header 'X-API-Key: oa_m9s346q3d25vt4f5v37e3s3e28jt97kb6cq643dzvmxxqkfbf5kznwj47tan9zt2'

• Production

End the open incident on this alarm.

An alarm has at most one incident open at a time. While one is open, further triggers fold into it rather than starting a new one - so clearing is what returns the alarm to normal monitoring and lets the next trigger alert again.

An incident you never clear closes on its own 24 hours after escalation ends, so a forgotten one cannot suppress the alarm indefinitely. Clearing is the immediate path.

Clearing does not change whether the alarm is armed. An alarm armed Away when it fired is still armed Away once the incident is cleared, and will alert again on the next trigger without being re-armed. Clearing says the event has been dealt with, never that the premises are unarmed - only disarm disarms.

Clearing when nothing is open is still a success, and clearing twice costs nothing - so it is safe to call defensively.

Authorizations

• ApiKeyHeader
• BearerAuth

Parameters

Path Parameters

alarmId

required

string

The alarm’s 32-character identifier. The API key gates the call; this names which alarm it acts on.

Example

k7m3x9q2f8d4w1b5n6p0r3t7v2x5z9c4

Responses

202

Accepted - the call will be applied, and nothing has been sent at the moment the response returns. Every endpoint on this API answers 202, so there is no other success code to handle.

For a trigger, contact waits out the false-alarm cancellation window (optional, set per mode) - a disarm inside it cancels the trigger before any incident opens. A repeat trigger while an incident is already open is recorded against it and still returns 202.

202 does not mean an alert went out. A trigger that folds into an open incident, is cancelled inside the false-alarm window, or lands in test mode is accepted and recorded without reaching anyone. See the Arming guide.

Check data.environment if your automation depends on being live - a test alarm looks identical from the outside otherwise.

Media typeapplication/json

The five-field envelope on every response. The 401 is the one exception - it returns only a message and no traceId.

object

error

required

The outcome. false on 202, true on 404.

boolean

message

required

Human-readable, and null on success. On 404 it is generic wording - it never indicates whether an ID exists but belongs to someone else. Text only, never a URL.

string | null

links

required

Any link that goes with the message, keyed by a registered IANA link relation name. Always present, {} when there is none. Today the one key is help: a page that explains how to fix the error. Ignore keys you do not recognise; new ones may be added.

object

help

string format: uri

traceId

required

Identifies this one call. Worth logging, and worth quoting if you report a problem. It is not a resource reference and no endpoint accepts one back.

string format: uuid

data

required

The payload. Carries environment on every 2xx, plus the location the source belongs to when it has one.

object

environment

Whether the trigger ran live or as a test. An alarm runs as a test when its own test switch is on, or when its whole location’s is - either alone is enough. On a test trigger the escalation policy still resolves and records, but nobody is alerted.

string

Allowed values: live test

location

The location this alarm or panic button belongs to. Renaming a location never changes any ID or URL.

object

id

The location’s 32-character identifier.

string

name

The location’s display name.

string

Example

{
  "error": false,
  "message": null,
  "links": {},
  "traceId": "8f14e45f-ea0d-4a1b-9f2c-6b3d70c5e881",
  "data": {
    "environment": "live",
    "location": {
      "id": "2c9wvhrq52k5refhtvmmr0f8yjz5j9e9",
      "name": "Home"
    }
  }
}

401

The API key is missing or invalid.

This is the one response that does not use the envelope. It returns only a message - no traceId, because no call was ever traced.

Media typeapplication/json

object

message

string

Example

{
  "message": "Unauthorized"
}

404

The alarm or panic button is not available to fire.

This covers four situations, and they are deliberately indistinguishable from one another:

1. The ID does not exist.
2. It belongs to another account.
3. It is in your account, but your key is not scoped to it.
4. Your key can reach it, but the trigger cannot currently fire - you disabled it.

Separating them would turn a narrowly-scoped key into a way to discover which IDs are real, so no response ever does.

A trigger that cannot fire is a 404 rather than a 202 on purpose: accepting the call and quietly doing nothing would tell you your alarm fired when it did not.

An unknown mode is the one 404 that says what is wrong. On arm/{modeId} and trigger/{modeId}, a mode other than home, away, night or vacation returns Unknown mode 'off'. Use home, away, night or vacation. with links.help pointing to the Arming guide. Modes are public, so naming the problem reveals nothing.

Media typeapplication/json

The five-field envelope on every response. The 401 is the one exception - it returns only a message and no traceId.

object

error

required

The outcome. false on 202, true on 404.

boolean

message

required

Human-readable, and null on success. On 404 it is generic wording - it never indicates whether an ID exists but belongs to someone else. Text only, never a URL.

string | null

links

required

Any link that goes with the message, keyed by a registered IANA link relation name. Always present, {} when there is none. Today the one key is help: a page that explains how to fix the error. Ignore keys you do not recognise; new ones may be added.

object

help

string format: uri

traceId

required

Identifies this one call. Worth logging, and worth quoting if you report a problem. It is not a resource reference and no endpoint accepts one back.

string format: uuid

data

required

The payload. Carries environment on every 2xx, plus the location the source belongs to when it has one.

object

environment

Whether the trigger ran live or as a test. An alarm runs as a test when its own test switch is on, or when its whole location’s is - either alone is enough. On a test trigger the escalation policy still resolves and records, but nobody is alerted.

string

Allowed values: live test

location

The location this alarm or panic button belongs to. Renaming a location never changes any ID or URL.

object

id

The location’s 32-character identifier.

string

name

The location’s display name.

string

Example

{
  "error": true,
  "message": "Alarm ID not found",
  "links": {},
  "traceId": "8f14e45f-ea0d-4a1b-9f2c-6b3d70c5e881",
  "data": {}
}