AI generation API versioning and deprecation

The API is versioned by URL prefix (/v1). Additive, backwards-compatible changes (new endpoints, new optional fields, new error codes) land within the current version. Breaking changes require a new major version (/v2).

1. Breaking changes are announced at least 90 days before removal.
2. Deprecated endpoints return a Deprecation: true response header and keep working during the deprecation window.
3. Changelog entries mark each change with added, changed, deprecated, or removed.
4. The current version remains fully supported for at least 12 months after the next major version ships.

2026-10-22 — v1 (October additions)

• added — paymentMode: "direct" on generations for one-time pay-per-job billing, alongside the existing "credits" and "wallet" modes.
• added — POST /v1/assets/bulk-download resolves a presigned download URL per requested asset.
• added — Boards: GET/POST /v1/boards, PATCH/DELETE /v1/boards/:id, POST /v1/boards/:id/items, PATCH/DELETE /v1/boards/:id/items/:itemId, PATCH /v1/boards/:id/order. Reading is free; mutations require a paid plan.
• added — Voice profiles: GET/POST /v1/voices, GET/PATCH/DELETE /v1/voices/:id, POST /v1/voices/:id/refresh.
• added — Generation presets: GET/POST /v1/presets, GET/PATCH/DELETE /v1/presets/:id.
• added — Chat conversations: GET/POST /v1/chat/conversations, GET/DELETE /v1/chat/conversations/:conversationId, GET/POST /v1/chat/conversations/:conversationId/messages. Chat completions also stream over WebSocket with SSE as the fallback transport.
• added — Reference templates: POST /v1/reference/quote, POST /v1/reference/analyses, GET /v1/reference/analyses/:workflowId, and .../cancel / .../retry turn an uploaded image or video into a draft workflow template (isTemplate + templateMeta), metered on real vision tokens. Requires the workflows.write scope.
• changed — Flow steps resolve {{nodeId}} tokens from upstream step output and {{subject}} from the run input in a single pass.
• No deprecations or breaking changes in this window.

2026-08-02 — v1 (initial public surface)

• added — API keys: GET/POST /v1/api-keys, DELETE /v1/api-keys/:id, GET /v1/api-keys/:id/usage. Bearer authentication, scopes, per-key rate limits with X-RateLimit-* headers, api_requests usage logging.
• added — Idempotency-Key header support on POST /v1/generations.
• added — Customer webhooks: GET/POST/PATCH/DELETE /v1/webhooks, GET /v1/webhooks/:id/deliveries. Delivery with HMAC-SHA256 X-FreeInd-Signature header, exponential-backoff retries, delivery history.
• added — paymentMode: "wallet" on generations for pay-as-you-go wallet billing.
• added — Wallet endpoints: GET /v1/wallet, POST /v1/wallet/top-ups (server-side $10 minimum), GET /v1/wallet/transactions, GET /v1/wallet/deposits.
• changed — /v1/models, /v1/generations*, /v1/usage, /v1/files/*, /v1/assets*, /v1/wallet* accept Bearer API keys in addition to session cookies.
• added — favorite, mediaType, and sourceGenerationId filters on GET /v1/assets; PATCH /v1/assets/:id for favorites.

Stable error codes and the error envelope ({"error":{"code","message","requestId"}}) are part of the v1 contract. New codes are additive; existing codes never change meaning. See Authentication for the full error code list.