API reference
Ingest
Send profiles, events, devices and store relationships in one call, and report push opens from apps.
Send profiles, events, devices and store relationships in one call, and report push opens from apps.
POST /v1/batch#
Ingest profiles, events, devices and relationships
Workspace, Track and app keys. With a Track or app key, send the person's identity token in X-Sapagan-User-Token (an identity token signed by your backend, or your registered session JWT): profile items, device registrations and relationships must then name its subject. App keys always need it, Track keys when the workspace requires identity (Settings, Setup). A token that does not verify is 401 invalid_user_token; items the rule refuses are reported per item (user_token_required, user_token_mismatch, identifier_not_allowed). Browser calls are allowed only from the workspace's web origins.
Request body
| Field | Type | Notes |
|---|---|---|
items required | any[] |
curl -X POST "$SAPAGAN_URL/v1/batch" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"type": "profile",
"id": "user-42",
"attributes": {
"name": "Budi Santoso",
"plan": "gold"
}
},
{
"type": "event",
"profileId": "user-42",
"name": "order_placed",
"timestamp": "2026-11-17T09:30:00+07:00",
"properties": {
"total": 150000
},
"dedupeId": "order-1042"
},
{
"type": "device",
"op": "upsert",
"profileId": "user-42",
"platform": "android",
"token": "<FCM registration token>"
}
]
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/batch`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"items": [
{
"type": "profile",
"id": "user-42",
"attributes": {
"name": "Budi Santoso",
"plan": "gold"
}
},
{
"type": "event",
"profileId": "user-42",
"name": "order_placed",
"timestamp": "2026-11-17T09:30:00+07:00",
"properties": {
"total": 150000
},
"dedupeId": "order-1042"
},
{
"type": "device",
"op": "upsert",
"profileId": "user-42",
"platform": "android",
"token": "<FCM registration token>"
}
]
}),
});
const data = await res.json();Responses
{
"results": [
{
"index": 0,
"status": "ok"
},
{
"index": 1,
"status": "ok"
},
{
"index": 2,
"status": "ok"
}
],
"summary": {
"items": 3,
"ok": 3,
"errors": 0,
"events": {
"received": 1,
"inserted": 1,
"duplicates": 0,
"clamped": 0,
"backfilled": 0
}
}
}POST /v1/push/opened#
Report a push opened or delivered (app SDK)
The app's ingest key reports opened or delivered for the delivery in the push's data.k_did. Recorded once per delivery and metric. Always 202: recorded is false for a repeat and, identically, for an unknown or foreign delivery or a profileId that is not the recipient.
Request body
| Field | Type | Notes |
|---|---|---|
deliveryId required | string | |
event required | "opened" | "delivered" | |
at required | string (date-time) | |
profileId | string or null | min 1, max 200 |
anonymousId | string or null | min 1, max 200 |
device required | object | |
device.token | string or null | min 1, max 4096 |
device.platform required | "android" | "ios" | "web" |
curl -X POST "$SAPAGAN_URL/v1/push/opened" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"deliveryId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
"event": "opened",
"at": "2026-11-17T09:31:00+07:00",
"device": {
"platform": "android"
}
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/push/opened`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"deliveryId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
"event": "opened",
"at": "2026-11-17T09:31:00+07:00",
"device": {
"platform": "android"
}
}),
});
const data = await res.json();Responses
{
"recorded": true
}