API Overview

The BreakGround REST API provides programmatic access to manage flows, audiences, analytics, content, and SDK integration. All endpoints return JSON.

Base URL

All API requests are made to:

https://api.breakground.io/api

For local development, the API runs at http://localhost:3001/api. The dashboard dev server proxies /api requests to the API automatically.

Authentication

Requests must be authenticated using either:

• API keys (X-API-Key header) for SDK and server-to-server routes
• JWT tokens (HttpOnly session_token cookie or Authorization: Bearer header) for dashboard routes

See Authentication for details.

Response Format

Success

All successful responses wrap data in a data field:

{
  "data": {
    "tenantId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Organization"
  }
}

Paginated endpoints include a meta field:

{
  "data": [...],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}

Errors

All errors return a structured error object:

{
  "error": {
    "message": "Invalid request body",
    "statusCode": 400,
    "code": "VALIDATION_ERROR",
    "category": "VALIDATION",
    "details": [{ "path": "events.0.type", "message": "Invalid enum value" }]
  }
}

See Error Codes for the full list.

Rate Limits

Scope	Limit	Scoped by
Global (all routes)	100 requests/min	IP address
Auth routes (/api/auth/*)	10 requests/min	IP address
Token refresh (/api/auth/refresh)	20 requests/min	IP address
SDK routes (/api/sdk/*)	600 requests/min	API key
Admin read (/api/admin/* GET)	60 requests/min	Platform JWT
Admin write (/api/admin/* POST/PATCH)	20 requests/min	Platform JWT
Admin critical (kill switch, GDPR delete)	5 requests/min	Platform JWT

Rate-limited responses return HTTP 429 with a Retry-After header.

Request Headers

Header	Required	Description
Content-Type	Yes (POST/PUT/PATCH)	Must be application/json
X-API-Key	Yes (SDK routes)	API key for SDK authentication
Authorization	Yes (dashboard routes)	Bearer <jwt_token>

Route Prefixes

Prefix	Purpose	Auth method
/api/sdk/*	SDK integration endpoints	API key
/api/auth/*	Authentication (login, register, refresh)	None / JWT
/api/flows/*, /api/audiences/*, etc.	Dashboard CRUD	JWT
/api/admin/*	Platform administration	Platform JWT