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 replayableintent_log), andDELETE /v1/recipes/{id}(204 No Content; not idempotent). Joins the existingPOST /v1/recipescapture 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-tokenendpoint 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-sessionsnow also auto-populates alivekitfield 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/registeradmin endpoint accepts per-Mac LiveKit API credentials on harness boot. The API secret is encrypted at rest under the existingMFA_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 amac_node.livekit_registeredrow to the admin audit log attributing the operator + recording themac_node_id+ws_url— the audit payload deliberately omits the api_key + api_secret so secret material never leaks via audit replay. - SDKs —
LiveKitInfotype across TS / Python / Go. New typed shape carriesws_url+room+token+participant_identity+expires_at. Used on the new/livekit-tokenresponse AND the optionallivekitfield on session-create — one type, two consumption surfaces.AgentSession.livekitfield 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 scatteredhttps://app.driftstack.devliterals + the legacyPUBLIC_DASHBOARD_URLenv 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_ORIGINenv 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 tolocalhost— 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+useAdminInternalNotein favour of the shared helper. - GUI — surface server problem+json detail on 4xx.
Customer-facing hooks now read the RFC 7807
detailfield 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_beforequery params. - GUI — Load more on customer history view.
The customer history view now exposes the server's
next_cursoras 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.csvnow respectscreated_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_beforequery params. - API — date-range filter on admin order list.
GET /v1/admin/crypto-ordersnow accepts the samecreated_after/created_beforeISO 8601 window. Combine withstatusandcursorto scope reconciliation scans. - API — date-range filter on customer order list.
GET /v1/billing/crypto-ordersnow accepts?created_after=(inclusive) and?created_before=(exclusive), both ISO 8601 timestamps. Composes withstatusandcursorfor backfill scans. The SDK exposes the same fields onlist()/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 untilnext_cursoris null. Accepts the same options aslist()minuscursor; callers canbreakearly. - API — customer order list cursor pagination.
GET /v1/billing/crypto-ordersnow returns anext_cursoralongsideordersand accepts a?cursor=query param. Mirrors the admin endpoint. The SDK'sclient.cryptoOrders.list()accepts the newcursoroption; loop untilresponse.next_cursoris null. - api-types —
ListCryptoOrdersQueryexported.@driftstack/api-typesnow ships a Zod schema + type for the customer list query, mirroring the server's accepted parameters. The TypeScript SDK reuses it so itslist()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-ordersevery 60s while any visible order is stillpending. 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-orderswas 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 stampsCache-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-ordershook. - SDK —
list({status,limit}).@driftstack/sdk'sclient.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'sstatusandlimitquery 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-ordersnow accepts a single-valuestatusquery (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/sdkships aclient.cryptoOrdersresource withquote,createCheckout(with optionalidempotencyKey),list,get,updateNote,cancel, andreceipt. - 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.pdfnow appear in the spec with the appropriateapplication/json/text/plain/application/pdfresponse 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+cryptotags. Ops integrators can codegen from/openapi.jsoninstead 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.jsonand on the Scalar UI at/docs. Tagged withbilling+cryptofor filtering. - Customer — no-store cache headers on order endpoints.
GET /v1/billing/crypto-ordersandGET /v1/billing/crypto-orders/:idnow setCache-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/:idnow returns anexpires_atISO timestamp on pending envelopes, set tocreated_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/:idnow returns aneventsarray 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 internalsweptsource toexpired. Backward-compatible — older callers that ignore unknown fields continue to work. - Admin — order events timeline.
GET /v1/admin/crypto-orders/:id/eventsreturns the order's append-only state-transition log. Each event carries the destinationstatus, an ISO-8601attimestamp, and asourcetag of one ofcreate/ipn/cancel/expired/swept. Rendered inline on the admin detail drawer. - Admin — payment_id exact-match filter.
GET /v1/admin/crypto-ordersaccepts apayment_idquery 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_mismatchescounter 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-metricsreturns 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-checkoutnow honours anIdempotency-Keyrequest header. Duplicate requests within 24 hours return the original order with anIdempotent-Replayed: 1response header. See /docs/idempotency-keys. - Events —
crypto.order.failedemitted server-side. Now emitted when an order transitions tofailed(via IPN, expiry sweep, or admin sweep) with areasontag ofipn,expired, orswept. Idempotent — re-running a sweep over already-failed orders does not re-emit. Customer subscription is roadmap; this event isn't inSubscribableWebhookEventTypeSchemayet (see /docs/webhooks-crypto-events). - Admin CSV export — reference doc.
GET /v1/admin/crypto-orders.csvis 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.pdfjoins 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/:idaccepts{ 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.csvreuses the status + search filters and exports up to 1000 rows per call. - Crypto orders — admin stats KPIs.
GET /v1/admin/crypto-orders/statsresponse gainsavg_time_to_paid_ms+paid_sample. Existing fields are unchanged. - Crypto orders — admin internal note.
PATCH /v1/admin/crypto-orders/:id/internal-notesets/clears an admin-only note on an order (never visible to the customer). - Admin list — cursor pagination.
GET /v1/admin/crypto-ordersnow returnsnext_cursoralongsideorders; callers walk pages by passing the previous response's cursor on the?cursor=query string. See /docs/admin-api-pagination. - Events —
crypto.order.paidemitted 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 inSubscribableWebhookEventTypeSchemayet — see /docs/webhooks-crypto-events.
2026-04
- Crypto orders — admin status + search filters.
GET /v1/admin/crypto-ordersacceptsstatus+searchquery params filtering across order_id / product / customer_note. - Crypto orders — receipt + cancel endpoints.
GET /v1/billing/crypto-orders/:id/receipt,.txtvariant,POST /v1/billing/crypto-orders/:id/cancelfor self-service abandonment of pending orders. - Crypto orders — admin daily breakdown.
GET /v1/admin/crypto-orders/daily?days=Nreturns per-(date, status) counts for the last N days (max 90).
2026-03
- Crypto orders — initial release.
POST /v1/billing/crypto-checkoutmints orders; the IPN webhook from NowPayments atPOST /webhooks/nowpayments/ipndrives the order state machine. Customer-facing list atGET /v1/billing/crypto-orders; admin surface atGET /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
Deprecationresponse 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.