Batch API

The Batch API lets you send multiple events in a single HTTP request. This is the primary endpoint used by all Kixo SDKs, and you can call it directly for server-side event ingestion.

Endpoint

text

POST https://api.kixo.io/v1/batch

Headers

text

Content-Type: application/json

Request body

json

{
  "project_id": "kx_proj_...",
  "api_key": "kx_key_...",
  "bundle_id": "com.example.app",
  "platform": "ios",
  "environment": "production",
  "batch": [
    {
      "event_type": "screen_view",
      "event_name": "HomeScreen",
      "device_id": "...",
      "session_id": "...",
      "timestamp": "2026-04-08T12:00:00Z",
      "properties": {}
    }
  ],
  "sent_at": "2026-04-08T12:00:01Z"
}

Fields

Field	Type	Required	Description
`project_id`	string	Yes	Your Kixo project ID
`api_key`	string	Yes	Your Kixo API key
`bundle_id`	string	Yes	App bundle identifier (e.g. com.example.app)
`platform`	string	Yes	One of: ios, android, web
`environment`	string	No	production, staging, or development (default: production)
`batch`	array	Yes	Array of event objects
`sent_at`	string	No	ISO 8601 timestamp of when the batch was sent (used for clock drift correction)

Event object

Field	Type	Required	Description
`event_type`	string	Yes	Event type (e.g. screen_view, custom)
`event_name`	string	Yes	Human-readable event name
`device_id`	string	Yes	Unique device identifier
`session_id`	string	Yes	Session identifier
`timestamp`	string	Yes	ISO 8601 timestamp of the event
`properties`	object	No	Arbitrary key-value pairs

Response

On success, the API returns:

json

{
  "status": "ok",
  "accepted": 1
}

Rate limits

The Batch API supports up to 1,000 events per request and 100 requests per second per project. If you exceed these limits, the API returns a 429 Too Many Requests response.

Tip

For best performance, batch as many events as possible into a single request rather than sending events one at a time.

Example: cURL

bash

curl -X POST https://api.kixo.io/v1/batch \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "kx_proj_abc123",
    "api_key": "kx_key_xyz789",
    "bundle_id": "com.example.app",
    "platform": "web",
    "batch": [
      {
        "event_type": "page_view",
        "event_name": "/pricing",
        "device_id": "d_001",
        "session_id": "s_001",
        "timestamp": "2026-04-08T12:00:00Z",
        "properties": { "referrer": "https://google.com" }
      }
    ]
  }'