Skip to main content
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://api.flokit.ai

​
Send a single event

curl -X POST https://api.flokit.ai/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"
    }
  }'
Response 
{
  "status": "ok",
  "event_id": "evt_01hx4j7k9m2n3p5q6r8s"
}

​
Request fields

​
event
string
required
Event name from the event taxonomy. E.g. paywall_viewed, subscription_started.
​
user_id
string
Your backend user identifier. Required if anonymous_id is not present.
​
anonymous_id
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.
​
timestamp
string
required
ISO 8601 datetime of when the event occurred. Use the event’s actual occurrence time, not the time the request is sent.
​
properties
object
Any additional event properties as key/value pairs. See the event taxonomy for recommended properties per event type.

​
Error responses

StatusMeaning
200 OKEvent accepted
400 Bad RequestValidation error — response body includes error and message
401 UnauthorizedMissing or invalid API key
429 Too Many RequestsRate 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://api.flokit.ai/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.