Server-side events

The Events API is part of the v1 REST API design-partner preview. It has no public host yet — YOUR-FLOKIT-API-HOST is a placeholder your FloKit team fills in when you get preview access. To send app events today, use @flokitai/subscriptions-sdk or the live measurement ingest endpoint.

The FloKit Events API accepts JSON events from your server. Use it to send funnel events, revenue events, or custom events not covered by your subscription platform.

Authentication

All requests require an API key passed as a Bearer token.

Authorization: Bearer $FLOKIT_API_KEY

Find or create API keys in FloKit → Settings → API Keys. Base URL: https://YOUR-FLOKIT-API-HOST

Send a single event

curl -X POST https://YOUR-FLOKIT-API-HOST/v1/events \
  -H "Authorization: Bearer $FLOKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "paywall_viewed",
    "user_id": "usr_abc123",
    "anonymous_id": "anon_xyz789",
    "timestamp": "2024-03-15T14:22:00Z",
    "properties": {
      "paywall_id": "pw_annual_v3",
      "offer_id": "offer_intro_50pct",
      "context": "onboarding_step_3"
    }
  }'

const response = await fetch('https://YOUR-FLOKIT-API-HOST/v1/events', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.FLOKIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    event: 'paywall_viewed',
    user_id: 'usr_abc123',
    anonymous_id: 'anon_xyz789',
    timestamp: new Date().toISOString(),
    properties: {
      paywall_id: 'pw_annual_v3',
      offer_id: 'offer_intro_50pct',
      context: 'onboarding_step_3',
    },
  }),
});

const data = await response.json();
// { status: 'ok', event_id: 'evt_01hx...' }

Response

{
  "status": "ok",
  "event_id": "evt_01hx4j7k9m2n3p5q6r8s"
}

Request fields

string

required

Event name from the event taxonomy. E.g. paywall_viewed, subscription_started.

string

Your backend user identifier. Required if anonymous_id is not present.

string

Pre-login device or session identifier. Recommended for events that occur before a user account is created. FloKit links anonymous_id to user_id automatically when both appear together in any event.

string

required

ISO 8601 datetime of when the event occurred. Use the event’s actual occurrence time, not the time the request is sent.

object

Any additional event properties as key/value pairs. See the event taxonomy for recommended properties per event type.

Error responses

Status	Meaning
`200 OK`	Event accepted
`400 Bad Request`	Validation error — response body includes `error` and `message`
`401 Unauthorized`	Missing or invalid API key
`429 Too Many Requests`	Rate limit exceeded — see headers for retry-after

Idempotency

Include an Idempotency-Key header to safely retry requests without creating duplicate events. FloKit deduplicates on this key within a 24-hour window.

curl -X POST https://YOUR-FLOKIT-API-HOST/v1/events \
  -H "Authorization: Bearer $FLOKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: usr_abc123-subscription_started-2024-03-15" \
  -d '{
    "event": "subscription_started",
    "user_id": "usr_abc123",
    "timestamp": "2024-03-15T14:25:00Z",
    "properties": {
      "plan_id": "plan_annual_usd",
      "revenue": 49.99,
      "currency": "USD",
      "transaction_id": "txn_3OZ..."
    }
  }'

If a duplicate request is received within 24 hours, FloKit returns 200 OK with the original event_id — no duplicate is stored.

Event ordering

Send events in chronological order where possible. Out-of-order events are accepted and will be processed correctly, but funnel metrics may appear inconsistent for a brief period until FloKit’s event sorter catches up. For historical imports with large volumes of out-of-order events, use the batch endpoint and sort events by timestamp before sending.

Basic guides

Start here

Connect your stack

Connect an assistant

Send data

Use FloKit

Recipes

Examples

Server-side events

Authentication

Send a single event

Request fields

Error responses

Idempotency

Event ordering

​Authentication

​Send a single event

​Request fields

​Error responses

​Idempotency

​Event ordering

Authentication

Send a single event

Request fields

Error responses

Idempotency

Event ordering