POST/v1/beacons

Record beacon

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

Secret key requiredSecret key, browser activation context, or asset token where issuedSandbox this

Request parameters

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

Returns

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

Request example

POST /v1/beacons

record-beacon.shbash

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

Response example

Response

response.jsonjson

1{2  "ok": true,3  "duplicate": false,4  "request_id": "req_W2B90p"5}

Errors

unauthorized401

Missing auth or asset token.

validation_error400

Unsupported event name or malformed body.

not_found404

Slot was not found.

API v1 overview →Testing in sandbox →Errors →