Driftstack DRIFTSTACK docs
Docs

API reference

This page lists every request you can send Driftstack over the web — in API terms, every endpoint. The Driftstack HTTP API surface lives at https://api.driftstack.dev. Every endpoint is versioned under /v1/*; new majors land with explicit deprecation cycles per the policy below.

What's here

  • Authentication flows — sign up, log in, verify email, MFA challenge + step-up, magic link, password reset, refresh, logout. The customer-dashboard surface; distinct from API-key bearer auth.
  • Account — /v1/account/me read + edit (name, timezone, slug, region, avatar). Team-RBAC interaction notes.
  • API keys — create, list, rotate (24-hour grace), revoke. Scopes table.
  • Sessions — create, navigate, interact, capture, wait, destroy. Session lifecycle + concurrency caps.
  • Agent sessions — AI-driven chat-style automation, manual pass-through mode, and pair-mode interactive takeover/handback state machine. The v2-#8 surface; complements regular driver sessions.
  • Recipes — snapshot a finished agent-session's intent_log + transcript as a replayable recipe. Create / list / read / delete ship at v1.0; only execute (replay) lands at v1.1.
  • Bundled LLM — opt-in consent, monthly soft cap, used / remaining / refused state for the no-BYOK agent decomposer rail.
  • BYOK Anthropic key — bring-your-own key management: set, rotate, clear, test. Encrypted at rest; never echoed in responses.
  • Profiles — persistent identity slots; create, list, get, patch, clone, delete. Snapshots — capture / list / restore / delete.
  • Account proxies — register your own SOCKS5 proxies; route a session's egress through one. Passwords encrypted at rest, never echoed.
  • Usage — current-period meter for sessions / api-calls / data transfer with tier caps surfaced.
  • Audit log — every account-level action with payload + filters + paginated read.
  • Two-factor authentication — TOTP enrol / verify / disable + recovery codes; step-up gate semantics.
  • Billing — subscriptions, Stripe Customer Portal redirect, billing-state read.
  • Team RBAC — invite + accept + list + remove for multi-user teams. Shipped at v1.0.
  • Status page API — public snapshot, incident feed (REST + SSE), 30-day SLA report, and double-opt-in email subscription. Unauthenticated; CDN-coalesced.
  • OAuth 2.0 (third-party clients) — Authorization-code + PKCE flow so third-party apps can act on a customer's behalf without holding the customer's API key. Register, authorize, exchange, introspect, revoke.
  • Versioning policy — additive vs breaking changes, deprecation cycle, when /v2/* is justified.
  • Webhook endpoints — register, list, update, delete, and test webhook endpoints; rotate signing secrets with a 24-hour dual-signing grace.
  • Webhook events catalog — every event type Driftstack emits, payload shape, signature verification, retry policy.
  • Replaying deliveries — customer self-service replay for failed and DLQ webhook deliveries.

Practical use

Other reference surfaces

  • OpenAPI spec. Live at https://api.driftstack.dev/openapi.json; rendered via Scalar UI on the API host at /docs/. The spec is the contract for SDK consumers; a deliberately committed copy lives in the repository for SDK regeneration.
  • Authentication. Bearer API keys (ds_live_… for production, ds_test_… for the free tier). Web sessions on the customer dashboard use opaque sha256-hashed tokens; Bearer header in both cases.
  • Rate limits. Per-tier token-bucket policy. Response headers include x-ratelimit-remaining; 429 responses include retry-after. IP-based gates also apply on unauthenticated auth endpoints (signup / login / verify-email / password-reset).