API Reference

Complete reference for the Serla REST API. Ingest events, query analytics, and manage your projects programmatically.

Authentication

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

Authorization: Bearer YOUR_API_KEY

API keys are scoped to a single project. Create and manage keys in your project settings.

Security: Never expose API keys in client-side code. Use environment variables and make requests from your backend.

Base URL

https://api.serla.dev

Event Ingestion

POST /api/events/ingest

Track a new event.

Request Body

{
  "eventName": "button_click",
  "userId": "user_123",
  "sessionId": "sess_abc",
  "metadata": {
    "button": "signup",
    "page": "/pricing",
    "utm_source": "google",
    "utm_medium": "cpc"
  },
  "timestamp": "2025-12-05T10:30:00Z"
}

Parameters

eventName (required): Event name (max 255 chars)
userId (optional): User identifier
sessionId (optional): Session identifier
metadata (optional): Custom key-value pairs
timestamp (optional): ISO 8601 timestamp (defaults to server time)

Response

{
  "success": true,
  "data": {
    "eventId": "evt_abc123",
    "eventName": "button_click",
    "timestamp": "2025-12-05T10:30:00Z",
    "projectId": "proj_xyz"
  }
}

Status Codes

200 OK: Event tracked successfully
400 Bad Request: Invalid request body or missing required fields
401 Unauthorized: Invalid or missing API key
429 Too Many Requests: Rate limit exceeded

Stats & Analytics

GET /api/stats/overview

Get project overview statistics.

Query Parameters

projectId (required): Project ID

Response

{
  "project": {
    "id": "proj_xyz",
    "name": "My Website"
  },
  "stats": {
    "totalEvents": 125847,
    "eventsLast30Days": 42156,
    "eventsLast24Hours": 1523,
    "totalSessions": 8943,
    "uniqueVisitors": 6721,
    "bounceRate": 42.3,
    "totalEvents24hChange": 12.5
  }
}

GET /api/charts/timeseries

Get event time series data for charts.

Query Parameters

projectId (required): Project ID
startDate (optional): ISO 8601 start date
endDate (optional): ISO 8601 end date
interval (optional): hour, day, week, or month (default: day)
compare (optional): true or false (default: false)

Response

{
  "timeSeries": [
    { "date": "2025-12-01", "count": 1243 },
    { "date": "2025-12-02", "count": 1567 },
    { "date": "2025-12-03", "count": 1423 }
  ],
  "topEvents": [
    { "name": "page_view", "count": 5234 },
    { "name": "button_click", "count": 2156 }
  ],
  "comparison": {
    "previousTimeSeries": [...],
    "currentTotal": 15234,
    "previousTotal": 13456,
    "changePercentage": 13.2
  }
}

GET /api/analytics/languages

Get visitor language breakdown.

Query Parameters

projectId (required): Project ID
days (optional): Number of days (default: 30)

Response

{
  "languages": [
    { "language": "en-US", "count": 5432, "percentage": 54.3 },
    { "language": "es", "count": 2156, "percentage": 21.6 },
    { "language": "fr", "count": 1234, "percentage": 12.3 }
  ],
  "period": "30 days"
}

Goals

GET /api/goals

List all goals for a project.

Query Parameters

projectId (required): Project ID

Response

{
  "goals": [
    {
      "id": "goal_abc",
      "name": "Sign Up Completed",
      "type": "event",
      "targetEvent": "signup_completed",
      "value": 10.00,
      "enabled": true,
      "createdAt": "2025-12-01T..."
    }
  ]
}

POST /api/goals

Create a new goal.

Request Body

{
  "projectId": "proj_xyz",
  "name": "Sign Up Completed",
  "description": "User completes signup",
  "type": "event",
  "targetEvent": "signup_completed",
  "value": 10.00,
  "enabled": true
}

GET /api/goals/:id/stats

Get goal statistics.

Query Parameters

days (optional): Number of days (default: 30)

Response

