Fictura
Events
POST/api/v1/events/log

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

events
array · required · 1 to 500

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.

sent_at
string · ISO time

When the device sent the batch. With each event's timestamp, it corrects the device's clock skew.

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 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_set_once / attributes_unset
object / array

Attributes to set only where the user has no value yet, and attribute keys to remove. Same key and value rules as attributes.

historical
boolean

Keep each event's old timestamp and skip the rate limits. Needs a second key: see Historical import.

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.

client_dropped / client_dropped_reasons
number / object

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

200 — accepted
{
  "ok": true,
  "master_user_id": "0f1e2d3c-4b5a-6978-8695-a4b3c2d1e0f9",
  "dropped": 0,
  "failed": [],
  "throttled": 0,
  "warnings": 0
}
200 — some events refused, some throttled
{
  "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
}
FieldAlways?Meaning
master_user_idwhen something was storedThe user the batch was stitched to.
droppedyesEvents switched off in capture control, dropped silently, or carrying an identifier of a deleted person.
dedupedwhen non-zeroEvents whose uuid repeated inside the batch (the first one was kept) or was already stored.
failedyesRefused events: index is the event's position in the batch as sent, reason is one of the reasons below. Do not resend them unchanged.
rejectedwhen non-zerofailed.length.
throttledyesEvents dropped from the end of the batch because this device went over 600 events a minute.
warningsyesEvents stored but flagged (mixed-case name, ignored identifier, dropped attribute, clock skew not corrected, an unplanned event or a missing required property).
conversionwhen presentSet when the batch's attribution resolved an install; the SDK uses it for deferred deep links.

Reasons in failed:

reasonWhy
invalid_eventThe 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_nameevent_name is missing, empty, longer than 200 characters or has control characters.
reserved_nameevent_name starts with $. Only the SDK's own $opt_in, $abnormal_exit and $ota_emergency_launch pass.
too_many_propertiesMore than 255 property keys.
too_largeProperties over 64 KB serialized.
no_valid_identityThe 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.

On this page