Skip to main content

​
POST /v1/events

Send a single event from your server.

​
Headers

HeaderValue
AuthorizationBearer $FLOKIT_API_KEY
Content-Typeapplication/json
Idempotency-Key(optional) Unique key for safe retries — deduplicated within 24 hours

​
Request body

​
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 the user has an account. FloKit links anonymous_id to user_id when both appear in the same event.
​
timestamp
string
required
ISO 8601 datetime of when the event occurred. Use the actual event time, not the request time.
​
properties
object
Additional event properties as key/value pairs. See the event taxonomy for recommended properties per event type.

​
Examples

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",
    "timestamp": "2024-03-15T14:22:00Z",
    "properties": {
      "paywall_id": "pw_annual_v3",
      "offer_id": "offer_intro_50pct",
      "plan_ids": ["plan_annual_usd", "plan_monthly_usd"],
      "context": "onboarding_step_3"
    }
  }'

​
Response

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

​
Error responses

StatusDescription
400 Bad RequestValidation error — error and message fields in response body
401 UnauthorizedMissing or invalid API key
429 Too Many RequestsRate limit exceeded — check Retry-After header

​
POST /v1/batch/events

Send up to 1,000 events in a single request.

​
Request body

​
events
array
required
Array of event objects. Each object accepts the same fields as the single-event endpoint: event, user_id, anonymous_id, timestamp, properties.

​
Example

curl -X POST https://api.flokit.ai/v1/batch/events \
  -H "Authorization: Bearer $FLOKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event": "paywall_viewed",
        "user_id": "usr_abc123",
        "timestamp": "2024-03-15T14:20:00Z",
        "properties": {
          "paywall_id": "pw_annual_v3",
          "context": "onboarding_step_3"
        }
      },
      {
        "event": "trial_started",
        "user_id": "usr_abc123",
        "timestamp": "2024-03-15T14:22:00Z",
        "properties": {
          "plan_id": "plan_annual_usd",
          "trial_length_days": 7
        }
      }
    ]
  }'

​
Response

{
  "status": "ok",
  "accepted": 2,
  "rejected": 0,
  "event_ids": [
    "evt_01hx4j7k9m2n3p5q6r8s",
    "evt_01hx4j7k9m2n3p5q6r9t"
  ],
  "errors": []
}
If some events fail validation, accepted events are still processed. Rejected events appear in errors with the array index and reason.

​
Rate limits

LimitValue
Events per request1,000
Requests per minute100 per workspace
Contact FloKit for higher throughput capacity.