Fictura
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
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 — events takes an array of up to 500, and one request per batch is the intended shape.
  • status is success, failure, or info; 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. source accepts frontend or backend; webhook is reserved for Fictura's own billing events.
  • Events disabled on the dashboard are dropped at ingestion — dropped in the response counts them. An event refused on its own appears in failed.

The full body schema — attribution fields, targeting attributes and their limits — is on Ingest events.