BUZZER API / REST REFERENCE

Every endpoint.
Every field.

Implementation reference

This documents the connector implementation at backend commit a85cadaf34b9. The backend release and live-provider verification are still pending. The website being live does not make these routes available. Use your configured backend origin; api.buzzerapi.com remains planned.

Coverage: 32 public /v1 operations. This excludes Lowkey app-internal routes and the website's private session bridge. Download the OpenAPI 3.1 contract for agents and tools, or start with the workflow guide and CLI reference. Schemas preserve the API's actual casing, including apiKey, requestId, and webhook timestamps.

HTTP, authentication, and limits

Send Authorization: Bearer YOUR_API_KEY and Content-Type: application/json for bodies. Never send a key as a query parameter. Use a server-side client or the CLI; the backend is not configured for arbitrary browser origins. The website uses its own server-side session bridge. JSON requests use the server's default 100 KB body limit; do not send files or card details.

Responses use X-Request-ID and normally Cache-Control: no-store; public plans explicitly allow caching. Selected-building endpoints return X-Buzzer-Building-Id. Treat identifiers as opaque, timestamps as ISO 8601 unless explicitly Unix seconds, and money as minor currency units.

Rate-limit bucket	Current implementation
Public plans and identity-authenticated API operations	100 requests per 15 minutes, keyed by API key or IP for anonymous calls. The limiter runs before subscription lookup on these routes, so do not assume a higher plan increases this allowance.
Webhook routes	Subscription lookup precedes the limiter: Lite 100, Standard 500, Premium 2,000, Business/Multi Building 5,000 per 15 minutes. The authenticated routes share the same limiter bucket for a key; this is not an independent allowance per endpoint.
All `/v1/auth/*` routes	30 requests per 15 minutes per IP, including key management. `/auth/otp` additionally allows 5 per 15 minutes per IP; at most 3 unexpired challenges per email. Each challenge lasts 15 minutes and permits at most 5 verification attempts.

Honor rate-limit headers and Retry-After when present. The per-email challenge limit does not currently attach Retry-After; wait for existing challenges to expire. Limits are enforced by the current process and are not a guaranteed distributed quota. Back off with jitter after 429; inspect mutation state before repeating anything with side effects.

Account/setup/access/log reads and access revocation remain available with a valid key after subscription expiry. All webhook operations require an active subscription, including list and delete. Linked-building writes require Multi Building. The exact-body {"active":false} access update bypasses grant plan checks for the primary building; linked-building PATCH still requires Multi Building, so use DELETE for downgrade cleanup.

REST examples

Set BUZZER_BASE_URL to the backend service origin, without /v1. These examples assume authentication and physical building setup are complete. Read onboarding for email authentication and hosted payment.

# Create a one-use, four-digit visitor code. Save the returned grant ID.
curl -sS "$BUZZER_BASE_URL/v1/unlock" \
  -H "Authorization: Bearer $BUZZER_API_KEY" \
  -H "X-Buzzer-Building-Id: $BUILDING_ID" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: delivery-example-001' \
  --data '{"type":"passcode","label":"Delivery","max_uses":1,"expires_in_minutes":60}'

# Read the current grant and ETag before an update.
curl -i "$BUZZER_BASE_URL/v1/unlock/$UNLOCK_ID" \
  -H "Authorization: Bearer $BUZZER_API_KEY" \
  -H "X-Buzzer-Building-Id: $BUILDING_ID"

# Replace "3" with the exact quoted ETag from that GET.
curl -sS -X PATCH "$BUZZER_BASE_URL/v1/unlock/$UNLOCK_ID" \
  -H "Authorization: Bearer $BUZZER_API_KEY" \
  -H "X-Buzzer-Building-Id: $BUILDING_ID" \
  -H 'Content-Type: application/json' -H 'If-Match: "3"' \
  --data '{"active":false}'

# REST requires events even though the CLI supplies a default.
curl -sS "$BUZZER_BASE_URL/v1/webhooks" \
  -H "Authorization: Bearer $BUZZER_API_KEY" \
  -H "X-Buzzer-Building-Id: $BUILDING_ID" \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://agent.example/buzzer","events":["unlock.completed"]}'

# Fetch an activity page; repeat with the returned pagination.cursor.
curl -sS -G "$BUZZER_BASE_URL/v1/logs" \
  -H "Authorization: Bearer $BUZZER_API_KEY" \
  -H "X-Buzzer-Building-Id: $BUILDING_ID" \
  --data-urlencode 'since=2026-09-19T00:00:00Z' --data-urlencode 'limit=100'
# Add --data-urlencode "cursor=$CURSOR" for subsequent pages.

Creation returns a grant like this (illustrative values, optional fields omitted):

{
  "building_id": "507f1f77bcf86cd799439011",
  "id": "507f1f77bcf86cd799439012",
  "type": "passcode", "label": "Delivery", "active": true,
  "version": 0, "status": "active", "request_id": "delivery-example-001",
  "created_at": "2026-09-19T12:00:00Z", "expires_at": "2026-09-19T13:00:00Z",
  "code": "0427", "max_uses": 1, "remaining_uses": 1, "voice_enabled": false
}

To page safely, retain the same building and filters while pagination.has_more is true. Unlock lists use an ID cursor; logs use an opaque encoded cursor. For ongoing activity recovery, persist a timestamp checkpoint, overlap the next polling window, and deduplicate by log ID. The CLI's logs --follow is polling, not a separate streaming REST endpoint.

Callback payloads and signature verification

Subscribe separately for each building. Production destinations must use HTTPS and resolve to a supported public IPv4 address; private networks, URL credentials, IPv6-only endpoints, and redirect-based receivers are unsupported. Registrations are capped at five per building, including inactive ones. Secret rotation requires creating a replacement registration and deliberately removing the old one.

Event	Actual payload and meaning
`unlock.completed`	`data`: `routine_id`, `unlock_id`, `activity_id`, `occurred_at`, `name`, numeric `unlock_type` (1 timer, 2 passcode, 3 routine). Emitted when Lowkey accepted a rule and prepared the release tone. No passcode in this event. This does not prove the door opened or anyone entered.
`unlock.revoked`	`data`: `routine_id`, `name`, `reason:"uses_exhausted"`. Emitted when a use-limited passcode is exhausted. It does not include unlock_id/activity_id; use routine_id. Manual API deletion does not currently emit this event.
`access.denied`	`data.attempted_passcode` may contain attempted digits or recognized speech. Treat this as sensitive. This callback does not supply a correlated activity ID.
`unlock.created`, `unlock.expired`	Accepted subscription values but currently not emitted. Do not depend on them for lifecycle tracking; read grant state.
`webhook.test`	`data.message` only; no created_at in the test envelope. Sent by the test endpoint even for an inactive registration. Cannot be selected in events. Never use it to trigger entry actions.

