Reference
API reference
Send events, identify users and register devices directly: authentication, endpoints, limits and examples.
Authentication#
http
Authorization: Bearer nak_pk_live_YOUR_KEY
X-Nerja-App-Id: com.yourshop.app # mobile apps only
Content-Type: application/jsonBrowsers send the key from your allowed website (the Origin is checked). Mobile apps send X-Nerja-App-Id, which must be allowed for the key. Server keys (SECRET) skip both checks.
Send an event#
POST /v1/events
curl -X POST https://api.nerja.ai/v1/events \
-H "Authorization: Bearer $NERJA_KEY" -H "Content-Type: application/json" \
-d '{
"id": "7c0f2e9c-5b1d-4b7a-9d61-1e0a6a6f2a10",
"event": "add_to_cart",
"timestamp": 1791900000000,
"user_id": "user_42",
"properties": { "products": [{ "id": "sku-1", "name": "Amber Oud", "quantity": 1, "price": 249 }], "currency": "SAR" }
}'
# → 202 Accepted| Field | Notes |
|---|---|
id | A UUID you generate. The same id is only ever processed once, so retries are safe. |
event | An event name — see the tag's list, or your own custom name. |
timestamp | Milliseconds since epoch. |
user_id / anonymous_id | At least one. Send both to link history. |
properties | Free-form; products use id, name, price, quantity, image_url, url. |
Send a batch#
POST /v1/events/batch with { "batch": [ …events ] } (up to 100 events). Prefer this from servers and apps.
Identify#
POST /v1/identify
curl -X POST https://api.nerja.ai/v1/identify \
-H "Authorization: Bearer $NERJA_KEY" -H "Content-Type: application/json" \
-d '{ "user_id": "user_42", "anonymous_id": "…", "traits": { "email": "sara@example.com", "first_name": "Sara" } }'Register a device#
POST /v1/devices
curl -X POST https://api.nerja.ai/v1/devices \
-H "Authorization: Bearer $NERJA_KEY" -H "X-Nerja-App-Id: com.yourshop.app" \
-H "Content-Type: application/json" \
-d '{ "fcmToken": "…", "platform": "ANDROID", "userId": "user_42", "anonymousId": "…", "appId": "com.yourshop.app" }'
# DELETE /v1/devices/{fcmToken} on logout or uninstallPlatforms: ANDROID, IOS, WEB. If you use SDKs you never call this yourself.
Push receipts#
http
POST /v1/tracking/push/{executionId}/{delivered|opened|clicked} → 204
# executionId arrives in the push's data as exec_id (or use the receipt_url field)No key needed — the execution id is the secret; repeats are ignored.
Limits and errors#
| Endpoint | Limit |
|---|---|
| POST /v1/events | 100 / minute |
| POST /v1/events/batch | 30 / minute, ≤ 100 events each |
| POST /v1/identify | 50 / minute |
| POST /v1/devices | 30 / minute |
| Status | Meaning |
|---|---|
| 202 | Accepted (events are processed asynchronously) |
| 400 | Invalid body, e.g. unknown field shape — the response lists the issues |
| 401 | Missing/invalid key, key revoked, origin or app id not allowed, or a signed user id is required |
| 429 | Rate limit — retry with backoff |
Prefer to talk it through? Book a 30-minute call with the Nerja team.
Something unclear or missing? Email support@nerja.ai and we will improve this page.