API Reference

Complete reference for the Serla REST API.

Authentication

All API requests require authentication using an API key. Include your key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Base URL

https://serla.dev/api

Endpoints

POST/events/ingest

Track a custom event.

Request Body

{
  "eventName": "button_click",        // Required: Event name
  "userId": "user_123",               // Optional: User identifier
  "sessionId": "sess_abc",            // Optional: Session identifier
  "metadata": {                       // Optional: Custom JSON data
    "button": "signup",
    "page": "/pricing"
  },
  "timestamp": "2025-12-03T10:00:00Z" // Optional: ISO 8601 timestamp
}

Response

{
  "success": true,
  "data": {
    "eventId": "clx123abc...",
    "eventName": "button_click",
    "timestamp": "2025-12-03T10:00:00.000Z",
    "projectId": "clx456def..."
  }
}

// Response Headers:
// X-RateLimit-Limit: 100
// X-RateLimit-Remaining: 99
// X-RateLimit-Reset: 1733234567

Example Request

curl -X POST https://serla.dev/api/events/ingest \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "eventName": "purchase_completed",
    "userId": "user_456",
    "metadata": {
      "amount": 49.99,
      "currency": "USD",
      "items": ["item_1", "item_2"]
    }
  }'

GET/events/get

Retrieve events by ID, user, session, or event name.

Query Parameters

event_idGet a specific event by ID

user_idGet all events for a user

session_idGet all events in a session

event_nameFilter by event type

fromStart date (ISO 8601)

toEnd date (ISO 8601)

limitMax results (default: 100, max: 1000)

At least one filter parameter is required: event_id, user_id, session_id, or event_name

Response

{
  "success": true,
  "data": [
    {
      "event_id": "clx123abc...",
      "event_name": "button_click",
      "user_id": "user_123",
      "session_id": "sess_xyz",
      "metadata": {
        "button": "checkout",
        "page": "product"
      },
      "user_agent": "Mozilla/5.0 ...",
      "ip_address": "192.168.1.1",
      "timestamp": "2025-12-05T10:30:00.000Z",
      "created_at": "2025-12-05T10:30:01.123Z",
      "revenue": {
        "amount": 99.99,
        "currency": "USD"
      }
    }
  ],
  "count": 1,
  "limit": 100
}

Example Request

# Get events by user ID
curl -X GET "https://serla.dev/api/events/get?user_id=user_123&limit=10" \
  -H "Authorization: Bearer sk_live_abc123..."

# Get specific event by ID
curl -X GET "https://serla.dev/api/events/get?event_id=clx123abc" \
  -H "Authorization: Bearer sk_live_abc123..."

Error Codes

Code	Description
200	Request successful
400	Invalid request body or validation error
401	Missing or invalid API key
429	Rate limit exceeded (100 req/min) or usage limit exceeded for your tier
500	Internal server error

Rate Limits

Request Rate Limit

All API keys are limited to 100 requests per minute. Rate limit headers are included in every response:

•X-RateLimit-Limit - Maximum requests per minute
•X-RateLimit-Remaining - Remaining requests in current window
•X-RateLimit-Reset - Unix timestamp when the limit resets

Monthly Usage Limits

Usage limits vary by subscription tier:

•Free: 25,000 events/month
•Hobby: 500,000 events/month
•Pro: 2,500,000 events/month
•Max: Unlimited events