/api/v1/events/logIngest 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. Ids like guest, null or 0, and any id under 5 or over 200 characters, are ignored for matching (and counted as an ingest warning); a batch left with no usable id has every event refused with no_valid_identity.
Body
Each: event_name (string, 1 to 200 characters, no control characters, not starting with $), optional status (success | failure | info), optional source (frontend | backend), optional properties (object, at most 255 keys and 64 KB serialized). webhook as a source is reserved for Fictura's own billing events. Optional uuid (a UUID, which deduplicates retries; any other value is ignored) and timestamp (ISO time the event happened on the device). Use lower snake_case names; a mixed-case name is stored with a name_casing warning.
When the device sent the batch. With each event's timestamp, it corrects the device's clock skew.
The RevenueCat app user id, for identity stitching with billing webhooks.
Targeting attributes merged onto the user: keys [a-zA-Z0-9_], max 40 chars, max 100 keys across this and attributes_set_once; values string (≤1,024), number, or boolean. A bad key or value is dropped with an attribute_dropped warning; the batch is still stored. $-prefixed keys are dropped the same way; the server stamps $platform, $app_version, $country itself.
Attributes to set only where the user has no value yet, and attribute keys to remove. Same key and value rules as attributes.
Keep each event's old timestamp and skip the rate limits. Needs a second key: see Historical import.
First-touch fields: link_slug, utm_*, click_id, install_referrer, growth_click_id. The SDK fills these automatically; server senders rarely need them.
ios | android | web; version ≤40 chars; ISO-3166 alpha-2.
What the sender had to drop before sending, since its last successful flush: a total, and counts by reason ({"queue_full": 3}). Recorded as ingest warnings; never fails the batch.
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"}]}'Response
Events are judged one at a time. A bad event is refused on its own and the rest of the batch is stored, so a 200 can carry refusals. Only a malformed body (400 validation_error), more than 500 events (400 too_many_events), a refused historical flag (403 historical_requires_import_key) or the per-app rate limit (429) fails the whole batch.
{
"ok": true,
"master_user_id": "0f1e2d3c-4b5a-6978-8695-a4b3c2d1e0f9",
"dropped": 0,
"failed": [],
"throttled": 0,
"warnings": 0
}{
"ok": true,
"master_user_id": "0f1e2d3c-4b5a-6978-8695-a4b3c2d1e0f9",
"dropped": 1,
"deduped": 2,
"rejected": 2,
"failed": [
{ "index": 3, "reason": "reserved_name" },
{ "index": 7, "reason": "too_large" }
],
"throttled": 5,
"warnings": 1
}| Field | Always? | Meaning |
|---|---|---|
master_user_id | when something was stored | The user the batch was stitched to. |
dropped | yes | Events switched off in capture control, dropped silently, or carrying an identifier of a deleted person. |
deduped | when non-zero | Events whose uuid repeated inside the batch (the first one was kept) or was already stored. |
failed | yes | Refused events: index is the event's position in the batch as sent, reason is one of the reasons below. Do not resend them unchanged. |
rejected | when non-zero | failed.length. |
throttled | yes | Events dropped from the end of the batch because this device went over 600 events a minute. |
warnings | yes | Events stored but flagged (mixed-case name, ignored identifier, dropped attribute, clock skew not corrected, an unplanned event or a missing required property). |
conversion | when present | Set when the batch's attribution resolved an install; the SDK uses it for deferred deep links. |
Reasons in failed:
reason | Why |
|---|---|
invalid_event | The event is not an object, or a field has a value it cannot take: properties not an object, status or source outside the allowed values. |
invalid_name | event_name is missing, empty, longer than 200 characters or has control characters. |
reserved_name | event_name starts with $. Only the SDK's own $opt_in, $abnormal_exit and $ota_emergency_launch pass. |
too_many_properties | More than 255 property keys. |
too_large | Properties over 64 KB serialized. |
no_valid_identity | The request carried no usable device, account or RevenueCat id. |
Every refusal and warning is also counted on Dashboard → Events → Manage → Problems with incoming events, with the latest example, so a problem in production shows up as a number rather than silence.
Retrieve entitlement
Ask Fictura whether a user is currently entitled, instead of maintaining your own billing table. Derived from Stripe's and the stores' own webhooks; fails closed.
Event config
The kill-switch list, readable by anything that sends events — so disabled events can be skipped at the source instead of discarded on arrival.