Skip to main content

​
POST /api/events

Receives batched events from the Solute SDK. This is the primary endpoint for event ingestion.

​
Request

​
Headers

​
Content-Type
string
required
application/json
​
X-Api-Key
string
required
Your API key

​
Body

​
batch
Array<Event>
required
Array of events to process. Each event has the following structure:
​
sentAt
string
required
ISO 8601 timestamp when the batch was sent

​
Event Object

​
type
'track' | 'identify' | 'page' | 'group' | 'alias'
required
Event type
​
timestamp
string
required
ISO 8601 timestamp
​
userId
string
User ID (if user is identified)
​
anonymousId
string
Anonymous ID
​
messageId
string
required
UUID for deduplication
​
context
object
required
Event context including page info, user agent, screen, locale, library, and session ID
​
event
string
Event name (for ‘track’ events)
​
properties
object
Event properties (for ‘track’ events)
​
traits
object
User traits (for ‘identify’ events)
​
name
string
Page name (for ‘page’ events)
​
category
string
Page category (for ‘page’ events)
​
groupId
string
Group ID (for ‘group’ events)
​
previousId
string
Previous user ID (for ‘alias’ events)

​
Example Request

curl -X POST https://api.solute.dev/api/events \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your_api_key" \
  -d '{
    "batch": [
      {
        "type": "track",
        "event": "Button Clicked",
        "properties": {
          "button_id": "cta-signup",
          "page": "/homepage"
        },
        "timestamp": "2025-01-15T10:30:00Z",
        "userId": "user_123",
        "anonymousId": "anon_456",
        "messageId": "msg_789",
        "context": {
          "page": {
            "path": "/homepage",
            "url": "https://example.com/homepage",
            "title": "Homepage"
          },
          "library": {
            "name": "@solute-ai/sdk",
            "version": "0.1.2"
          },
          "sessionId": "session_abc"
        }
      }
    ],
    "sentAt": "2025-01-15T10:30:05Z"
  }'

​
Response

​
Success Response

​
success
boolean
required
true if the request was successful
​
processed
number
required
Number of events successfully processed
​
failed
number
Number of events that failed to process
​
errors
Array<{ index: number; error: string }>
Array of errors for failed events

​
Example Response

{
  "success": true,
  "processed": 1,
  "failed": 0
}

​
Best Practices

Use the messageId field to deduplicate events. Store processed message IDs and reject duplicates.
Accept batches of up to 100 events. Process them asynchronously and return 200 immediately.
Validate event schemas before processing. Return validation errors for invalid events.
Process events asynchronously. Don’t block the response waiting for event processing to complete.

Feature Flags Endpoint

Identify Endpoint