SDK reference
Server events
Your backend can log events into the same pipeline the app uses — one POST, marked source: backend, joined to the same user.
Anything your server knows that the app doesn't — a generation finishing, a job failing, a quota tripping — can be an event. Send it with the same x-api-key the SDK uses and the user's id in the x-account-id header, and it lands in the same dictionary, funnels and cohorts as everything else.
curl -X POST https://api.fictura.co/api/v1/events/log \
-H "x-api-key: gk_..." \
-H "x-account-id: <your user id>" \
-H "Content-Type: application/json" \
-d '{"events":[{"event_name":"generation_success","status":"success","source":"backend","properties":{"model":"large"}}]}'200 — application/json
{
"ok": true,
"master_user_id": "0f1e2d3c-4b5a-6978-8695-a4b3c2d1e0f9",
"dropped": 0,
"failed": [],
"throttled": 0,
"warnings": 0
}- Batch freely —
eventstakes an array of up to 500, and one request per batch is the intended shape. statusissuccess,failure, orinfo; the success/failure pair is what powers the generation-health view.- Mark server events
source: "backend"so the Events tab can tell them from app events.sourceacceptsfrontendorbackend;webhookis reserved for Fictura's own billing events. - Events disabled on the dashboard are dropped at ingestion —
droppedin the response counts them. An event refused on its own appears infailed.
The full body schema — attribution fields, targeting attributes and their limits — is on Ingest events.