Screeb API

The Screeb API allows you to send events (identify, track, group, page, screen, copilot) 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)
`copilot`	Track a Screeb Copilot interaction

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

`copilot`

Used to track interactions with a Screeb Copilot agent. The event_name field determines the specific interaction being recorded.

Field	Type	Required	Description
`event_name`	`string`	yes	One of `screeb_copilot_user_prompt`, `screeb_copilot_response`, `screeb_copilot_conversion`, `screeb_copilot_satisfaction`
`conversation_id`	`string`	yes (except when `event_name` is `screeb_copilot_conversion`)	Unique identifier for the conversation (max 100 chars)
`copilot_session_id`	`string`	yes (except when `event_name` is `screeb_copilot_conversion`)	Unique identifier for the copilot session (max 100 chars)
`prompt`	`string`	yes (when `event_name` is `screeb_copilot_user_prompt`)	The user's prompt text (max 10 000 chars)
`response`	`string`	yes (when `event_name` is `screeb_copilot_response`)	The copilot's response text (max 10 000 chars)
`rating`	`string`	yes (when `event_name` is `screeb_copilot_satisfaction`)	The satisfaction rating value
`rating_scale`	`string`	yes (when `event_name` is `screeb_copilot_satisfaction`)	The scale used for the rating

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": "support@screeb.app",
        "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
      }
    }
  ]'

Track a Copilot interaction

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": "copilot",
      "event_name": "screeb_copilot_user_prompt",
      "conversation_id": "conv-abc-123",
      "copilot_session_id": "session-xyz-456",
      "prompt": "How do I reset my password?"
    },
    {
      "user_alias": "user-123",
      "type": "copilot",
      "event_name": "screeb_copilot_response",
      "conversation_id": "conv-abc-123",
      "copilot_session_id": "session-xyz-456",
      "response": "You can reset your password from the settings page."
    },
    {
      "user_alias": "user-123",
      "type": "copilot",
      "event_name": "screeb_copilot_conversion"
    },
    {
      "user_alias": "user-123",
      "type": "copilot",
      "event_name": "screeb_copilot_satisfaction",
      "conversation_id": "conv-abc-123",
      "copilot_session_id": "session-xyz-456",
      "rating": "5",
      "rating_scale": "10"
    }
  ]'

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

Releases API

You can integrate the creation of your releases into your current workflow using the Releases API.

Authorization

To push a new release to your organization, you will need an API Token generated for you. You can find it on the release create form, next to the Submit button.

Endpoint

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

The released_at field is optional and will default to the current date.

Example

curl -X POST https://api.screeb.app/1.0/release \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer my_api_token" \
    -d '{
        "name": "My release name",
        "description": "My release description",
        "version": "1.0",
        "tags": ["API", "V1"],
        "released_at": "2023-03-22T15:22:41+00:00"
    }'

Support

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

Authorization​

Endpoint​

Event types​

Request body​

Common fields​

Context object​

Type-specific fields​

identify​

track​

group.assign / group.unassign​

page​

screen​

copilot​

Response​

Examples​

Identify a user​

Track a custom event​

Assign a user to a group​

Track a Copilot interaction​

Send a batch of events​

Rate limiting​

Error handling​

Releases API​

Authorization​

Endpoint​

Example​

Support​

Authorization

Endpoint

Event types

Request body

Common fields

Context object

Type-specific fields

`identify`

`track`

`group.assign` / `group.unassign`

`page`

`screen`

`copilot`

Response

Examples

Identify a user

Track a custom event

Assign a user to a group

Track a Copilot interaction

Send a batch of events

Rate limiting

Error handling

Releases API

Authorization

Endpoint

Example

Support