SapaganDocs sapagan.com

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.

Accepted keys Server key Track key App key

Request body

FieldTypeNotes
items requiredany[]
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>"
      }
    ]
  }'

Responses

200 OK, 400 Invalid request, 401 Unauthorized, 403 Forbidden, 413 Too large, 503 Unavailable. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Track key App key

Request body

FieldTypeNotes
deliveryId requiredstring
event required"opened" | "delivered"
at requiredstring (date-time)
profileIdstring or nullmin 1, max 200
anonymousIdstring or nullmin 1, max 200
device requiredobject
device.tokenstring or nullmin 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"
    }
  }'

Responses

202 Accepted, 400 Invalid request, 429 Rate limited. Errors use the error body.

Example response 202

{
  "recorded": true
}