{
  "goal": {
    "id": "goal_abc",
    "name": "Sign Up Completed"
  },
  "stats": {
    "conversions": 1247,
    "totalValue": 12470.00,
    "previousConversions": 1089,
    "changePercentage": 14.5,
    "period": "30 days"
  }
}

PATCH /api/goals/:id

Update a goal.

Request Body

{
  "enabled": false
}

DELETE /api/goals/:id

Delete a goal.

Segments

GET /api/segments

List all segments for a project.

Response

{
  "segments": [
    {
      "id": "seg_abc",
      "name": "US Mobile Users",
      "filters": [
        { "field": "country", "operator": "equals", "value": "US" },
        { "field": "device", "operator": "equals", "value": "mobile" }
      ],
      "createdAt": "2025-12-01T..."
    }
  ]
}

POST /api/segments

Create a new segment.

Request Body

{
  "projectId": "proj_xyz",
  "name": "US Mobile Users",
  "description": "Mobile users from the United States",
  "filters": [
    { "field": "country", "operator": "equals", "value": "US" },
    { "field": "device", "operator": "equals", "value": "mobile" }
  ]
}

DELETE /api/segments/:id

Delete a segment.

Cohorts & Retention

GET /api/cohorts

List all cohorts for a project.

POST /api/cohorts

Create a new cohort.

Request Body

{
  "projectId": "proj_xyz",
  "name": "December 2025 Signups",
  "eventName": "signup",
  "startDate": "2025-12-01T00:00:00Z",
  "endDate": "2025-12-31T23:59:59Z",
  "granularity": "week"
}

GET /api/cohorts/:id/retention

Get retention data for a cohort.

Response

{
  "cohort": {
    "id": "cohort_abc",
    "name": "December 2025 Signups",
    "size": 1247,
    "granularity": "week"
  },
  "retention": [
    { "period": 0, "returned": 1247, "percentage": 100.00 },
    { "period": 1, "returned": 564, "percentage": 45.23 },
    { "period": 2, "returned": 387, "percentage": 31.04 }
  ]
}

Journey Mapping

GET /api/analytics/journey

Get user journey path data.

Query Parameters

projectId (required): Project ID
days (optional): Number of days (default: 7)
limit (optional): Max paths to return (default: 50)

Response

{
  "totalSessions": 12453,
  "paths": [
    {
      "path": "page_view → signup_click → signup_completed",
      "count": 1247,
      "percentage": 10.01
    }
  ],
  "period": "7 days"
}

Attribution

GET /api/analytics/attribution

Get multi-touch attribution data.

Query Parameters

projectId (required): Project ID
model (optional): first-touch, last-touch, linear, or time-decay (default: last-touch)
days (optional): Number of days (default: 30)

Response

{
  "model": "time-decay",
  "period": "30 days",
  "totalRevenue": 24850.50,
  "totalConversions": 347.25,
  "attribution": [
    {
      "source": "google / cpc",
      "revenue": 12400.00,
      "conversions": 156.5
    }
  ]
}

Data Export

GET /api/events/export

Export events to CSV.

Query Parameters

projectId (required): Project ID
startDate (optional): ISO 8601 start date
endDate (optional): ISO 8601 end date

Response

CSV file download with columns: id, eventName, userId, sessionId, metadata, revenueAmount, revenueCurrency, language, timestamp, createdAt

Rate Limits

Event Ingestion: 1000 requests/minute per project
Analytics APIs: 100 requests/minute per project
Management APIs: 60 requests/minute per user

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1733400000

Error Responses

400 Bad Request

{
  "error": "Validation failed",
  "details": {
    "eventName": "Event name is required"
  }
}

401 Unauthorized

{
  "error": "Invalid or missing API key"
}

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "retryAfter": 42
}

500 Internal Server Error

{
  "error": "Internal server error",
  "message": "An unexpected error occurred"
}

Webhooks

For webhook documentation, see the Webhooks Guide.

SDKs

Official SDKs coming soon:

JavaScript/TypeScript
Python
Ruby
PHP
Go