POST/v1/beacons

Record beacon

Send one event per user-observable lifecycle transition. Beacon writes are designed to be idempotent by beacon_id.

Auth: Secret key, browser activation context, or asset token where issued

Request parameters

Name	Type	Required	Description
beacon_id	string	Yes	Idempotency key for this beacon event.
slot_id	string	Yes	Slot associated with the rendered decision.
event	string	Yes	rendered, visible, clicked, completed, dismissed, or equivalent supported event.
occurred_at	string	Yes	ISO timestamp for when the event happened.

Response fields

Name	Type	Required	Description
ok	boolean	Yes	Whether the beacon was accepted.
duplicate	boolean	No	True when the idempotency key was already recorded.
request_id	string	Yes	Support identifier.

Examples

record-beacon.sh

curl -X POST https://api.wavebird.ai/v1/beacons \
  -H "Authorization: Bearer sk_test_wavebird_demo_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "beacon_id": "bcn_demo_123",
    "slot_id": "slot_demo_123",
    "event": "visible",
    "occurred_at": "2026-04-24T12:00:00.000Z"
  }'

Response example

{
  "ok": true,
  "duplicate": false,
  "request_id": "req_W2B90p"
}

Errors

unauthorized401

Missing auth or asset token.

validation_error400

Unsupported event name or malformed body.

not_found404

Slot was not found.

Decisions

Consent

Code

Record beacon

Records render, visible, click, complete, or dismiss events for billing and proof integrity.

record-beacon.sh

curl -X POST https://api.wavebird.ai/v1/beacons \
  -H "Authorization: Bearer sk_test_wavebird_demo_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "beacon_id": "bcn_demo_123",
    "slot_id": "slot_demo_123",
    "event": "visible",
    "occurred_at": "2026-04-24T12:00:00.000Z"
  }'

Need rollout review?

Contact the team

Start in the dashboard, choose Script Tag or Server API, and use contact only when you need rollout review, enterprise coordination, or non-standard integration help. Billing beacon rules live in the API concepts guide.