REST API reference
Base URL: https://api.backstory.io (EU: https://api.eu.backstory.io; self-hosted: your api service). Authenticate with Authorization: Bearer <token> for API tokens, or the dashboard’s session cookie plus X-Backstory-CSRF and X-Backstory-Project headers. Errors return { error, code }. Lists return { items, nextCursor? }.
Type definitions for every request and response live in the @backstory/protocol package (packages/protocol/src/api-*.ts).
Health and configuration
Section titled “Health and configuration”| Method | Path | Notes |
|---|---|---|
| GET | /healthz, /readyz | Probes |
| GET | /v1/config?key=&sdk= | Public SDK remote config, cached 60 s |
| GET | /v1/projects/current | Project bound to the token |
Sessions and visits
Section titled “Sessions and visits”| Method | Path | Notes |
|---|---|---|
| GET | /v1/sessions?limit&cursor&q&hasErrors&browser&os&device&level&hasGaps&minDurationSec&maxDurationSec&from&to&user&urlContains&environment&release | Faceted list |
| GET | /v1/sessions/{id} | Detail with chunk manifest and gaps |
| GET | /v1/sessions/{id}/chunks/{seq} | Decompressed, decrypted chunk JSON |
| GET | /v1/sessions/{id}/events?types&limit | Flattened events |
| GET | /v1/sessions/{id}/issues | Signals in this session |
| GET | /v1/sessions/{id}/traces | Linked OpenTelemetry trace trees |
| GET | /v1/sessions/{id}/assets | Archived asset map |
| POST | /v1/sessions/{id}/share | Create a share link { expiresInHours } |
| POST | /v1/sessions/{id}/export | Start a video export |
| GET | /v1/visits/{id} | Segments of a visit |
| GET | /share/{token} | Public share (no auth) |
Insights
Section titled “Insights”| Method | Path |
|---|---|
| GET / PATCH | /v1/issues, /v1/issues/{clusterId}, /v1/issues/{clusterId}/sessions |
| GET | /v1/errors, /v1/errors/{fingerprint} (legacy fingerprint lookup; error triage is part of Issues) |
| GET | /v1/releases |
| GET | /v1/heatmaps?route&kind&breakpoint&from&to |
| GET / POST / PATCH / DELETE | /v1/funnels, /v1/funnels/{id}, /v1/funnels/{id}/results, /v1/funnels/suggestions (drafts from walked routes) |
| GET | /v1/dashboard/overview, /v1/vitals |
| POST / GET | /v1/sourcemaps (multipart upload), /v1/symbolicate |
Calls (WebRTC)
Section titled “Calls (WebRTC)”| Method | Path | Purpose |
|---|---|---|
| GET | /v1/calls | List calls with quality score, setup time, relay status, and issues. Filters: from, to, relayed, failedToConnect, networkType, minQuality, maxQuality, browser, os, device, release, endUser, hasIssue, cursor |
| GET | /v1/calls/{id} | One call with the full per-track metric series and event markers |
| GET | /v1/sessions/{id}/calls | Calls within a session (used by the Media panel) |
| GET | /v1/calls/overview | Connect failure rate, relay rate, setup percentiles, quality distribution, top failure reasons, and breakdowns by network, browser, device, and release |
Notifications
Section titled “Notifications”| Method | Path |
|---|---|
| GET / POST / PATCH / DELETE | /v1/notifications/rules |
| GET / POST / PATCH / DELETE | /v1/notifications/channels, /v1/notifications/channels/{id}/test |
| GET | /v1/notifications/deliveries, POST /v1/notifications/deliveries/{id}/replay |
| GET / POST | /v1/inbox, /v1/inbox/{id}/ack |
Webhook payloads are signed: X-Backstory-Signature: t=<unix>,v1=<hex hmac-sha256(secret, "<t>.<body>")>. See Webhooks.
Backend
Section titled “Backend”Every read takes environment and a time window: range=15m|1h|6h|24h|7d|30d (default 24h) or from and to in epoch milliseconds. Lists return { items, nextCursor? }.
| Method | Path | Notes |
|---|---|---|
| GET | /v1/backend/traces?service&route&status&minMs&linked&q&cursor&limit | Server requests, newest first. status=error|slow; linked=1 keeps requests with a replay |
| GET | /v1/backend/traces/{traceId} | Span tree, the trace’s logs, the linked session, and the services it crossed |
| GET | /v1/backend/logs?service&minSeverity&templateId&traceId&sessionId&q&cursor&limit | Log lines, newest first |
| GET | /v1/backend/logs/patterns?service&minSeverity | Log lines grouped by message template |
| GET | /v1/backend/metrics?service | Metric names with their type and unit |
| GET | /v1/backend/metrics/query?name&agg&service&groupBy | One metric over time, optionally split by an attribute |
| GET | /v1/backend/services, /v1/backend/services/{service}/routes | Request rate, error rate, and latency per service and route |
| GET | /v1/backend/map | Calls between services and to databases and queues |
| GET | /v1/backend/facets | Services and environments seen in the window |
| GET | /v1/backend/usage | This month’s backend GB for the organization, by day (with dropped data) and by project, against the plan |
| GET / PUT | /v1/projects/{projectId}/backend/settings | Capture level, severity floor, routes, headers, redaction, metrics, budget, cap |
| POST / DELETE | /v1/projects/{projectId}/backend/boost | Start a boost { service, minutes } (1 to 1440); DELETE ?service= ends it early |
| GET / POST | /v1/projects/{projectId}/backend/metric-rules | Metric alerts { name, metric, service, aggregation, comparator, threshold, windowMin, severity, enabled } |
| PUT / DELETE | /v1/projects/{projectId}/backend/metric-rules/{id} | Edit or delete a metric alert |
| GET / POST / DELETE | /v1/projects/{projectId}/server-keys, /v1/projects/{projectId}/server-keys/{id} | Server keys. The secret is returned once, on create |
Changing settings, metric alerts, and server keys takes an owner or admin. Starting or ending a boost takes write access.
Authentication and organizations
Section titled “Authentication and organizations”Public flows under /auth/*: signup, login, MFA verify, magic link, verify email, password forgot/reset, OAuth start/callback (google, microsoft, github), SSO start/ACS/callback/lookup, passkey login, invitation accept, logout.
Authenticated under /v1: me (profile, password, MFA, passkeys, sessions), orgs (settings, members, invitations, projects, tokens, audit, sso, domains, dsar, erasure), projects/{id} (settings, rotate key).
| Method | Path |
|---|---|
| GET | /v1/sessions/{id}/transcript, /v1/sessions/{id}/summary |
| POST | /v1/sessions/{id}/explain, /v1/sessions/{id}/repro, /v1/issues/{clusterId}/explain, /v1/issues/{clusterId}/draft-pr |
| GET | /v1/ai/jobs/{id} |
| POST | /v1/ai/chat (SSE), /v1/search, /v1/ai/feedback |
| GET | /v1/ai/digests, /v1/ai/usage, /v1/orgs/{orgId}/ai/settings |
| MCP | /mcp (Streamable HTTP) |
Billing
Section titled “Billing”GET /v1/orgs/{orgId}/usage, GET /v1/orgs/{orgId}/billing, POST …/billing/checkout, POST …/billing/portal, PATCH …/billing/caps, GET …/billing/invoices, GET /v1/license.
Ingest (SDK only)
Section titled “Ingest (SDK only)”POST /v1/ingest with X-Backstory-Project-Key, X-Backstory-Encoding: json+deflate, and a protocol-v1 chunk body. Acknowledged only after the chunk is durable in object storage. See the protocol document.
POST /v1/otlp/traces, /v1/otlp/logs, and /v1/otlp/metrics take standard OpenTelemetry (OTLP/HTTP) bodies, protobuf or JSON, plain or Content-Encoding: gzip. Authenticate with Authorization: Bearer sk_live_…. The browser key writes browser spans only. GET /v1/backend/config?service&environment returns the capture settings the backend SDKs poll.