REST API

Ingest and platform endpoint reference

Service endpoints

Service	Base URL	Primary use
Ingest	`https://ingest.realanalytics.dev`	Event collection from SDK/clients
App API	`https://app.realanalytics.dev`	CLI/project management + dashboard queries

Event ingest

`POST /` on ingest service

Send events to https://ingest.realanalytics.dev with a public key.

curl -X POST https://ingest.realanalytics.dev \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_xxx" \
  -d '[
    {
      "event": "signup_completed",
      "timestamp": "2026-02-03T15:30:00.000Z",
      "distinctId": "user_123",
      "sessionId": "sess_abc",
      "properties": {
        "plan": "pro",
        "source": "pricing_page"
      }
    }
  ]'

Accepted payload shapes

Single event object
Array of events (max 100 per request)
Envelope: { apiKey, events } (used by Beacon flow)

Event schema (required fields)

Field	Type	Notes
`event`	string	1-100 chars
`timestamp`	ISO string	Must parse as valid date
`distinctId`	string	User/visitor identifier
`sessionId`	string	Session identifier
`properties`	object	Max 100 keys

Responses

// success
{ "success": true, "events": 1 }

// monthly plan limit reached
{
  "error": "Monthly event limit exceeded",
  "code": "EVENT_LIMIT_EXCEEDED",
  "limit": 10000,
  "used": 10000,
  "remaining": 0
}

// validation failure
{ "error": "Validation failed", "details": [...] }

// rate limit
{ "error": "Rate limit exceeded" }
// Retry-After: <seconds>

Rate limit

Ingest currently limits to 1000 requests per 60-second window per public key.

Dashboard query endpoint (app API)

`POST /api/query` on app service

Used by the dashboard app. Requires an authenticated app session and project membership.

POST https://app.realanalytics.dev/api/query
Content-Type: application/json
Cookie: <session cookies>

{
  "type": "timeseries",
  "projectId": "my-project-slug",
  "event": "$pageview",
  "dateRange": {
    "start": "2026-02-01T00:00:00.000Z",
    "end": "2026-02-03T23:59:59.999Z"
  },
  "metric": "count",
  "filter": {
    "key": "$pathname",
    "op": "eq",
    "value": "/pricing"
  }
}

Query types: timeseries, breakdown, metric,funnel.

CLI-related app endpoints

POST /api/cli/validate - exchange one-time CLI token for access token
POST /api/projects - create project (session auth or CLI bearer token)
POST /api/deploy - deploy compiled config (secret key + CLI/session auth)