Events API

The FloKit v1 REST API is in design-partner preview — endpoints and schemas may change before general availability. Contact your FloKit team for access.

POST /v1/events

Send a single event from your server.

Headers

Header	Value
`Authorization`	`Bearer $FLOKIT_API_KEY`
`Content-Type`	`application/json`
`Idempotency-Key`	(optional) Unique key for safe retries — deduplicated within 24 hours

Request body

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 the user has an account. FloKit links anonymous_id to user_id when both appear in the same event.

string

required

ISO 8601 datetime of when the event occurred. Use the actual event time, not the request time.

object

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

Examples

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",
    "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"
    }
  }'

curl -X POST https://YOUR-FLOKIT-API-HOST/v1/events \
  -H "Authorization: Bearer $FLOKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "subscription_started",
    "user_id": "usr_abc123",
    "timestamp": "2024-03-22T14:22:00Z",
    "properties": {
      "plan_id": "plan_annual_usd",
      "revenue": 49.99,
      "currency": "USD",
      "transaction_id": "txn_3OZ9kL2eZvKYlo2C0FL1nGdU",
      "trial_converted": true,
      "paywall_id": "pw_annual_v3",
      "store": "apple"
    }
  }'

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: 'subscription_started',
    user_id: 'usr_abc123',
    timestamp: new Date().toISOString(),
    properties: {
      plan_id: 'plan_annual_usd',
      revenue: 49.99,
      currency: 'USD',
      transaction_id: 'txn_3OZ9kL2eZvKYlo2C0FL1nGdU',
      trial_converted: true,
      paywall_id: 'pw_annual_v3',
      store: 'apple',
    },
  }),
});

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

Response

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

Error responses

Status	Description
`400 Bad Request`	Validation error — `error` and `message` fields in response body
`401 Unauthorized`	Missing or invalid API key
`429 Too Many Requests`	Rate limit exceeded — check `Retry-After` header

POST /v1/batch/events

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

Request body

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://YOUR-FLOKIT-API-HOST/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
        }
      }
    ]
  }'

const response = await fetch('https://YOUR-FLOKIT-API-HOST/v1/batch/events', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.FLOKIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    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 },
      },
    ],
  }),
});

const data = await response.json();

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

Limit	Value
Events per request	1,000
Requests per minute	100 per workspace

Contact FloKit for higher throughput capacity.

Live endpoints

API reference

POST /v1/events

Headers

Request body

Examples

Response

Error responses

POST /v1/batch/events

Request body

Example

Response

Rate limits

​POST /v1/events

​Headers

​Request body

​Examples

​Response

​Error responses

​POST /v1/batch/events

​Request body

​Example

​Response

​Rate limits

POST /v1/events

Headers

Request body

Examples

Response

Error responses

POST /v1/batch/events

Request body

Example

Response

Rate limits