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

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

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

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)

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

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
POST	/v1/otlp/traces, /v1/otlp/logs

Webhook payloads are signed: X-Backstory-Signature: t=<unix>,v1=<hex hmac-sha256(secret, "<t>.<body>")>. See Webhooks.

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).

AI

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

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)

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.