API changelog

This page summarises customer-facing API changes by month. Backward-compatible additions appear without ceremony; the Breaking tag flags anything that requires a caller to update before the documented sunset date.

2026-05

• API — Recipe library read & management endpoints. The recipe library gains its read/management path: GET /v1/recipes (cursor-paginated list, newest first), GET /v1/recipes/{id} (a single recipe in full, including the replayable intent_log), and DELETE /v1/recipes/{id} (204 No Content; not idempotent). Joins the existing POST /v1/recipes capture endpoint, and ships across the TypeScript / Python / Go SDKs (recipes.list / .get / .delete) plus a new Recipes page in the customer dashboard. Backward-compatible — all additive. Recipe execution (replay against a new agent-session) remains on the v1.1 roadmap. Full reference at /api/recipes.
• API — Live video for agent sessions (LiveKit WebRTC). New POST /v1/agent-sessions/{id}/livekit-token endpoint mints a per-Mac LiveKit JWT for WebRTC subscribers (the customer dashboard, the desktop GUI client, or any other LiveKit-aware tool). POST /v1/agent-sessions now also auto-populates a livekit field on the 201 response when the deployment is LiveKit-ready, so clients can skip the round-trip and connect to the room immediately on create. Token TTL is 24h; the room name is always the agent_session id. Backward-compatible — the field is optional; older SDKs ignore it. Full reference at /api/agent-sessions and integration guide at /guides/live-video.
• API — Mac-node LiveKit credential registration. New POST /v1/mac-nodes/register admin endpoint accepts per-Mac LiveKit API credentials on harness boot. The API secret is encrypted at rest under the existing MFA_ENCRYPTION_KEY (same envelope as BYOK Anthropic + gui_control_key + MFA TOTP); plaintext is decrypted in-memory only at JWT-mint time. Every successful registration writes a mac_node.livekit_registered row to the admin audit log attributing the operator + recording the mac_node_id + ws_url — the audit payload deliberately omits the api_key + api_secret so secret material never leaks via audit replay.
• SDKs — LiveKitInfo type across TS / Python / Go. New typed shape carries ws_url + room + token + participant_identity + expires_at. Used on the new /livekit-token response AND the optional livekit field on session-create — one type, two consumption surfaces. AgentSession.livekit field is optional so older SDKs parse the response unchanged.
• Auth — derivation paths match dashboard routes. : the DASHBOARD_ORIGIN-derived defaults now land on the customer-dashboard's real file-based routes (/verify-email, /reset-password) instead of the previous /auth/<flow> paths that 404'd. Sister fix to
• Dashboard — auto-verify on the verify-email page. B: when the user clicks the verification link in their email, the dashboard now reads ?token=… from the URL and submits it automatically — previously the user was asked to copy + paste the token they'd just clicked. The form stays mounted as a fallback (token absent / mail client mangled the link).
• Server — runtime URLs centralized on DASHBOARD_ORIGIN. : lifecycle emails, team-invite emails, and Stripe success/cancel/portal defaults now all source from config.dashboardOrigin. Removes scattered https://app.driftstack.dev literals + the legacy PUBLIC_DASHBOARD_URL env var.
• Docs — Emails reference page. New /docs/emails-reference listing every template Driftstack sends (verify, magic-link, password-reset, payment receipt/failure, status notifications, weekly digest), each tagged transactional vs notification, with the API endpoints for preference management.
• Auth — DASHBOARD_ORIGIN now drives email link URLs. : a single DASHBOARD_ORIGIN env var derives the three auth-flow email URLs (verify-email, magic-link, password-reset). Production boot now refuses to start if any URL still resolves to localhost — fixes the case where a real customer received a verification email with a localhost link.
• Docs — API security headers reference. New page at /docs/api-security-headers listing the HSTS, Cache-Control, CORS, CORP, and helmet defaults we set. Useful for security reviewers and integrators auditing the response surface.
• GUI — Reset filters button. Both the customer history view and admin orders view now show a "Reset filters" button when any filter is active. Clicking clears every active filter in one go.
• GUI — problem+json detail across all crypto hooks. Extended the 4xx detail surfacing to all customer + admin-crypto hooks (15 total). Removed the inline detail- parsing code from useCancelOrder + useAdminInternalNote in favour of the shared helper.
• GUI — surface server problem+json detail on 4xx. Customer-facing hooks now read the RFC 7807 detail field from 4xx responses, so the user sees the server-provided message instead of just "HTTP 400". Wired into the order list + PDF / .txt receipt download hooks.
• API — date-window validation. An inverted window (created_before <= created_after) now returns 400 instead of silently returning an empty list. Catches the common swapped-args bug.
• GUI — customer date-range filter UI. The customer history view now has From/To date inputs next to the existing status dropdown. Wires directly into the server created_after / created_before query params.
• GUI — Load more on customer history view. The customer history view now exposes the server's next_cursor as a "Load more" button at the bottom of the table. Auto-refresh pauses once the user loads beyond the first page so appended rows don't get clobbered.
• API — admin CSV export accepts date range. GET /v1/admin/crypto-orders.csv now respects created_after / created_before. The admin GUI's CSV button automatically picks up the date inputs from the orders view.
• GUI — admin date-range filter UI. The admin orders view now has From/To date inputs next to the existing status / search / payment-id filters. Wires directly into the new server created_after / created_before query params.
• API — date-range filter on admin order list. GET /v1/admin/crypto-orders now accepts the same created_after / created_before ISO 8601 window. Combine with status and cursor to scope reconciliation scans.
• API — date-range filter on customer order list. GET /v1/billing/crypto-orders now accepts ?created_after= (inclusive) and ?created_before= (exclusive), both ISO 8601 timestamps. Composes with status and cursor for backfill scans. The SDK exposes the same fields on list() / listAll().
• Security — /v1/billing/* no-store. Promotes the no-store header to cover all of /v1/billing/* (billing state, crypto checkout, order envelopes, receipts, etc.). Defense-in-depth so a future endpoint can't accidentally omit it.
• Docs — polling vs webhooks for crypto orders. New page at /docs/crypto-orders-polling-vs-webhooks covering when to use each, recommended hybrid pattern, and cadence guidance. Closes a frequently-asked integrator question.
• SDK — cryptoOrders.listAll() iterator. Async generator that walks every page until next_cursor is null. Accepts the same options as list() minus cursor; callers can break early.
• API — customer order list cursor pagination. GET /v1/billing/crypto-orders now returns a next_cursor alongside orders and accepts a ?cursor= query param. Mirrors the admin endpoint. The SDK's client.cryptoOrders.list() accepts the new cursor option; loop until response.next_cursor is null.
• api-types — ListCryptoOrdersQuery exported. @driftstack/api-types now ships a Zod schema + type for the customer list query, mirroring the server's accepted parameters. The TypeScript SDK reuses it so its list() options stay in lockstep with the server-side enum.
• GUI — auto-refresh history view on pending. The customer history view now polls GET /v1/billing/crypto-orders every 60s while any visible order is still pending. Polling stops as soon as everything settles so stale tabs don't keep hitting the API.
• Security — /v1/admin/* no-store (broadened). The existing no-store header on /v1/admin/crypto-orders was promoted to an app-level hook covering all /v1/admin/* responses (accounts, audit, sessions, webhooks, etc.). Admin data is operational and caller-private — no caching anywhere.
• Security — /v1/account/* no-store. Every response under /v1/account/* (profile, audit, cost, MFA, sessions, rate-limits) now stamps Cache-Control: no-store, private. Defense-in- depth against shared/proxy caches and browser back-forward cache holding caller-private data after logout. Mirrors the existing /v1/admin/crypto-orders hook.
• SDK — list({status,limit}). @driftstack/sdk's client.cryptoOrders.list() now accepts an optional { status, limit } object that maps to the new server-side query params. Existing zero-arg callers continue to work unchanged.
• OpenAPI — customer list ?status= + ?limit= documented. The customer list endpoint's status and limit query parameters now appear in the spec with their enum values. Codegen clients pick up the typed filter automatically on regeneration.
• API — customer order list ?status= filter. GET /v1/billing/crypto-orders now accepts a single-value status query (one of pending / confirming / paid / failed / partial / cancelled). Unknown values return 400. The GUI history view exposes this as a dropdown next to Refresh.
• GUI — receipt PDF + .txt download. The customer-facing receipt view now has both a Download PDF and a Download .txt button. They blob-fetch /v1/billing/crypto-orders/:id/receipt.{pdf,txt} with the Bearer token attached and synthesize an anchor click — the endpoints are auth-gated, so a plain link wouldn't work.
• SDK — typed CryptoOrders resource. @driftstack/sdk ships a client.cryptoOrders resource with quote, createCheckout (with optional idempotencyKey), list, get, updateNote, cancel, and receipt.
• OpenAPI — full crypto surface documented. Quote, daily, pending-age, idempotency-metrics, CSV export, and admin apply-ipn endpoints are now in the spec. Combined with/AY/AZ the entire crypto surface (customer + admin) is machine-readable.
• OpenAPI — receipt endpoints documented. /receipt (JSON), /receipt.txt, and /receipt.pdf now appear in the spec with the appropriate application/json / text/plain / application/pdf response content types.
• OpenAPI — admin crypto endpoints documented. The six core admin crypto endpoints (list, get, events, internal-note, sweep, stats) now appear in the spec under admin + crypto tags. Ops integrators can codegen from /openapi.json instead of hand-rolling clients.
• OpenAPI — crypto endpoints documented. The five customer-facing crypto endpoints (checkout, list, get-one, update-note, cancel) now appear in /openapi.json and on the Scalar UI at /docs. Tagged with billing + crypto for filtering.
• Customer — no-store cache headers on order endpoints. GET /v1/billing/crypto-orders and GET /v1/billing/crypto-orders/:id now set Cache-Control: no-store, private. Order state flips mid-checkout (pending → confirming → paid), so nothing should cache the response. Defensive: requests are already auth-gated.
• Customer — pay-window hint on pending orders. GET /v1/billing/crypto-orders/:id now returns an expires_at ISO timestamp on pending envelopes, set to created_at + 60 minutes. Null on non-pending orders. Informational only — actual expiry is enforced by the admin sweep + the customer cancel endpoint.
• Customer — order events on the detail envelope. GET /v1/billing/crypto-orders/:id now returns an events array on the envelope with the order's append-only state-transition log. Same shape as the admin endpoint added below; the customer-facing view rewrites the internal swept source to expired. Backward-compatible — older callers that ignore unknown fields continue to work.
• Admin — order events timeline. GET /v1/admin/crypto-orders/:id/events returns the order's append-only state-transition log. Each event carries the destination status, an ISO-8601 at timestamp, and a source tag of one of create / ipn / cancel / expired / swept. Rendered inline on the admin detail drawer.
• Admin — payment_id exact-match filter. GET /v1/admin/crypto-orders accepts a payment_id query param for exact-match reverse lookup from a NowPayments payment id. Used by support to find a Driftstack order when the customer only has the provider-side identifier.
• Idempotency-key body-fingerprint check. Replays whose request body fingerprint differs from the stored one increment a new body_mismatches counter and fire a structured warn log. The contract is unchanged (still replays the original order). See /docs/idempotency-keys.
• Ops runbook. Added /docs/crypto-orders-ops-runbook — the support workflow for stuck orders, duplicate-charge claims, and reconciliation.
• Admin — idempotency-key telemetry. GET /v1/admin/crypto-orders/idempotency-metrics returns process-lifetime counters (replays + first_writes) for the checkout idempotency cache. Useful for spotting client-side retry storms.
• Integration guide. Added /docs/billing-crypto-integration-guide — end-to-end walkthrough that stitches checkout, webhooks, idempotency, and receipts together.
• Idempotency-Key on crypto checkout. POST /v1/billing/crypto-checkout now honours an Idempotency-Key request header. Duplicate requests within 24 hours return the original order with an Idempotent-Replayed: 1 response header. See /docs/idempotency-keys.
• Events — crypto.order.failed emitted server-side. Now emitted when an order transitions to failed (via IPN, expiry sweep, or admin sweep) with a reason tag of ipn, expired, or swept. Idempotent — re-running a sweep over already-failed orders does not re-emit. Customer subscription is roadmap; this event isn't in SubscribableWebhookEventTypeSchema yet (see /docs/webhooks-crypto-events).
• Admin CSV export — reference doc. GET /v1/admin/crypto-orders.csv is now documented at /docs/admin-csv-export with the per-column contract + truncation header (X-Driftstack-Export-Truncated). The endpoint itself was added in 2026-04; the doc page is new.
• Crypto orders — PDF receipts. GET /v1/billing/crypto-orders/:id/receipt.pdf joins the existing .txt + JSON receipt variants. Content-Disposition: attachment + a meaningful filename so a browser GET triggers a download.
• Crypto orders — customer note. PATCH /v1/billing/crypto-orders/:id accepts { customer_note: string | null } (capped 500 chars). Stored on the order envelope and returned on subsequent GETs.
• Crypto orders — admin CSV export. GET /v1/admin/crypto-orders.csv reuses the status + search filters and exports up to 1000 rows per call.
• Crypto orders — admin stats KPIs. GET /v1/admin/crypto-orders/stats response gains avg_time_to_paid_ms + paid_sample. Existing fields are unchanged.
• Crypto orders — admin internal note. PATCH /v1/admin/crypto-orders/:id/internal-note sets/clears an admin-only note on an order (never visible to the customer).
• Admin list — cursor pagination. GET /v1/admin/crypto-orders now returns next_cursor alongside orders; callers walk pages by passing the previous response's cursor on the ?cursor= query string. See /docs/admin-api-pagination.
• Events — crypto.order.paid emitted server-side. Emitted when an order transitions to paid (account-scoped, single-fire, idempotent re-deliver of the same IPN doesn't re-emit). Customer subscription is roadmap; this event isn't in SubscribableWebhookEventTypeSchema yet — see /docs/webhooks-crypto-events.

2026-04

• Crypto orders — admin status + search filters. GET /v1/admin/crypto-orders accepts status + search query params filtering across order_id / product / customer_note.
• Crypto orders — receipt + cancel endpoints. GET /v1/billing/crypto-orders/:id/receipt, .txt variant, POST /v1/billing/crypto-orders/:id/cancel for self-service abandonment of pending orders.
• Crypto orders — admin daily breakdown. GET /v1/admin/crypto-orders/daily?days=N returns per-(date, status) counts for the last N days (max 90).

2026-03

• Crypto orders — initial release. POST /v1/billing/crypto-checkout mints orders; the IPN webhook from NowPayments at POST /webhooks/nowpayments/ipn drives the order state machine. Customer-facing list at GET /v1/billing/crypto-orders; admin surface at GET /v1/admin/crypto-orders.

Versioning policy

See the versioning policy for the full lifecycle:

• New endpoints + new optional fields ship without bumping the version.
• Removing a field or changing its type requires the 90-day deprecation window documented in /docs/api-versioning, with a Deprecation response header (RFC 5988) carrying the sunset date from the moment the deprecation lands.
• Major-version bumps (next is v2) ship in lock-step with published migration notes and at least 12 months of v1 support.

Subscribe

We post a summary of each month's changes to status.driftstack.dev as a non-incident announcement, and email the api-changes@ mailing list. Subscribe at app.driftstack.dev/settings/notifications.

Related

• API versioning policy
• API reference
• Error codes