{
  "event": "unlock.completed",
  "eventId": "29b4a1b5-69b0-4e40-b9d7-4850a6fcf521",
  "building_id": "507f1f77bcf86cd799439011",
  "created_at": "2026-09-19T12:05:00Z",
  "data": {
    "routine_id": "507f1f77bcf86cd799439012",
    "unlock_id": "507f1f77bcf86cd799439012",
    "activity_id": "507f1f77bcf86cd799439013",
    "occurred_at": "2026-09-19T12:05:00Z",
    "name": "Delivery", "unlock_type": 2
  }
}

Every callback is JSON POST with X-Buzzer-Event, X-Buzzer-Delivery-Id (same as eventId), and X-Buzzer-Signature: t=UNIX_SECONDS,v1=HEX_DIGEST. Verify HMAC-SHA256 over timestamp + "." + raw body bytes using the returned secret as a string. Do not hex-decode the secret or reserialize parsed JSON.

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody must be the untouched Buffer, captured before JSON parsing.
export function verifyBuzzerSignature(rawBody, header, secret, now = Date.now()) {
  if (!Buffer.isBuffer(rawBody) || typeof header !== 'string') return false;
  const match = /^t=([0-9]+),v1=([a-f0-9]{64})$/.exec(header);
  if (!match) return false;
  const [, timestamp, digest] = match;
  if (Math.abs(Math.floor(now / 1000) - Number(timestamp)) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(timestamp + '.').update(rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(digest, 'hex'));
}

After verification, parse the event, deduplicate by eventId, durably queue processing, and return 2xx promptly. The five-minute tolerance above is a receiver recommendation. Callbacks time out after 10 seconds; network failures, 429, and 5xx retry up to three total attempts, with approximately 5–7.5 and 30–45 seconds between attempts. Other HTTP errors are not retried, and redirects are not followed. Retry signatures use a fresh timestamp but retain the event ID and body.

Ten consecutive failed attempts auto-disable a registration; success resets the counter. Inspect the list, fix delivery, then PATCH active=true. Test deliveries make one attempt and return success, optional statusCode/errorMessage, and latencyMs; HTTP 200 alone does not mean the callback succeeded. Test attempts do not reset failure counters. Delivery is best effort with in-process retries; there is no durable delivery queue, public delivery-history endpoint, or replay API. Recover missed use events through logs; not all callback events have a log equivalent.

Errors and recovery

{
  "error": {
    "type": "invalid_request_error",
    "message": "Access changed since it was read...",
    "code": "VERSION_CONFLICT", "retryable": false,
    "next_action": "buzzer unlock get <id>"
  },
  "requestId": "req_example"
}

Preserve requestId for support. retryable is true for 429 and 5xx; it is not permission to duplicate a mutation. Retry access creation, checkout, and building execution with the original idempotency key and identical body. Access updates use If-Match; after a timeout reread the grant. For webhook creation, inspect registrations before retrying. Building reconciliation requires support instead of another mutation.

HTTP / codes	Recovery
400: `INVALID_JSON`, `INVALID_EMAIL`, `INVALID_KEY_OPTIONS`, `INVALID_PLAN`, `INVALID_TONE`, `INVALID_ID`, `INVALID_BUILDING`, `INVALID_BUILDING_CONTEXT`, `INVALID_BUILDING_INPUT`, `INVALID_PHONE_NUMBER`, `INVALID_QUOTE`, `INVALID_UNLOCK`, `INVALID_TYPE`, `INVALID_ACTIVE`, `INVALID_LIMIT`, `INVALID_CURSOR`, `INVALID_DATE`, `IDEMPOTENCY_KEY_REQUIRED`, `MISSING_URL`, `MISSING_EVENTS`, `INVALID_EVENTS`, `INVALID_URL`, `MAX_WEBHOOKS_EXCEEDED`	Correct the named input. Follow returned messages and documented bounds. Use a returned cursor and supported HTTPS destination. Delete an unwanted webhook registration before exceeding the five-registration limit.
401: `AUTH_REQUIRED`, `INVALID_KEY`, `INVALID_OTP`	Authenticate again or request a valid delegated key. OTP challenges are single-use, expiring, and attempt-limited.
403: `INSUFFICIENT_SCOPE`, `OWNER_KEY_REQUIRED`, `PARENT_BILLING_REQUIRED`, `PARENT_BUILDING_KEY_REQUIRED`, `SUBSCRIPTION_REQUIRED`, `PLAN_UPGRADE_REQUIRED`, `MULTI_BUILDING_REQUIRED`	Use the correct owner/parent credential and scopes, or manage the subscription. Do not rotate credentials to bypass a plan requirement.
404: `NOT_FOUND`, `ACCOUNT_NOT_FOUND`, `NUMBER_NOT_FOUND`, `BUILDING_NOT_FOUND`, `CUSTOMER_NOT_FOUND`	Verify resource ownership and building selection. A number may still need provisioning. An unknown API path or unreleased service can return a non-JSON 404 instead.
409: `KEY_LIMIT`, `PLAN_UNAVAILABLE`, `SUBSCRIPTION_EXISTS`, `CHECKOUT_EXISTS`, `CHECKOUT_PENDING`, `CHECKOUT_RECONCILIATION_REQUIRED`, `BUILDING_REQUIRED`, `BUILDING_BILLING_MISMATCH`, `BUILDING_LIMIT`, `INVALID_QUOTE`, `IDEMPOTENCY_CONFLICT`, `QUOTE_EXPIRED`, `QUOTE_STALE`, `BUILDING_BUSY`, `GRANT_REVOKED`, `VERSION_CONFLICT`, `SETUP_REQUIRED`	Inspect existing state. Expired/stale unexecuted quotes need a new preview. Pending checkout needs recovery, not another purchase. Reconciliation/billing mismatch needs support. Revoke an old credential for key limits. A revoked grant requires a deliberately new grant.
428: `VERSION_REQUIRED`	GET the grant and send its quoted ETag as If-Match.
429: `AUTH_RATE_LIMIT`, `OTP_RATE_LIMIT`, `RATE_LIMIT_EXCEEDED`	Respect Retry-After where returned and reduce polling/request frequency.
500: `INTERNAL_ERROR`, `FETCH_FAILED`, `CREATE_FAILED`, `LIST_FAILED`, `UPDATE_FAILED`, `DELETE_FAILED`, `TEST_FAILED`, `SECRET_DECRYPT_FAILED`; 503: `CHECKOUT_UNAVAILABLE`	Retry reads with backoff. Reconcile mutations using their receipt/resource first. Persist requestId for support. Provider/validation failures not explicitly mapped by a route can surface as a generic 500.

Some legacy error paths and hosting/proxy failures may return text or HTML rather than this envelope. Check HTTP status and content type before parsing. Unknown fields are rejected on access, setup, key creation, checkout, and building mutation bodies; other routes may ignore them. Send only documented fields. A 202 building receipt uses the normal operation schema, not the error envelope; inspect status before treating it as success.

Every REST operation

`GET /v1/health`

Check service health

Health is public; success does not establish account readiness.

Authorization: Public; no key required.

No request body.

Responses

HTTP status	Contract
200	Success. Health
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`GET /v1/plans`

Read live public prices

Only Standard/Premium monthly/yearly are listed. Multi Building is managed in the Lowkey app. Public cache max-age=60, shared cache max-age=300.

Authorization: Public; no key required.

No request body.

Responses

HTTP status	Contract
200	Success. Plans
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`POST /v1/auth/otp`

Request email sign-in code

Expires in 15 minutes, five verification attempts, single use. At most three unexpired challenges per email. Delivery is not proof that the account already exists.

Authorization: Public; no key required.

JSON request body

OtpRequest

Responses

HTTP status	Contract
200	Success. OtpChallenge
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`POST /v1/auth/verify`

Verify email and obtain owner credential

Creates the account if needed. At most five active non-web owner credentials. Never disclose apiKey. purpose=web is for server-side website sessions; it is not a browser-storage recommendation.

Authorization: Public; no key required.

JSON request body

VerifyRequest

Responses

HTTP status	Contract
200	Success. OwnerCredential
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`DELETE /v1/auth/key`

Revoke the current credential

No extra scope required. Subsequent use fails authentication. CLI child credentials are invalidated when their parent expires or is revoked. Website account-agent keys survive website logout.

Authorization: Bearer key; no additional scope.

No request body.

Responses

HTTP status	Contract
200	Success. Revoked
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`POST /v1/auth/keys`

Create an agent credential

One delegation level; a parentKeyId credential cannot delegate again. Requested scopes must be held by the issuer. Website sessions require an active subscription and may issue only default access scopes plus optional buildings:write, with a limit of 20 active account-agent keys. Website-issued keys are independent of session expiry; CLI-delegated keys depend on their parent.

Authorization: Bearer key; keys:write.

JSON request body

KeyRequest

Responses

HTTP status	Contract
201	Created. AgentCredential
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`GET /v1/auth/keys`

List manageable agent credentials

Website sessions list account-agent keys. Other credentials list their own children plus account-agent keys. Excludes revoked keys, but can include expired ones. No secrets or pagination.

Authorization: Bearer key; keys:write.

No request body.

Responses

HTTP status	Contract
200	Success. KeyList
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`DELETE /v1/auth/keys/{id}`

Revoke a manageable agent key

Same ownership rules as list. Repeated revocation of a known managed key succeeds.

Authorization: Bearer key; keys:write.

Parameters

Parameter Contract

Parameter	Contract
`id` path · required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$

id
path · required

string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

No request body.

Responses

HTTP status	Contract
200	Success. KeyRevoked
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`GET /v1/account`

Inspect account readiness

Account-level response; building header does not select another account. Subscription active and a recorded buzz do not prove physical entry.

Authorization: Bearer key; account:read.

No request body.

Responses

HTTP status	Contract
200	Success. Account
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`GET /v1/billing/plans`

Read authenticated price catalog

Same catalog as public plans; no active subscription required.

Authorization: Bearer key; billing:write.

No request body.

Responses

HTTP status	Contract
200	Success. Plans
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`GET /v1/billing/checkout`

Recover latest checkout

Read after a timeout. complete means hosted checkout completed; recheck account.subscription.status and setup. preparing means retry original plan and request ID.

Authorization: Bearer key; billing:write.

No request body.

Responses

HTTP status	Contract
200	Success. Checkout
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`POST /v1/billing/checkout`

Start or recover hosted checkout

Parent account only. Existing subscriptions use the portal. One pending checkout: same plan reuses it, another plan conflicts until the unpaid session is expired. Same request ID with another plan conflicts. After an unresolved provider outcome older than 23 hours, reconciliation is required instead of another purchase. No card details accepted by this API.

Authorization: Bearer key; billing:write.

Parameters

Parameter	Contract
`Idempotency-Key` header · required	Stable identifier for this action. Reuse the identical body and key after a timeout.`string` pattern: ^[a-zA-Z0-9_-]{16,100}$

JSON request body

CheckoutRequest

Responses

HTTP status	Contract
200	Success. Checkout
201	Created. Checkout
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`POST /v1/billing/checkout/{id}/expire`

Expire unpaid checkout

Open sessions can be expired; already-expired sessions succeed. Completed checkout returns 409 SUBSCRIPTION_EXISTS. This does not cancel a subscription.

Authorization: Bearer key; billing:write.

Parameters

Parameter	Contract
`id` path · required	`string` Stripe checkout session ID.

No request body.

Responses

HTTP status	Contract
200	Success. CheckoutExpired
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`POST /v1/billing/portal`

Open hosted billing management

Parent account with an existing billing customer. No request body.

Authorization: Bearer key; billing:write.

No request body.

Responses

HTTP status	Contract
200	Success. Portal
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`GET /v1/setup`

Inspect selected building setup

No subscription required for inspection. A previous successful buzz is not proof of physical door release.

Authorization: Bearer key; account:read.

Parameters

Parameter Contract

X-Buzzer-Building-Id
header

Required when a parent account has linked buildings, even for its primary building. Omit only for a single-building account. Child keys cannot select siblings.string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

No request body.

Responses

HTTP status	Contract
200	Success. Setup
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`PATCH /v1/setup`

Configure selected building release tone

Must own a provisioned number. Linked-building writes require active Multi Building. The API does not program the building call box; its manager must change the destination.

Authorization: Bearer key; setup:write.

Parameters

Parameter Contract

X-Buzzer-Building-Id
header

Required when a parent account has linked buildings, even for its primary building. Omit only for a single-building account. Child keys cannot select siblings.string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

JSON request body

SetupRequest

Responses

HTTP status	Contract
200	Success. SetupUpdated
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`GET /v1/buildings`

List accessible buildings

No pagination. Ordered by creation time then ID. Parent sees primary and children; child sees only itself.

Authorization: Bearer key; account:read.

No request body.

Responses

HTTP status	Contract
200	Success. Buildings
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`POST /v1/buildings`

Execute quoted building addition

Parent account only; do not send building header. Supply the matching unexpired quote and stable request ID. Stale inventory/billing requires a fresh preview before execution. Replay returns stored operation. HTTP 202 is not completion. running: poll the operation; reconciliation_required: contact support with its ID and do not create another request. Account mutations are serialized; uncertain outcomes retain the lock.

Authorization: Bearer key; account:read + buildings:write.

Parameters

Parameter	Contract
`Idempotency-Key` header · required	Stable identifier for this action. Reuse the identical body and key after a timeout.`string` pattern: ^[a-zA-Z0-9_-]{16,100}$

JSON request body

QuoteRequest

Responses

HTTP status	Contract
200	Success. BuildingOperation
201	Created. BuildingOperation
202	Pending or uncertain: inspect status and next_action. BuildingOperation
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`POST /v1/buildings/preview`

Preview addition or removal

Parent account only; do not send building header. Requires exactly one active/trialing Multi Building subscription, matching billed quantity, maximum 20 buildings including primary. Preview purchases nothing, creates a 15-minute quote and invoice snapshot. Only US addresses supported for additions. Removal cannot target primary; review release/deletion effects.

Authorization: Bearer key; account:read + buildings:write.

JSON request body

BuildingPreview

Responses

HTTP status	Contract
201	Created. BuildingOperation
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`DELETE /v1/buildings/{id}`

Execute quoted building removal

Authorization: Bearer key; account:read + buildings:write.

Parameters

Parameter Contract

Parameter	Contract
`id` path · required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`Idempotency-Key` header · required	Stable identifier for this action. Reuse the identical body and key after a timeout.`string` pattern: ^[a-zA-Z0-9_-]{16,100}$

id
path · required

string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

Idempotency-Key
header · required

Stable identifier for this action. Reuse the identical body and key after a timeout.string

pattern: ^[a-zA-Z0-9_-]{16,100}$

JSON request body

QuoteRequest

Responses

HTTP status	Contract
200	Success. BuildingOperation
202	Pending or uncertain: inspect status and next_action. BuildingOperation
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`GET /v1/buildings/operations/{id}`

Read building operation receipt

Parent-owned operation. Recovery remains available without an active subscription. A running operation older than five minutes is reported as reconciliation_required. Quotes/receipts are not erased when the quote expires.

Authorization: Bearer key; account:read + buildings:write.

Parameters

Parameter Contract

Parameter	Contract
`id` path · required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$

id
path · required

string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

No request body.

Responses

HTTP status	Contract
200	Success. BuildingOperation
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`POST /v1/unlock`

Create an access grant

Requires active subscription and provisioned selected number. Lite: timer; Standard: timer/passcode; Premium, Business, Multi Building: all three. Linked buildings require Multi Building. New grants start enabled. A repeated idempotency key returns the current grant (including revoked state), never reopens it; a changed body conflicts.

Authorization: Bearer key; access:write.

Parameters

Parameter Contract

X-Buzzer-Building-Id
header

Required when a parent account has linked buildings, even for its primary building. Omit only for a single-building account. Child keys cannot select siblings.string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

Idempotency-Key
header · required

Stable identifier for this action. Reuse the identical body and key after a timeout.string

pattern: ^[a-zA-Z0-9_-]{16,100}$

JSON request body

UnlockCreate

Responses

HTTP status Contract

200

HTTP status	Contract
200	Success. Unlock `Location`: On new 201: relative /v1/unlock/{id}. `string` `Idempotency-Replayed`: Present on replay. `string` constant: "true"
201	Created. Unlock `Location`: On new 201: relative /v1/unlock/{id}. `string` `Idempotency-Replayed`: Present on replay. `string` constant: "true"
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

Success. Unlock

Location: On new 201: relative /v1/unlock/{id}. string

Idempotency-Replayed: Present on replay. string

constant: "true"

201

Created. Unlock

Location: On new 201: relative /v1/unlock/{id}. string

Idempotency-Replayed: Present on replay. string

constant: "true"

default Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`GET /v1/unlock`

List access grants

No active subscription required. Excludes API-revoked grants. Ordered by descending ID. active=true means timer within window, nonexpired/nonexhausted enabled passcode, or enabled routine (not necessarily inside its schedule).

Authorization: Bearer key; access:read.

Parameters

Parameter	Contract
`X-Buzzer-Building-Id` header	Required when a parent account has linked buildings, even for its primary building. Omit only for a single-building account. Child keys cannot select siblings.`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`active` query	`string` one of: true, false
`type` query	`string` one of: timer, passcode, routine
`limit` query	`integer` minimum: 1 maximum: 100 default: 50
`cursor` query	Use pagination.cursor; this endpoint uses a grant ID cursor.`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$

No request body.

Responses

HTTP status	Contract
200	Success. UnlockPage
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`GET /v1/unlock/{id}`

Read one access grant

Includes revoked grants; ownership is scoped to selected building.

Authorization: Bearer key; access:read.

Parameters

Parameter Contract

Parameter	Contract
`id` path · required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`X-Buzzer-Building-Id` header	Required when a parent account has linked buildings, even for its primary building. Omit only for a single-building account. Child keys cannot select siblings.`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$

id
path · required

string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

X-Buzzer-Building-Id
header

Required when a parent account has linked buildings, even for its primary building. Omit only for a single-building account. Child keys cannot select siblings.string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

No request body.

Responses

HTTP status Contract

200

HTTP status	Contract
200	Success. Unlock `ETag`: Supply this exact quoted value as If-Match when updating. `string` Quoted decimal version, e.g. "3".
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

Success. Unlock

ETag: Supply this exact quoted value as If-Match when updating. string

Quoted decimal version, e.g. "3".

default Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`PATCH /v1/unlock/{id}`

Update an access grant

Requires If-Match from GET. Missing/malformed version: 428 VERSION_REQUIRED; changed version: 409 VERSION_CONFLICT. Reread before retrying. Revoked grants cannot be reopened. Changing max_uses resets remaining uses. Creation plan/setup checks apply except body exactly {"active":false}; linked-building PATCH still requires active Multi Building even for deactivation. DELETE remains the downgrade cleanup path.

Authorization: Bearer key; access:write.

Parameters

Parameter Contract

Parameter	Contract
`id` path · required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`X-Buzzer-Building-Id` header	Required when a parent account has linked buildings, even for its primary building. Omit only for a single-building account. Child keys cannot select siblings.`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`If-Match` header · required	`string` pattern: ^"[0-9]+"$

id
path · required

string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

X-Buzzer-Building-Id
header

Required when a parent account has linked buildings, even for its primary building. Omit only for a single-building account. Child keys cannot select siblings.string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

If-Match
header · required

string

pattern: ^"[0-9]+"$

JSON request body

UnlockUpdate

Responses

HTTP status Contract

200

HTTP status	Contract
200	Success. Unlock `ETag`: Supply this exact quoted value as If-Match when updating. `string` Quoted decimal version, e.g. "3".
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

Success. Unlock

ETag: Supply this exact quoted value as If-Match when updating. string

Quoted decimal version, e.g. "3".

default Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`DELETE /v1/unlock/{id}`

Revoke access grant

No active subscription required. Soft revocation is repeatable; never erases create idempotency receipt. Missing grant is 404. Other grants may still allow access. No manual-revocation callback is currently dispatched.

Authorization: Bearer key; access:write.

Parameters

Parameter Contract

Parameter	Contract
`id` path · required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`X-Buzzer-Building-Id` header	Required when a parent account has linked buildings, even for its primary building. Omit only for a single-building account. Child keys cannot select siblings.`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$

id
path · required

string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

X-Buzzer-Building-Id
header

Required when a parent account has linked buildings, even for its primary building. Omit only for a single-building account. Child keys cannot select siblings.string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

No request body.

Responses

HTTP status	Contract
200	Success. UnlockRevoked
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`GET /v1/logs`

Read persisted access activity

No active subscription required. Descending created_at then ID. since/until inclusive. Follow every cursor with unchanged filters; overlap timestamp checkpoints and deduplicate by ID to recover use events. Failed entries and sensitive passcodes may be included. Older records may lack unlock_id. No server streaming endpoint.

Authorization: Bearer key; logs:read.

Parameters

Parameter	Contract
`X-Buzzer-Building-Id` header	Required when a parent account has linked buildings, even for its primary building. Omit only for a single-building account. Child keys cannot select siblings.`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`limit` query	`integer` minimum: 1 maximum: 100 default: 50
`since` query	`string` ISO 8601 timestamp. format: date-time
`until` query	`string` ISO 8601 timestamp. format: date-time
`type` query	`string` constant: "unlock"
`cursor` query	Opaque base64url cursor; do not construct or decode as part of client logic.`string`

No request body.

Responses

HTTP status	Contract
200	Success. LogPage
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`POST /v1/webhooks`

Register callback

Requires active subscription for every webhook operation, including list, delete, and test. Linked building requires Multi Building. Maximum five registrations per selected building, including inactive registrations. events is required in REST. Save the secret once. No idempotency support: after uncertain creation, inspect list before repeating; if the secret was lost, delete/recreate deliberately.

Authorization: Bearer key; webhooks:write.

Parameters

Parameter Contract

X-Buzzer-Building-Id
header

Required when a parent account has linked buildings, even for its primary building. Omit only for a single-building account. Child keys cannot select siblings.string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

JSON request body

WebhookCreate

Responses

HTTP status	Contract
201	Created. WebhookCreated
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`GET /v1/webhooks`

List callback registrations

Requires active subscription for every webhook operation, including list, delete, and test. Linked building requires Multi Building. Newest first, no pagination. Secret is never returned; optional status timestamps are omitted until set.

Authorization: Bearer key; webhooks:write.

Parameters

Parameter Contract

X-Buzzer-Building-Id
header

Required when a parent account has linked buildings, even for its primary building. Omit only for a single-building account. Child keys cannot select siblings.string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

No request body.

Responses

HTTP status	Contract
200	Success. Webhooks
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`PATCH /v1/webhooks/{id}`

Update callback registration

Requires active subscription for every webhook operation, including list, delete, and test. Linked building requires Multi Building. Returns updated fields, failure counters, last success/failure and created/updated timestamps. disabledAt/disabledReason are list-only. No signing-secret rotation endpoint; create a replacement registration.

Authorization: Bearer key; webhooks:write.

Parameters

Parameter Contract

Parameter	Contract
`id` path · required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`X-Buzzer-Building-Id` header	Required when a parent account has linked buildings, even for its primary building. Omit only for a single-building account. Child keys cannot select siblings.`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$

id
path · required

string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

X-Buzzer-Building-Id
header

Required when a parent account has linked buildings, even for its primary building. Omit only for a single-building account. Child keys cannot select siblings.string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

JSON request body

WebhookUpdate

Responses

HTTP status	Contract
200	Success. Webhook
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`DELETE /v1/webhooks/{id}`

Delete callback registration

Requires active subscription for every webhook operation, including list, delete, and test. Linked building requires Multi Building. Hard delete; repeating returns 404.

Authorization: Bearer key; webhooks:write.

Parameters

Parameter Contract

id
path · required

string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

X-Buzzer-Building-Id
header

Required when a parent account has linked buildings, even for its primary building. Omit only for a single-building account. Child keys cannot select siblings.string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

No request body.

Responses

HTTP status	Contract
200	Success. Deleted
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

`POST /v1/webhooks/{id}/test`

Send a test callback

Requires active subscription for every webhook operation, including list, delete, and test. Linked building requires Multi Building. One attempt, ten-second timeout; no automatic retries for test. Sends even to inactive registrations. HTTP 200 describes the attempt: inspect success and statusCode. Test does not create access or reset automatic failure state.

Authorization: Bearer key; webhooks:write.

Parameters

Parameter Contract

id
path · required

string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

X-Buzzer-Building-Id
header

Required when a parent account has linked buildings, even for its primary building. Omit only for a single-building account. Child keys cannot select siblings.string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

No request body.

Responses

HTTP status	Contract
200	Success. WebhookTest
default	Structured API error; see error handling and the error code catalog. Hosting/proxy failures and unknown paths can return non-JSON bodies. Error

Request and response schemas

Optional response fields can be omitted; null is documented separately. Type-specific grant fields appear only for that type; older app-created records may omit optional fields. Required means required in that schema, not that every supported request variant uses that schema.

Error

object

Field	Contract
`error` required	`object`
`error.type` required	`string` one of: permission_error, authentication_error, invalid_request_error, not_found_error, rate_limit_error, internal_error
`error.message` required	`string`
`error.code` required	`string`
`error.retryable` required	`boolean` True for 429 and 5xx; does not authorize blindly repeating mutations.
`error.next_action` required	`string`
`requestId` required	`string` Also returned as X-Request-ID.

Health

object

Field	Contract
`status` required	`string` one of: ok
`version` required	`string` Backend package version.
`uptime` required	`number` Process uptime in seconds.

Plans

object

Field	Contract
`data` required	`array` of `object`
`data[].id` required	`string` one of: standard_monthly, standard_yearly, premium_monthly, premium_yearly
`data[].available` required	`boolean`
`data[].amount` required	`integer` Minor currency units; do not hardcode prices. \| `null`
`data[].currency` required	`string`
`data[].interval` optional	`string`
`data[].interval_count` optional	`integer`
`data[].access` required	`array` of `string` one of: timer, passcode, routine

OtpRequest

object

Field Contract

email required

string

Trimmed and lowercased.

format: email
maxLength: 254

OtpChallenge

object

Field	Contract
`challenge` required	`string` One-use challenge; expires after 15 minutes.
`message` required	`string`

VerifyRequest

object

Field	Contract
`email` required	`string` format: email
`challenge` required	`string`
`otp` required	`string` Six-digit email sign-in code, not a visitor code. pattern: ^[0-9]{6}$
`purpose` optional	`string` one of: web

OwnerCredential

object

Field	Contract
`apiKey` required	`string` Secret returned once. Omit purpose for CLI owner key; purpose=web produces a 12-hour website session key.
`keyPrefix` required	`string`
`name` required	`string`

KeyRequest

object

Unknown fields rejected.

Field Contract

name optional

string

Nonblank; trimmed before storage.

maxLength: 120
default: "Delivery agent"

scopes optional

array of string

one of: account:read, access:read, access:write, logs:read, setup:write, billing:write, webhooks:write, keys:write, buildings:write

minItems: 1
default: ["account:read","access:read","access:write","logs:read","webhooks:write"]

expires_in_days optional

integer

CLI delegation is also bounded by parent expiry.

minimum: 1
maximum: 90
default: 30

AgentCredential

object

Field	Contract
`id` required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`api_key` required	`string` Returned once; store in secret settings.
`scopes` required	`array` of `string` one of: account:read, access:read, access:write, logs:read, setup:write, billing:write, webhooks:write, keys:write, buildings:write
`expires_at` required	`string` ISO 8601 timestamp. format: date-time
`message` required	`string`

KeyList

object

Field	Contract
`data` required	`array` of `object`
`data[].id` required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`data[].name` required	`string`
`data[].scopes` optional	`array` of `string` one of: account:read, access:read, access:write, logs:read, setup:write, billing:write, webhooks:write, keys:write, buildings:write
`data[].expires_at` optional	`string` ISO 8601 timestamp. format: date-time \| `null`
`data[].last_used_at` optional	`string` ISO 8601 timestamp. format: date-time \| `null`

Revoked

object

Field	Contract
`revoked` required	`boolean` constant: true

KeyRevoked

object

Field Contract

id required

string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

revoked required

boolean

constant: true

Account

object

Field	Contract
`id` required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`email` required	`string`
`virtual_number` required	`string` \| `null`
`subscription` required	`object`
`subscription.type` required	`string` one of: NONE, LITE, STANDARD, PREMIUM, BUSINESS, MULTI_BUILDING
`subscription.status` required	`string` one of: none, active, past_due
`usage` required	`object`
`usage.total_unlocks` required	`integer` Recorded activity count, including failed attempts; not a physical-entry count.
`usage.active_routines` required	`integer` Stored activated rules; not necessarily currently effective.
`usage.shared_users` required	`integer` Number of users associated with the number.
`created_at` required	`string` ISO 8601 timestamp. format: date-time
`buildings` required	`object`
`buildings.count` required	`integer`
`buildings.selection_required` required	`boolean`
`buildings.list_command` required	`string`
`capabilities` required	`object`
`capabilities.multi_building` required	`boolean`
`capabilities.access_types` required	`array` of `string` one of: timer, passcode, routine
`capabilities.scopes` required	`array` of `string` May contain owner for legacy unscoped keys.
`readiness` required	`object`
`readiness.can_create_access` required	`boolean` Readiness hint; creation still validates plan, scope, setup, and selected building.
`readiness.building_connection` required	`string` one of: not_provisioned, previous_buzz_recorded, unverified
`readiness.physical_entry_verified` required	`boolean` constant: false
`next_actions` required	`array` of `object`
`next_actions[].command` required	`string`
`next_actions[].reason` required	`string`

CheckoutRequest

object

Unknown fields rejected.

Field	Contract
`plan` required	`string` one of: standard_monthly, standard_yearly, premium_monthly, premium_yearly

Checkout

object

Field	Contract
`status` required	`string` constant: "none"
`payment_required` required	`boolean` constant: false
`next_action` required	`string`

| object

Field	Contract
`id` required	`string` Stripe checkout session ID. \| `null`
`request_id` required	`string`
`plan` required	`string` one of: standard_monthly, standard_yearly, premium_monthly, premium_yearly
`url` required	`string` format: uri \| `null`
`status` required	`string` one of: preparing, open, complete, expired, failed
`payment_required` required	`boolean`
`next_action` required	`string`
`message` required	`string`

CheckoutExpired

object

Field	Contract
`id` required	`string`
`status` required	`string` constant: "expired"
`payment_required` required	`boolean` constant: false

Portal

object

Field Contract

url required

string

Hosted Stripe billing-management URL.

format: uri

Setup

object

Field	Contract
`building_id` required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`virtual_number` required	`string` \| `null`
`unlock_tone` required	`string` \| `null`
`last_successful_buzz_at` required	`string` ISO 8601 timestamp. format: date-time \| `null`
`status` required	`string` one of: awaiting_subscription_or_provisioning, previous_buzz_recorded, building_setup_required
`instructions` required	`string`

SetupRequest

object

Unknown fields rejected.

Field Contract

unlock_tone required

string

Exact building release keypress; test at the entrance.

pattern: ^[0-9#*]{1,3}$

SetupUpdated

object

Field	Contract
`building_id` required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`virtual_number` required	`string`
`unlock_tone` required	`string`
`physical_test_required` required	`boolean` constant: true

Address

object

Field	Contract
`street` optional	`string`
`city` optional	`string`
`state` optional	`string`
`zip` optional	`string`
`country` optional	`string`

Buildings

object

Field	Contract
`data` required	`array` of `object`
`data[].id` required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`data[].label` required	`string`
`data[].address` required	Address \| `null`
`data[].virtual_number` required	`string` \| `null`
`data[].is_primary` required	`boolean`
`data[].provisioned` required	`boolean`
`selection_required` required	`boolean`
`next_action` required	`string`

BuildingAddPreview

object

Unknown fields rejected.

Field	Contract
`action` required	`string` constant: "add"
`label` required	`string` Nonblank; trimmed. maxLength: 120
`address` required	`object` Unknown fields rejected.
`address.street` optional	`string` maxLength: 200
`address.city` required	`string` Nonblank; trimmed. maxLength: 120
`address.state` required	`string` Normalized uppercase. pattern: ^[A-Za-z]{2}$
`address.zip` required	`string` pattern: ^[0-9]{5}(-[0-9]{4})?$
`address.country` optional	`string` constant: "US" default: "US"
`unlock_tone` required	`string` Exact building release keypress; test at the entrance. pattern: ^[0-9#*]{1,3}$
`phone_number` optional	`string` Resident forwarding number. Defaults to parent phone if omitted; a valid number is still required. pattern: ^\+[1-9][0-9]{6,14}$

BuildingRemovePreview

object

Unknown fields rejected.

Field Contract

action required

string

constant: "remove"

building_id required

string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

BuildingPreview

BuildingAddPreview | BuildingRemovePreview

QuoteRequest

object

Unknown fields rejected.

Field Contract

quote_id required

string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

BuildingOperation

object

Field	Contract
`id` required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`action` required	`string` one of: add, remove
`status` required	`string` one of: quoted, expired, running, succeeded, reconciliation_required
`input` required	`object` Add: normalized label/address/unlock_tone/phone_number. Remove: building_id/label/virtual_number/effects. Inspect the exact snapshot before execution.
`input.label` optional	`string`
`input.address` optional	Address
`input.unlock_tone` optional	`string`
`input.phone_number` optional	`string`
`input.building_id` optional	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`input.virtual_number` optional	`string` \| `null`
`input.effects` optional	`array` of `string`
`billing` required	`object`
`billing.subscription_id` required	`string`
`billing.price_id` required	`string`
`billing.current_quantity` required	`integer`
`billing.new_quantity` required	`integer`
`billing.currency` required	`string`
`billing.next_invoice_amount_due` required	`integer` Entire upcoming invoice estimate in minor currency units, not an immediate charge or refund.
`billing.per_building_amount` required	`integer` Can be null for tiered pricing. Do not multiply this to reconstruct the invoice. \| `null`
`billing.interval` optional	`string`
`billing.proration_date` required	`integer` Unix seconds used for the preview and execution.
`billing.note` required	`string`
`expires_at` required	`string` ISO 8601 timestamp. format: date-time
`building_id` required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$ \| `null`
`request_id` required	`string` \| `null`
`result` required	`object` Add result: building_id, label, virtual_number, physical_test_required. Remove result: building_id, deleted, released_number. Null until succeeded. \| `null`
`result.building_id` required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`result.label` optional	`string`
`result.virtual_number` optional	`string`
`result.physical_test_required` optional	`boolean` constant: true
`result.deleted` optional	`boolean` constant: true
`result.released_number` optional	`string` \| `null`
`next_action` required	`string`

TimerCreate

object

Unknown fields rejected.

Field Contract

type required

string

constant: "timer"

label optional

string

Defaults to the grant type when omitted or empty on creation.

maxLength: 120

duration_minutes required

integer

Starts/restarts the timer immediately.

minimum: 1
maximum: 1440

PasscodeCreate

object

Unknown fields rejected.

Field	Contract
`type` required	`string` constant: "passcode"
`label` optional	`string` Defaults to the grant type when omitted or empty on creation. maxLength: 120
`code` optional	`string` Omit to generate exactly four digits. Custom codes retain app compatibility: 1–4 digits except 1 alone. Preserve leading zeroes. Six-digit visitor codes are rejected. pattern: ^(?!1$)[0-9]{1,4}$
`max_uses` optional	`integer` On update, resets both maximum and remaining uses. minimum: 1 maximum: 100 default: 1
`voice_enabled` optional	`boolean` Allow spoken-code recognition. default: false
`expires_at` optional	`string` Future ISO timestamp with Z or numeric timezone offset, no more than seven days ahead. Cannot combine with expires_in_minutes. format: date-time
`expires_in_minutes` optional	`integer` Default expiry is 60 minutes. Do not combine with expires_at. minimum: 1 maximum: 10080 default: 60

RoutineCreate

object

Unknown fields rejected.

Field	Contract
`type` required	`string` constant: "routine"
`label` optional	`string` Defaults to the grant type when omitted or empty on creation. maxLength: 120
`days` required	`array` of `string` Day name, case-insensitive: sunday, monday, tuesday, wednesday, thursday, friday, saturday. Case-insensitive input. Only one day, all five weekdays, both weekend days, or all seven days are supported. Arbitrary subsets and duplicates are not supported. minItems: 1 maxItems: 7
`start` required	`string` 24-hour HH:MM. End must be later than start on the same day; no overnight window. pattern: ^([01][0-9]\|2[0-3]):[0-5][0-9]$
`end` required	`string` 24-hour HH:MM. End must be later than start on the same day; no overnight window. pattern: ^([01][0-9]\|2[0-3]):[0-5][0-9]$
`timezone` required	`string` Valid IANA timezone, such as America/Los_Angeles.

UnlockCreate

TimerCreate | PasscodeCreate | RoutineCreate

TimerUpdate

object

minProperties: 1

Unknown fields rejected.

Field Contract

label optional

string

Defaults to the grant type when omitted or empty on creation.

maxLength: 120

active optional

boolean

False ends timer now; true restarts with stored duration unless a new duration is supplied.

duration_minutes optional

integer

Starts/restarts the timer immediately.

minimum: 1
maximum: 1440

PasscodeUpdate

object

minProperties: 1

Unknown fields rejected.

Field	Contract
`label` optional	`string` Defaults to the grant type when omitted or empty on creation. maxLength: 120
`active` optional	`boolean`
`code` optional	`string` Optional replacement code; omission leaves the current code unchanged. Same 1–4 digit app-compatible validation as creation. pattern: ^(?!1$)[0-9]{1,4}$
`max_uses` optional	`integer` Optional; supplying it resets both maximum and remaining uses. minimum: 1 maximum: 100
`voice_enabled` optional	`boolean`
`expires_at` optional	`string` Future ISO timestamp with Z or numeric timezone offset, no more than seven days ahead. Cannot combine with expires_in_minutes. format: date-time

RoutineUpdate

object

minProperties: 1

Unknown fields rejected.

Field	Contract
`label` optional	`string` Defaults to the grant type when omitted or empty on creation. maxLength: 120
`active` optional	`boolean`
`days` optional	`array` of `string` Day name, case-insensitive: sunday, monday, tuesday, wednesday, thursday, friday, saturday. Case-insensitive input. Only one day, all five weekdays, both weekend days, or all seven days are supported. Arbitrary subsets and duplicates are not supported. minItems: 1 maxItems: 7
`start` optional	`string` 24-hour HH:MM. End must be later than start on the same day; no overnight window. pattern: ^([01][0-9]\|2[0-3]):[0-5][0-9]$
`end` optional	`string` 24-hour HH:MM. End must be later than start on the same day; no overnight window. pattern: ^([01][0-9]\|2[0-3]):[0-5][0-9]$
`timezone` optional	`string` IANA timezone.

UnlockUpdate

TimerUpdate | PasscodeUpdate | RoutineUpdate

Nonempty body; fields must match existing grant type. Type cannot change. Include start and end together if changing either. expires_in_minutes is creation-only.

Unlock

object

Field	Contract
`building_id` required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`id` required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`type` required	`string` one of: timer, passcode, routine
`label` required	`string`
`active` required	`boolean` For routines, enabled does not mean currently inside the schedule.
`version` required	`integer`
`status` required	`string` one of: active, inactive, expired, exhausted, revoked
`request_id` optional	`string` Original create idempotency key, absent on older app-created rules.
`created_at` required	`string` ISO 8601 timestamp. format: date-time
`updated_at` optional	`string` ISO 8601 timestamp. format: date-time
`duration_minutes` optional	`integer`
`expires_at` optional	`string` ISO 8601 timestamp. format: date-time
`code` optional	`string` Sensitive visitor code, present for passcodes.
`max_uses` optional	`integer` \| `null`
`remaining_uses` optional	`integer` \| `null`
`voice_enabled` optional	`boolean`
`days` optional	`array` of `string`
`start` optional	`string`
`end` optional	`string`
`timezone` optional	`string`

Pagination

object

Field	Contract
`cursor` required	`string` Pass unchanged into the next request with the same filters and building. \| `null`
`has_more` required	`boolean`

UnlockPage

object

Field	Contract
`data` required	`array` of Unlock
`pagination` required	Pagination

UnlockRevoked

object

Field Contract

id required

string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

deleted required

boolean

constant: true

status required

string

constant: "revoked"

Log

object

Field	Contract
`building_id` required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`id` required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`unlock_id` optional	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`type` required	`string` constant: "unlock"
`unlock_type` optional	`string` timer, passcode, routine, or unknown(N) for legacy values.
`name` required	`string`
`succeeded` required	`boolean`
`created_at` required	`string` ISO 8601 timestamp. format: date-time
`passcode` optional	`string` May contain an attempted or accepted code. Treat activity data as sensitive.

LogPage

object

Field Contract

building_id required

string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

data required array of Log

pagination required Pagination

WebhookCreate

object

Field Contract

url required

string

Production: HTTPS, no URL credentials, DNS must resolve to supported public IPv4. Private/reserved destinations and IPv6-only endpoints are unsupported. Redirects are not followed.

format: uri

events required

array of string

one of: unlock.created, unlock.completed, unlock.expired, unlock.revoked, access.denied

Required in REST. The CLI alone defaults to unlock.completed.

minItems: 1

description optional string

WebhookUpdate

object

Field	Contract
`url` optional	`string` format: uri
`events` optional	`array` of `string` one of: unlock.created, unlock.completed, unlock.expired, unlock.revoked, access.denied minItems: 1
`description` optional	`string`
`active` optional	`boolean` Setting true resets consecutive failures and clears disabled metadata.

Webhook

object

Field	Contract
`id` required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`url` required	`string`
`events` required	`array` of `string` one of: unlock.created, unlock.completed, unlock.expired, unlock.revoked, access.denied
`description` optional	`string`
`active` required	`boolean`
`consecutiveFailures` optional	`integer`
`lastSuccessAt` optional	`string` ISO 8601 timestamp. format: date-time
`lastFailureAt` optional	`string` ISO 8601 timestamp. format: date-time
`disabledAt` optional	`string` ISO 8601 timestamp. format: date-time
`disabledReason` optional	`string`
`createdAt` required	`string` ISO 8601 timestamp. format: date-time
`updatedAt` optional	`string` ISO 8601 timestamp. format: date-time

WebhookCreated

object

Field	Contract
`id` required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`url` required	`string`
`events` required	`array` of `string` one of: unlock.created, unlock.completed, unlock.expired, unlock.revoked, access.denied
`description` optional	`string`
`active` required	`boolean`
`secret` required	`string` 64 hex characters, returned only here. Use the string itself as the HMAC key, not hex-decoded bytes.
`createdAt` required	`string` ISO 8601 timestamp. format: date-time

Webhooks

object

Field	Contract
`data` required	`array` of Webhook

Deleted

object

Field Contract

id required

string

Opaque resource ID, normally 24 hexadecimal characters.

pattern: ^[a-fA-F0-9]{24}$

deleted required

boolean

constant: true

WebhookTest

object

Field	Contract
`success` required	`boolean` Inspect this even when the API returns HTTP 200.
`statusCode` optional	`integer` Present when endpoint responded.
`latencyMs` required	`integer`
`errorMessage` optional	`string` May be present for a transport failure.

WebhookEvent

object

Field	Contract
`event` required	`string` one of: unlock.completed, unlock.revoked, access.denied, webhook.test
`eventId` required	`string` Deduplicate this ID; retries retain it.
`building_id` required	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`created_at` optional	`string` ISO 8601 timestamp. format: date-time
`data` required	`object` unlock.completed: routine_id, unlock_id, activity_id, occurred_at, name, numeric unlock_type. unlock.revoked: routine_id, name, reason. access.denied: attempted_passcode (may be omitted). webhook.test: message only.
`data.routine_id` optional	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`data.unlock_id` optional	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`data.activity_id` optional	`string` Opaque resource ID, normally 24 hexadecimal characters. pattern: ^[a-fA-F0-9]{24}$
`data.occurred_at` optional	`string` ISO 8601 timestamp. format: date-time
`data.name` optional	`string`
`data.unlock_type` optional	`integer` Numeric callback values: 1 timer, 2 passcode, 3 routine. Log values are strings.
`data.reason` optional	`string` constant: "uses_exhausted"
`data.attempted_passcode` optional	`string` Denied events can contain the attempted digits or speech. Do not log indiscriminately.
`data.message` optional	`string`

Every endpoint.Every field.

Implementation reference

HTTP, authentication, and limits

REST examples

Callback payloads and signature verification

Errors and recovery

Every REST operation

GET /v1/health

Check service health

Responses

GET /v1/plans

Read live public prices

Responses

POST /v1/auth/otp

Request email sign-in code

JSON request body

Responses

POST /v1/auth/verify

Verify email and obtain owner credential

JSON request body

Responses

DELETE /v1/auth/key

Revoke the current credential

Responses

POST /v1/auth/keys

Create an agent credential

JSON request body

Responses

GET /v1/auth/keys

List manageable agent credentials

Responses

DELETE /v1/auth/keys/{id}

Revoke a manageable agent key

Parameters

Responses

GET /v1/account

Inspect account readiness

Responses

GET /v1/billing/plans

Read authenticated price catalog

Responses

GET /v1/billing/checkout

Recover latest checkout

Responses

POST /v1/billing/checkout

Start or recover hosted checkout

Parameters

JSON request body

Responses

POST /v1/billing/checkout/{id}/expire

Expire unpaid checkout

Parameters

Responses

POST /v1/billing/portal

Open hosted billing management

Responses

GET /v1/setup

Inspect selected building setup

Parameters

Responses

PATCH /v1/setup

Configure selected building release tone

Parameters

JSON request body

Responses

GET /v1/buildings

List accessible buildings

Responses

POST /v1/buildings

Execute quoted building addition

Parameters

JSON request body

Responses

POST /v1/buildings/preview

Preview addition or removal

JSON request body

Responses

DELETE /v1/buildings/{id}

Execute quoted building removal

Parameters

Every endpoint.
Every field.

`GET /v1/health`

`GET /v1/plans`

`POST /v1/auth/otp`

`POST /v1/auth/verify`

`DELETE /v1/auth/key`

`POST /v1/auth/keys`

`GET /v1/auth/keys`

`DELETE /v1/auth/keys/{id}`

`GET /v1/account`

`GET /v1/billing/plans`

`GET /v1/billing/checkout`

`POST /v1/billing/checkout`

`POST /v1/billing/checkout/{id}/expire`

`POST /v1/billing/portal`

`GET /v1/setup`

`PATCH /v1/setup`

`GET /v1/buildings`

`POST /v1/buildings`

`POST /v1/buildings/preview`

`DELETE /v1/buildings/{id}`

`GET /v1/buildings/operations/{id}`

`POST /v1/unlock`

`GET /v1/unlock`

`GET /v1/unlock/{id}`

`PATCH /v1/unlock/{id}`

`DELETE /v1/unlock/{id}`

`GET /v1/logs`

`POST /v1/webhooks`

`GET /v1/webhooks`

`PATCH /v1/webhooks/{id}`

`DELETE /v1/webhooks/{id}`

`POST /v1/webhooks/{id}/test`