Skip to content
You are reading the docs for Backstory 0.2 (private beta). Behavior may change before general availability; the changelog lists every change.

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

MethodPathNotes
GET/healthz, /readyzProbes
GET/v1/config?key=&sdk=Public SDK remote config, cached 60 s
GET/v1/projects/currentProject bound to the token
MethodPathNotes
GET/v1/sessions?limit&cursor&q&hasErrors&browser&os&device&level&hasGaps&minDurationSec&maxDurationSec&from&to&user&urlContains&environment&releaseFaceted 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&limitFlattened events
GET/v1/sessions/{id}/issuesSignals in this session
GET/v1/sessions/{id}/tracesLinked OpenTelemetry trace trees
GET/v1/sessions/{id}/assetsArchived asset map
POST/v1/sessions/{id}/shareCreate a share link { expiresInHours }
POST/v1/sessions/{id}/exportStart a video export
GET/v1/visits/{id}Segments of a visit
GET/share/{token}Public share (no auth)
MethodPath
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
MethodPathPurpose
GET/v1/callsList 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}/callsCalls within a session (used by the Media panel)
GET/v1/calls/overviewConnect failure rate, relay rate, setup percentiles, quality distribution, top failure reasons, and breakdowns by network, browser, device, and release
MethodPath
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.

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? }.

MethodPathNotes
GET/v1/backend/traces?service&route&status&minMs&linked&q&cursor&limitServer 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&limitLog lines, newest first
GET/v1/backend/logs/patterns?service&minSeverityLog lines grouped by message template
GET/v1/backend/metrics?serviceMetric names with their type and unit
GET/v1/backend/metrics/query?name&agg&service&groupByOne metric over time, optionally split by an attribute
GET/v1/backend/services, /v1/backend/services/{service}/routesRequest rate, error rate, and latency per service and route
GET/v1/backend/mapCalls between services and to databases and queues
GET/v1/backend/facetsServices and environments seen in the window
GET/v1/backend/usageThis month’s backend GB for the organization, by day (with dropped data) and by project, against the plan
GET / PUT/v1/projects/{projectId}/backend/settingsCapture level, severity floor, routes, headers, redaction, metrics, budget, cap
POST / DELETE/v1/projects/{projectId}/backend/boostStart a boost { service, minutes } (1 to 1440); DELETE ?service= ends it early
GET / POST/v1/projects/{projectId}/backend/metric-rulesMetric 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.

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

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

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.

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.