REST API
Base URL: https://api.backstory.io (self-hosted: your api service). Authentication: Authorization: Bearer <token> for API tokens; browser sessions use the backstory_session cookie plus X-Backstory-CSRF on state-changing requests. Types are published in @backstory/protocol.
Sessions and replay data
Section titled “Sessions and replay data”| Method | Path | Returns |
|---|---|---|
| GET | /v1/projects/current | Project |
| GET | /v1/sessions?limit&cursor&q&hasErrors | Page of SessionSummary |
| GET | /v1/sessions/{id} | SessionDetail (chunks, gaps) |
| GET | /v1/sessions/{id}/chunks/{seq} | Chunk (JSON) |
| GET | /v1/sessions/{id}/events?types&limit | Page of FlatEvent |
| GET | /v1/visits/{id} | VisitDetail |
| GET | /v1/config?key= | SDK remote configuration (public) |
| POST | /v1/ingest | SDK chunk ingest (gateway) |
Authentication
Section titled “Authentication”POST /auth/signup, POST /auth/login, POST /auth/mfa/verify, POST /auth/magic-link, POST /auth/verify-email, POST /auth/password/forgot|reset, GET /auth/oauth/{provider}/start|callback, GET /auth/sso/{connectionId}/start, POST /auth/sso/{connectionId}/acs, GET /auth/sso/lookup?email=, POST /auth/passkeys/login/options|verify, POST /auth/logout, POST /auth/invitations/{token}/accept.
Account and organizations
Section titled “Account and organizations”GET|PATCH /v1/me, /v1/me/password, /v1/me/mfa/*, /v1/me/passkeys/*, /v1/me/sessions, GET|POST /v1/orgs, /v1/orgs/{orgId} (settings), /members, /invitations, /projects, /tokens, /audit, /sso, /domains, /dsar, /erasure. Full field-level types: packages/protocol/src/api-auth.ts.
Errors
Section titled “Errors”{ "error": "human readable", "code": "unauthorized | not_found | invalid | internal" }Wire protocol
Section titled “Wire protocol”The SDK-to-gateway protocol (chunks, sequence numbers, acknowledgements, credits, clock sync) is documented in the repository at docs/PROTOCOL.md.