REST API Reference

The sessionvision REST API provides programmatic access to your analytics data. All endpoints are under https://app.sessionvision.com/api/v1/.

Authentication

Authenticate with either session cookies (from the web app) or API tokens for programmatic access. Include your API token in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://app.sessionvision.com/api/v1/projects/:project_id/events

Pagination

All list endpoints use cursor-based (keyset) pagination:

{
  "data": [...],
  "meta": {
    "next_cursor": "eyJ0cyI6...",
    "has_more": true
  }
}

Pass the next_cursor value as a cursor query parameter to get the next page.

Ingest

POST /api/v1/ingest/events

Accepts batched events from the SDK. Validates events and enqueues them for processing.

// Request
POST /api/v1/ingest/events
Content-Type: application/json

{
  "projectToken": "sv_pub_...",
  "events": [
    {
      "event": "$pageview",
      "timestamp": 1709856000000,
      "properties": { "$current_url": "https://example.com" },
      "anonymousId": "550e8400-...",
      "userId": null,
      "sessionId": "a1b2c3d4-..."
    }
  ]
}

// Response
{
  "status": "accepted",
  "accepted": 1,
  "rejected": 0,
  "errors": []
}

POST /api/v1/ingest/recordings

Returns a presigned URL for direct upload of recording chunks to object storage.

Persons

All person endpoints are under /api/v1/projects/:project_id/persons.

Method	Path	Description
`GET`	`/persons`	`List persons (supports limit, cursor, search, country, device_type, browser, has_user_id filters)`
`GET`	`/persons/:distinct_id`	`Get a single person`
`GET`	`/persons/:distinct_id/events`	`List events for a person`
`GET`	`/persons/:distinct_id/sessions`	`List sessions for a person`

Events

Method	Path	Description
`GET`	`/events`	`List events (supports limit, cursor, date_from, date_to, event, distinct_id, session_id filters)`
`GET`	`/events/:event_id`	`Get a single event`

Sessions

Method	Path	Description
`GET`	`/sessions`	`List sessions (supports limit, cursor, date_from, date_to, distinct_id, min/max_duration, is_bounce, entry_url, country, device_type, browser filters)`
`GET`	`/sessions/:session_id`	`Get a single session`
`GET`	`/sessions/:session_id/events`	`List events within a session`

Insights

POST /insights/trends

Time-series analysis with breakdowns.

POST /api/v1/projects/:project_id/insights/trends
Content-Type: application/json

{
  "events": [
    { "name": "$pageview", "math": "unique_persons" }
  ],
  "interval": "day",
  "date_from": "2025-01-01",
  "date_to": "2025-01-31",
  "breakdown": "$browser"
}

Param	Type	Description
`events`	`array (1-10)`	`Events to analyze`
`events[].name`	`string`	`Event name`
`events[].math`	`string`	`total, unique_persons, unique_sessions, per_session`
`interval`	`string`	`hour, day, week, month`
`breakdown`	`string`	`Property to break down by`
`date_from`	`string`	`Start date (ISO 8601)`
`date_to`	`string`	`End date (ISO 8601)`

POST /insights/funnel

Multi-step conversion funnel analysis. Uses ClickHouse windowFunnel() for accurate conversion tracking.

POST /api/v1/projects/:project_id/insights/funnel
Content-Type: application/json

{
  "steps": [
    { "event": "$pageview", "properties": { "$current_url": "/pricing" } },
    { "event": "checkout_started" },
    { "event": "purchase_completed" }
  ],
  "conversion_window": "7d",
  "date_from": "2025-01-01",
  "date_to": "2025-01-31"
}

Event & Property Definitions

Method	Path	Description
`GET`	`/event_definitions`	`Distinct event names with volume_30d and last_seen`
`GET`	`/property_definitions`	`Property keys with inferred types and example values`

Smart Events

Method	Path	Description
`GET`	`/action_definitions`	`List smart events (excludes archived by default)`
`GET`	`/action_definitions/:id`	`Get a single smart event`
`POST`	`/action_definitions`	`Create a smart event`
`PATCH`	`/action_definitions/:id`	`Update a smart event`
`DELETE`	`/action_definitions/:id`	`Delete a smart event`
`POST`	`/action_definitions/:id/preview`	`Preview matching events`

Error Codes

Status	Code	Description
`400`	`INVALID_PARAMETER`	`Invalid or missing request parameter`
`401`	`NOT_AUTHENTICATED`	`Missing or invalid authentication`
`403`	`NOT_AUTHORIZED`	`Insufficient permissions`
`404`	`NOT_FOUND`	`Resource not found`
`422`	`VALIDATION_ERROR`	`Request validation failed`

Error responses follow this format:

{
  "error": "Description of what went wrong",
  "code": "INVALID_PARAMETER"
}