Ingest events

The write path for the whole analytics product — the same endpoint the SDK batches to, open to your backend as well.

Authorization & identity

x-api-key carries your SDK app key. Identity rides in headers: x-device-id and x-account-id — send whichever you have; Fictura stitches them into one user and answers with the resulting master_user_id.

Body

events

array · required · min 1

Each: event_name (string, any name), optional status (success | failure | info), optional source (frontend | backend), optional properties (object). webhook as a source is reserved for Fictura's own billing events.

revenuecat_id

string · nullable

The RevenueCat app user id, for identity stitching with billing webhooks.

attributes

object

Targeting attributes merged onto the user: keys [a-zA-Z0-9_], max 40 chars, max 20 keys; values string (≤200), number, or boolean. $-prefixed keys are rejected — the server stamps $platform, $app_version, $country itself.

attribution

object

First-touch fields: link_slug, utm_*, click_id, install_referrer, growth_click_id. The SDK fills these automatically; server senders rarely need them.

platform / app_version / country

strings

ios | android | web; version ≤40 chars; ISO-3166 alpha-2.

cURL

curl -X POST https://api.fictura.co/api/v1/events/log \
  -H "x-api-key: gk_..." \
  -H "x-account-id: 8f14e45f" \
  -H "Content-Type: application/json" \
  -d '{"events":[{"event_name":"generation_success","status":"success","source":"backend"}]}'

200 — accepted

{
  "ok": true,
  "master_user_id": "0f1e2d3c-4b5a-6978-8695-a4b3c2d1e0f9"
}

200 — every event disabled

{
  "ok": true,
  "dropped": 3
}

Events switched off in capture control are dropped at ingestion. The dropped response appears only when the whole batch was disabled; a mixed batch answers normally with just the live events kept. When a batch's attribution resolves an install, the response additionally carries a conversion object the SDK uses for deferred deep links.

Authorization & identity

Body

On this page