Screeb API

The Screeb API allows you to send events (identify, track, group, page, screen) directly from your backend, without relying on a client-side SDK.

This is useful for server-side integrations, data pipelines, or any scenario where you need to push user data to Screeb from your own infrastructure.

Authorization

All requests must be authenticated with a Bearer token. You can find your workspace API key in Screeb workspace settings under Data & Deployment → Screeb API.

Include it in the Authorization header of every request:

Authorization: Bearer <your_api_token>

Endpoint

POST https://api.screeb.app/1.0/event

The request body is a JSON array of event items (batch). You can send between 1 and 100 events per request.

Event types

Type	Description
identify	Set or update properties on a user
track	Track a custom event
group.assign	Assign a user to a group
group.unassign	Unassign a user from a group
page	Track a page view
screen	Track a screen view (mobile)

Request body

Each item in the array must contain at least type. Additional fields depend on the event type.

Common fields

Field	Type	Required	Description
user_alias	string	no	An alias to identify the user. If omitted, an anonymous user is created automatically server-side
type	string	yes	The event type (see table above)
properties	object	no	Key-value pairs attached to the event
context	object	no	Optional context (see below)

Context object

Field	Type	Description
locale	string	User locale (e.g. en-US)
timezone	string	User timezone (e.g. Europe/Paris)

Type-specific fields

identify

No additional required fields. Use properties to set user attributes.

track

Field	Type	Required	Description
event_name	string	yes	Name of the event

group.assign / group.unassign

Field	Type	Required	Description
group_type	string	no	Type/category of the group
group_name	string	yes	Name of the group

page

Field	Type	Required	Description
url	string	yes	The page URL

screen

Field	Type	Required	Description
screen_name	string	yes	The screen name

Response

On success the API returns a 200 status with:

{
  "count": 2,
  "lag": null
}

Field	Type	Description
count	number	Number of events processed
lag	number | null	Current ingestion lag in milliseconds (if available)

Examples

Identify a user

curl -X POST https://api.screeb.app/1.0/event \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer my_api_token" \
  -d '[
    {
      "user_alias": "user-123",
      "type": "identify",
      "properties": {
        "email": "jane@example.com",
        "plan": "pro",
        "signed_up_at": "2025-01-15T10:30:00Z"
      }
    }
  ]'

Track a custom event

curl -X POST https://api.screeb.app/1.0/event \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer my_api_token" \
  -d '[
    {
      "user_alias": "user-123",
      "type": "track",
      "event_name": "subscription_renewed",
      "properties": {
        "plan": "pro",
        "amount": 49.99
      }
    }
  ]'

Assign a user to a group

curl -X POST https://api.screeb.app/1.0/event \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer my_api_token" \
  -d '[
    {
      "user_alias": "user-123",
      "type": "group.assign",
      "group_type": "company",
      "group_name": "Acme Inc",
      "properties": {
        "industry": "SaaS",
        "employees": 150
      }
    }
  ]'

Send a batch of events

curl -X POST https://api.screeb.app/1.0/event \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer my_api_token" \
  -d '[
    {
      "user_alias": "user-123",
      "type": "identify",
      "properties": { "plan": "enterprise" }
    },
    {
      "user_alias": "user-123",
      "type": "track",
      "event_name": "plan_upgraded"
    },
    {
      "user_alias": "user-456",
      "type": "screen",
      "screen_name": "DashboardScreen"
    }
  ]'

Rate limiting

The /event endpoint is rate-limited to 50 requests per second per API token. If you exceed this limit, the API will respond with a 429 Too Many Requests status.

When you receive a 429 response, back off and retry after a short delay.

Error handling

Status	Description
200	Events processed successfully
400	Validation error (invalid payload, missing required fields)
401	Unauthorized — missing or invalid API token
429	Too many requests — rate limit exceeded
500	Server error

Support

If you have any questions or additional requirements, feel free to open an issue or contact support@screeb.app.