@hunt-labs/bytekit-sdk 0.11.8 → 0.11.10

package/dist/generated/api.d.ts

@@ -153,7 +153,9 @@ export interface paths {
         put?: never;
         /**
          * Capture a screenshot
-         * @description Sync by default (holds up to 28s). Pass `?async=true` to return 202 immediately.
+         * @description Sync by default (holds up to 28s). Pass `async: true` in the body or `?async=true` in the
+         *     query string to return 202 immediately; either one is enough, and `false` in one never
+         *     cancels `true` in the other.
          *     Poll via GET /v1/screenshots/{id}.
          *
          *     **Limits:** request bodies are capped at 512 KB. An oversized body
@@ -198,13 +200,15 @@ export interface paths {
          *
          *     **The response shape is decided by your request, not by how we route it.** In precedence order:
          *
-         *     1. `async: true` → **202** with a `ScrapeQueuedEnvelope` receipt, returned immediately. Poll `GET /v1/scrape/{id}` for the result.
+         *     1. `async: true` in the body, or `?async=true` in the query string (either one is enough; `false` in one never cancels `true` in the other) → **202** with a `ScrapeQueuedEnvelope` receipt, returned immediately. Poll `GET /v1/scrape/{id}` for the result.
          *     2. Otherwise, a request that needs a full page render — today that is `delay_ms > 0` — is **held open** until the render reaches a terminal state, then returns **200** with the content envelope (`success` or `failed`). If the render is still running when the hold window expires (28 seconds by default), the request returns the **202** receipt instead and the job continues in the background.
          *     3. Otherwise the request is served by the fast HTTP path and returns **200** with the content envelope, typically in under a second.
          *
          *     **A failed fetch is a result, not a transport error.** An unreachable host, a refused connection, or a target whose bot protection defeats every proxy tier all come back on the same **200** as a `failed` envelope — never a 5xx. Narrow on the envelope's `status` before reading the body. A failure the fast path decides inline is recorded as a failed job, so its envelope normally carries that job's `id` and `GET /v1/scrape/{id}` returns the same envelope; if recording the failed job itself fails, the envelope still arrives on the same 200 with `id` set to `null` and there is nothing to poll. A failure a held render reaches carries that render's real `id`. Either way the request transfers no billable bytes and is charged nothing.
          *
-         *     So a 202 means one of exactly two things: you asked for one with `async: true`, or the hold window expired. `wait_for_selector` and `wait_until` are `ScreenshotRequest` options, not `ScrapeRequest` options — sending either to this endpoint returns `422 validation_error`, so neither can produce a 202 here.
+         *     **A target that rate-limits us is not ByteKit rate-limiting you.** The `failed` envelope's `error.code` is `target_rate_limited` when the target rate-limits the request. On the fast path that means our proxy attempts end on an HTTP 429 and no bot protection is identified on any attempt, even if the browser fallback then fails or reaches only an unidentified block page; the inline failure carries `error.retry_after_seconds` when the target sent a usable `Retry-After`. On a held render the browser's own answer decides: it observes a 429 on the page itself, or it fails outright after the proxy attempts ended on an HTTP 429. A bot-protection verdict on an earlier fetch attempt does not keep a held render `blocked` when the browser then observes the 429. A held render never carries `error.retry_after_seconds`. Retrying a `target_rate_limited` failure later is likely to work. A held render whose browser reaches an unidentified 403 or 503 page after a proxy 429 is `blocked`. A 429 that bot protection sends as a block stays `blocked` when it is the answer that decides the code: the fast path's proxy attempts, or the browser render on a held render. Your own per-key limit is a separate case: it answers HTTP 429 `rate_limited` with a `Retry-After` header (see the `429` response).
+         *
+         *     So a 202 means one of exactly two things: you asked for one with `async: true` or `?async=true`, or the hold window expired. `wait_for_selector` and `wait_until` are `ScreenshotRequest` options, not `ScrapeRequest` options — sending either to this endpoint returns `422 validation_error`, so neither can produce a 202 here.
          */
         post: operations["createScrape"];
         delete?: never;
@@ -249,6 +253,12 @@ export interface paths {
          *     `BulkCompletedWebhook` contract: at most 500 complete items and 1 MiB,
          *     followed by cursor recovery through `GET /v1/scrape/bulk/{id}` whenever
          *     `recovery_required` is true.
+         *
+         *     **Unknown keys.** An unknown key on an `items[]` entry, or at the top level of
+         *     the body, is rejected with `422 validation_error`. An unknown key inside
+         *     `defaults` is not: it is dropped without a warning and the request is accepted
+         *     with `202`. The exception is `cookies` and `headers`, on an item or in `defaults`: they
+         *     answer `400 validation_error`.
          */
         post: operations["createScrapeBulk"];
         delete?: never;
@@ -277,6 +287,17 @@ export interface paths {
          *     stored, or whose object cannot be signed, is omitted from `formats` and
          *     reported as `artifact_unavailable` in `warnings`. The private unsigned
          *     storage URL is never returned.
+         *
+         *     **Cancelled by the platform.** When the account can no longer spend (its bandwidth
+         *     balance is exhausted, or the account is deleted) while items are still pending, ByteKit
+         *     cancels the job itself. It then reads `status: cancelled` even though you never called
+         *     `DELETE /v1/bulk/{id}`, and the cancellation sends no webhook.
+         *
+         *     **Job ids from other create routes.** The job is looked up by account only, so the id
+         *     of a job created by `POST /v1/fetch/bulk` or `POST /v1/bulk` is found here too, not a `404`.
+         *     The items listed are the job's scrape rows: a fetch-bulk job's items appear, and a
+         *     `POST /v1/bulk` job shows its scrape items but not its screenshots. An id from another
+         *     account answers `404`.
          */
         get: operations["getScrapeBulk"];
         put?: never;
@@ -296,15 +317,20 @@ export interface paths {
         };
         /**
          * Fetch a URL (GET)
-         * @description Direct HTTP fetch. Successful responses return the upstream response bytes verbatim;
-         *     metadata is returned in X-Fetch-* headers. Non-2xx upstream responses use the
-         *     `upstream_error` JSON envelope with the upstream HTTP status.
+         * @description Direct HTTP fetch. Metadata is returned in X-Fetch-* headers. What the body holds
+         *     depends on `X-Fetch-Fast-Path`. When it is `true`, a successful response returns the
+         *     upstream response bytes verbatim. When it is `false` the request fell back to a browser
+         *     render, and the body is the rendered page rather than the bytes the target sent;
+         *     `X-Fetch-Content-Length` is then the compressed size of that page. Non-2xx upstream
+         *     responses use the `upstream_error` JSON envelope with the upstream HTTP status.
          */
         get: operations["getFetch"];
         put?: never;
         /**
          * Fetch a URL (POST)
-         * @description Same as GET /v1/fetch but with a JSON request body.
+         * @description Same as GET /v1/fetch but with a JSON request body. The response is the same, including
+         *     the `X-Fetch-Fast-Path` rule for what the body holds: the upstream bytes verbatim when
+         *     it is `true`, the rendered page when it is `false`.
          *
          *     **Limits:** request bodies are capped at 512 KB. An oversized body
          *     returns a `400` with error code `request_too_large`.
@@ -373,6 +399,16 @@ export interface paths {
          *     stored object, or completed items whose object cannot be signed, carry
          *     `null`; the latter report `artifact_unavailable`. The private unsigned
          *     storage URL is never returned.
+         *
+         *     **Cancelled by the platform.** When the account can no longer spend (its bandwidth
+         *     balance is exhausted, or the account is deleted) while items are still pending, ByteKit
+         *     cancels the job itself. It then reads `status: cancelled` even though you never called
+         *     `DELETE /v1/bulk/{id}`, and the cancellation sends no webhook.
+         *
+         *     **Job ids from other create routes.** The job is looked up by account only, so the id
+         *     of a job created by `POST /v1/scrape/bulk` or `POST /v1/bulk` is found here too, not a
+         *     `404`, with the job envelope and `items: []`: only items fetched through
+         *     `POST /v1/fetch/bulk` are listed. An id from another account answers `404`.
          */
         get: operations["getFetchBulk"];
         put?: never;
@@ -436,7 +472,19 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Get bulk job status */
+        /**
+         * Get bulk job status
+         * @description Returns the job envelope. Items are listed by `GET /v1/bulk/{id}/screenshots`.
+         *
+         *     **Cancelled by the platform.** When the account can no longer spend (its bandwidth
+         *     balance is exhausted, or the account is deleted) while items are still pending, ByteKit
+         *     cancels the job itself. It then reads `status: cancelled` even though you never called
+         *     `DELETE /v1/bulk/{id}`, and the cancellation sends no webhook.
+         *
+         *     **Job ids from other create routes.** The job is looked up by account only, so the id
+         *     of a job created by `POST /v1/scrape/bulk` or `POST /v1/fetch/bulk` is found here too, not
+         *     a `404`, with that job's envelope. An id from another account answers `404`.
+         */
         get: operations["getBulk"];
         put?: never;
         post?: never;
@@ -567,6 +615,20 @@ export interface paths {
          *     `X-ByteKit-Event: sitemap.failed` so receivers can dispatch on the
          *     header without parsing the body shape.
          *
+         *     The webhook body is `{ event, data }`. For a job the worker ran, `data` is not a
+         *     `SitemapResponse`:
+         *
+         *     - `sitemap.completed` `data` carries `id`, `url`, `strategy`, `status`,
+         *       `total_urls`, `sources`, `total_bytes`, `results_url`, `warnings`,
+         *       `metadata`, `compact` and `billing`.
+         *     - `sitemap.failed` `data` carries `id`, `url`, `strategy`, `status`,
+         *       `error_code`, `error_message`, `warnings` and `metadata`.
+         *
+         *     In both, `url` is the host as `scheme://host`, and `warnings` is the
+         *     worker's own warnings or `null`. When the request is answered from a cached job
+         *     (`cache: hit`), the `sitemap.completed` `data` is instead the full job object, the
+         *     same fields as a `SitemapResponse`.
+         *
          *     **Limits:** request bodies are capped at 512 KB. An oversized body
          *     returns a `400` with error code `request_too_large`.
          */
@@ -644,9 +706,6 @@ export interface paths {
          *     endpoint factor (a 100 KiB estimate is pre-charged, then reconciled). The
          *     bandwidth is still billed when the scrape succeeds but extraction later
          *     fails; both axes are refunded only when the scrape itself never runs.
-         *
-         *     Availability is gated by a server-side feature flag; when disabled the
-         *     endpoint returns `404`.
          */
         post: operations["createSchemaExtraction"];
         delete?: never;
@@ -743,7 +802,11 @@ export interface paths {
         put?: never;
         /**
          * Create Stripe checkout session
-         * @description Creates a Stripe Checkout Session for subscription sign-up.
+         * @description Creates an Elements-mode Stripe Checkout session for subscription sign-up
+         *     and returns its client secret. The dashboard mounts Stripe's Payment
+         *     Element on `client_secret` and the user pays in-page; the plan activates
+         *     asynchronously once Stripe's subscription webhook settles. The card paid
+         *     with becomes the customer's default when none is set.
          */
         post: operations["createCheckout"];
         delete?: never;
@@ -761,7 +824,11 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Create Stripe billing portal session */
+        /**
+         * Retired billing-portal compatibility terminal
+         * @description Returns 410 for every request and reads no body. Card update, cancellation and
+         *     invoice history all stay in the dashboard at `/settings/billing`.
+         */
         post: operations["createPortal"];
         delete?: never;
         options?: never;
@@ -779,9 +846,8 @@ export interface paths {
         get?: never;
         put?: never;
         /**
-         * PAYG onboarding
-         * @description Creates a Stripe customer and setup-mode Checkout Session to collect
-         *     a payment method without charging. For pay-as-you-go accounts.
+         * Legacy card-setup compatibility terminal
+         * @description Returns 410. Card setup moved to `POST /v1/billing/payment-methods/setup`.
          */
         post: operations["registerPayg"];
         delete?: never;
@@ -801,10 +867,11 @@ export interface paths {
         put?: never;
         /**
          * One-time dollar deposit
-         * @description Creates a hosted Stripe Checkout session for a deposit into the account's
-         *     USD balance and returns its URL. The caller redirects the user to
-         *     `checkout_url`; the balance is credited asynchronously by the
-         *     `payment_intent.succeeded` webhook once payment completes. The balance
+         * @description Creates an Elements-mode Stripe Checkout session for a deposit into the
+         *     account's USD balance and returns its client secret. The dashboard mounts
+         *     Stripe's Payment Element on `client_secret` and the user pays in-page; the
+         *     balance is credited asynchronously once Stripe's payment webhook settles.
+         *     The card paid with becomes the customer's default when none is set. The balance
          *     never expires and pays for usage beyond the included allowance, for
          *     bandwidth and search credits alike, at the plan's rate when it is used.
          */
@@ -822,15 +889,22 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        get?: never;
+        /**
+         * Read whether the plan is cancelling
+         * @description Whether the subscription is set to end at the end of the current period, read from Stripe on each call.
+         */
+        get: operations["getCancellation"];
         put?: never;
         /**
-         * Legacy cancellation compatibility terminal
-         * @description Returns 410. Customer cancellation is initiated through the hosted
-         *     Billing Portal and projected through Stripe webhooks.
+         * Cancel the plan at the period end
+         * @description Sets the subscription to end at the end of the current period instead of renewing; the plan stays active until then and the account then moves to Pay As You Go. A plan change booked for the period end is released first. Send the current cancellation disclosure revision in the `Billing-Disclosure-Revision` header: without it, or with a stale one, the call answers `409 billing_disclosure_stale` with the current terms.
          */
         post: operations["cancelSubscription"];
-        delete?: never;
+        /**
+         * Keep a cancelling plan
+         * @description Undoes a pending cancellation, so the subscription renews at the end of the current period as before.
+         */
+        delete: operations["keepSubscription"];
         options?: never;
         head?: never;
         patch?: never;
@@ -849,7 +923,10 @@ export interface paths {
          */
         get: operations["getPlanChange"];
         put?: never;
-        /** Change subscription plan */
+        /**
+         * Change subscription plan
+         * @description A plan change made while the plan is cancelling clears the pending cancellation, so the subscription keeps renewing.
+         */
         post: operations["changePlan"];
         /**
          * Revoke a scheduled plan change
@@ -868,7 +945,10 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** List Stripe invoices */
+        /**
+         * List Stripe invoices
+         * @description Invoices are ordered newest first. Page older with `starting_after` set to the last `id` of the previous page.
+         */
         get: operations["listInvoices"];
         put?: never;
         post?: never;
@@ -994,6 +1074,7 @@ export interface paths {
         /**
          * Detach a payment method
          * @description Detaches the specified payment method from the Stripe customer.
+         *     Removing the last card also turns auto-topup off.
          */
         delete: operations["deletePaymentMethod"];
         options?: never;
@@ -1148,8 +1229,9 @@ export interface paths {
         put?: never;
         /**
          * Accept current Terms of Service
-         * @description Records the authenticated account's acceptance of the current Terms of
-         *     Service version (clickwrap re-acceptance). The server always records the
+         * @description Records the signed-in person's own acceptance of the current Terms of
+         *     Service version (clickwrap). The record is per person, so each member of
+         *     an account accepts for themselves. The server always records the
          *     current version — the client cannot accept an arbitrary version. The
          *     client IP and User-Agent are captured as legal evidence. Requires an
          *     active membership.
@@ -1172,9 +1254,10 @@ export interface paths {
         put?: never;
         /**
          * Mark onboarding as finished
-         * @description Records that the account left the dashboard's onboarding flow through one
-         *     of its exits, so `onboarding_completed` on GET /v1/account reads true from
-         *     then on. Idempotent: a repeat call keeps the first timestamp and still
+         * @description Records that the signed-in person left the dashboard's onboarding flow
+         *     through one of its exits, so both `onboarding_completed` (the account) and
+         *     `user_onboarding_completed` (this person) on GET /v1/account read true
+         *     from then on. Idempotent: a repeat call keeps the first timestamps and still
          *     answers 200. Requires an active membership (admin or member).
          */
         post: operations["completeOnboarding"];
@@ -1464,6 +1547,14 @@ export interface components {
                 details?: unknown;
             };
         };
+        /** @description The vendor-masked `503` body of `POST /v1/search`. */
+        CreateSearchResponse503: {
+            /**
+             * @description Fixed vendor-masked error code. Always `search_provider_error`; the upstream provider's identity and failure detail are withheld by design.
+             * @enum {string}
+             */
+            error: "search_provider_error";
+        };
         /**
          * @description Item-local terminal artifact failure. The item's stable id remains usable for paginated recovery, but the requested stored content or signed reference could not be produced. Wherever this code is raised the URL field it describes is `null`; a private object-storage URL is never returned as a substitute for it. Endpoints that do not raise this code document their own fallback — see `image_url` on `GET /v1/bulk/{id}/screenshots`.
          *
@@ -1648,10 +1739,11 @@ export interface components {
         BillingNode: {
             /**
              * @description The unmultiplied basis of the charge. For byte-billed endpoints this is
-             *     the upstream wire bytes actually transferred. For screenshots and
-             *     recordings it is the Phase 1 HTML fetch's wire bytes — the only proxied
-             *     traffic in the happy path — never the size of the returned PNG/JPEG/MP4
-             *     artifact.
+             *     the upstream wire bytes actually transferred. For a page served by the
+             *     hosted-browser tier it is the browser's full measured transfer. For
+             *     screenshots and recordings it is the Phase 1 HTML fetch's wire bytes — the
+             *     only proxied traffic in the happy path — never the size of the returned
+             *     PNG/JPEG/MP4 artifact.
              * @example 1024
              */
             raw_bytes: number;
@@ -1674,11 +1766,19 @@ export interface components {
             /** Format: uri */
             url: string;
             /**
+             * @description What to return. Each entry is either a string format (`raw`, `markdown`, `links`
+             *     or `images`) or a `json` object entry that extracts structured data from the page.
+             *     The string `"json"` is not a format value; the `json` entry is an object, described
+             *     by `ScrapeRequestJsonFormat`. A list may hold at most one `json` entry, and a list
+             *     holding only the `json` entry still captures `raw`. The `json` entry exists on
+             *     `POST /v1/scrape` only: the bulk and monitor `formats` fields accept the string
+             *     formats alone. Its result is `formats.json` on the response, and its price is
+             *     described on `ScrapeRequestJsonFormat`.
              * @default [
              *       "raw"
              *     ]
              */
-            formats: ("raw" | "markdown" | "links" | "images")[];
+            formats: (components["schemas"]["ScrapeRequestFormatsItem"] | components["schemas"]["ScrapeRequestJsonFormat"])[];
             /** @default US */
             country: string;
             /**
@@ -1686,10 +1786,10 @@ export interface components {
              * @default 0
              */
             delay_ms: number;
-            /** @default 30000 */
+            /** @default 60000 */
             timeout_ms: number;
             /**
-             * @description When true, the request returns 202 with a `ScrapeQueuedEnvelope` receipt immediately and the scrape runs in the background; poll `GET /v1/scrape/{id}` for the result. This is the only way to ASK for a receipt, and it outranks every routing consequence: with `async: false` (the default) a browser-path request is held to completion instead of being receipted. A 202 can still arrive with `async: false`, but only when the hold window expires.
+             * @description When true, the request returns 202 with a `ScrapeQueuedEnvelope` receipt immediately and the scrape runs in the background; poll `GET /v1/scrape/{id}` for the result. The `?async=true` query parameter is a second spelling of this field: the request is async when either one says true, and `false` in one never cancels `true` in the other. Asking for a receipt this way outranks every routing consequence: when neither is set (the default) a browser-path request is held to completion instead of being receipted. A 202 can still arrive without either, but only when the hold window expires.
              * @default false
              */
             async: boolean;
@@ -1794,6 +1894,47 @@ export interface components {
              */
             x_internal_scrape_path?: "lean-forced";
         };
+        /**
+         * @description A string entry of `ScrapeRequest.formats`.
+         * @enum {string}
+         */
+        ScrapeRequestFormatsItem: "raw" | "markdown" | "links" | "images";
+        /**
+         * @description The `json` entry of `ScrapeRequest.formats`: structured extraction over the scraped
+         *     page, using the same extractor as `POST /v1/schema`.
+         *
+         *     **Price.** Each `json` entry costs 10 credits, charged only when the extraction
+         *     validates (`formats.json.validated` is `true`). The charge is on top of the scrape's
+         *     own charge and is never scaled by the scrape's factors. The 10 credits are reserved at
+         *     admission in every billing mode and released again when the extraction does not
+         *     validate. This price is provisional.
+         *
+         *     **Errors.** A `schema` the extractor cannot take is refused with
+         *     `422 schema_incompatible`, and a deployment with no extraction provider refuses the
+         *     request with `503 provider_unavailable`. Both are refused before anything is drawn. Once
+         *     the page is scraped, an extraction that does not validate never fails the scrape: the
+         *     result carries `validated: false` and `data: null`, with an extraction warning in
+         *     `warnings`.
+         */
+        ScrapeRequestJsonFormat: {
+            /** @enum {string} */
+            type: "json";
+            /**
+             * @description JSON Schema describing the desired output. It is held to the same guards as the
+             *     `schema` field of `POST /v1/schema`: serialized size at most 50 KB, nesting depth at
+             *     most 8, it must compile under Ajv, and it must be normalizable into the extractor's
+             *     strict subset (root `type: object`, and only the keyword allowlist given there).
+             */
+            schema: Record<string, never>;
+            /**
+             * @description Extraction model.
+             * @default openai/gpt-oss-20b
+             * @enum {string}
+             */
+            model: "openai/gpt-oss-20b" | "openai/gpt-oss-120b";
+            /** @description Optional natural-language extraction hint. */
+            prompt?: string;
+        };
         ScrapeScoredLink: {
             /** Format: uri */
             url: string;
@@ -1818,8 +1959,11 @@ export interface components {
             cols: number;
         };
         ScrapeWarning: {
-            /** @enum {string} */
-            code: "lossy_table" | "complex_math" | "unsupported_element" | "extraction_fallback" | "truncated" | "query_no_match" | "mode_disabled_fallback" | "artifact_unavailable" | "llm_clean_unavailable" | "llm_clean_failed" | "low_quality_extraction" | "fragment_menu_stripped";
+            /**
+             * @description Machine-readable warning code. `truncated` means the markdown was cut to fit the requested `tokenBudget`. `short_content` means a successful browser capture of an HTML page produced very little readable text (under 100 characters), which usually means the page needed an interaction such as scrolling or clicking that the capture did not perform; a genuinely short page can raise it too. `frames_skipped` means a browser capture left out one or more iframes (cross-origin ones, which the capture cannot read, or same-origin ones that failed or were still loading), so content inside them may be missing from the returned HTML. `short_content` and `frames_skipped` are advisory: they never change the response status, error code or billed bytes.
+             * @enum {string}
+             */
+            code: "lossy_table" | "complex_math" | "unsupported_element" | "extraction_fallback" | "truncated" | "query_no_match" | "mode_disabled_fallback" | "artifact_unavailable" | "llm_clean_unavailable" | "llm_clean_failed" | "low_quality_extraction" | "fragment_menu_stripped" | "extract_validation_failed" | "exhausted_retries" | "content_truncated" | "model_refusal" | "empty_extraction" | "short_content" | "frames_skipped";
             message: string;
             element: string | null;
         };
@@ -1844,6 +1988,19 @@ export interface components {
             links?: string[] | components["schemas"]["ScrapeScoredLink"][];
             /** @description Plain URL strings by default. When markdownIncludeMedia=true, an array of ScrapeScoredImage objects. */
             images?: string[] | components["schemas"]["ScrapeScoredImage"][];
+            /**
+             * @description The result of the request's `json` format entry. Present on every outcome of a
+             *     request that carried one. A failed extraction never fails the scrape: it sets
+             *     `validated` to `false` and adds an extraction warning code to `warnings`.
+             */
+            json?: {
+                /** @description The extracted object, or `null` whenever `validated` is `false`. */
+                data: Record<string, never> | null;
+                /** @description Whether the extraction produced output matching the schema. The `json` credits are charged only when `true`. */
+                validated: boolean;
+                /** @description The extraction model that ran. */
+                model: string;
+            };
         };
         ScrapeMetadata: {
             title: string | null;
@@ -1955,6 +2112,8 @@ export interface components {
              * @description Compressed wire bytes transferred for this request — the basis for
              *     bandwidth-billed plans. Reflects what crossed the network on your behalf
              *     (e.g. gzip/brotli-compressed size), not the decompressed content length.
+             *     A page served by the hosted-browser tier reports the browser's full
+             *     measured transfer instead: every response it loaded plus the requests it sent.
              */
             content_length: number;
             status_code: number | null;
@@ -2026,9 +2185,11 @@ export interface components {
             id: string | null;
             error: {
                 /** @enum {string} */
-                code: "validation_error" | "invalid_url" | "request_too_large" | "payload_too_large" | "unsupported_content_type" | "rate_limited" | "upstream_error" | "blocked" | "timeout" | "internal_error";
+                code: "validation_error" | "invalid_url" | "request_too_large" | "payload_too_large" | "unsupported_content_type" | "rate_limited" | "upstream_error" | "blocked" | "target_rate_limited" | "timeout" | "internal_error";
                 message: string;
                 http_status?: number;
+                /** @description Whole seconds the target site asked us to wait before the next request. Present only with `code: target_rate_limited`, only on the inline `POST /v1/scrape` failure the fast path decides, and only when the target sent a usable `Retry-After` (delta-seconds, or an HTTP-date still in the future, converted to seconds; values above 2147483647 are reported as 2147483647). Informational: ByteKit never enforces it on your next request. A held render (`delay_ms > 0`), `GET /v1/scrape/{id}` and webhooks omit it, because the value is relative to the moment the target answered. */
+                retry_after_seconds?: number;
                 /** Format: date-time */
                 failed_at: string;
             };
@@ -2069,7 +2230,10 @@ export interface components {
         FetchRequest: {
             /** Format: uri */
             url: string;
-            /** @default US */
+            /**
+             * @description Two-letter country code. Either case is accepted; the value is upper-cased.
+             * @default US
+             */
             country: string;
             /** @default 60000 */
             timeout_ms: number;
@@ -2096,6 +2260,11 @@ export interface components {
             device: "desktop" | "mobile";
             /** @default null */
             viewport: components["schemas"]["Viewport"] | null;
+            /**
+             * @description When true, the request returns 202 immediately and the screenshot is captured in the background; poll `GET /v1/screenshots/{id}`. The `?async=true` query parameter is a second spelling of this field: the request is async when either one says true, and `false` in one never cancels `true` in the other.
+             * @default false
+             */
+            async: boolean;
             /** @default false */
             full_page: boolean;
             /**
@@ -2432,9 +2601,26 @@ export interface components {
             captured_at: string;
         };
         SitemapRequest: {
-            /** Format: uri */
+            /**
+             * Format: uri
+             * @description The site to discover. Sitemap discovery is host-scoped (`robots.txt`
+             *     and `/sitemap.xml` live at the host root), so only the scheme and host
+             *     are used: a path, query string or fragment is accepted but ignored,
+             *     and the `202` response carries a `warnings` entry saying so. A bare
+             *     host, or a host with just a trailing `/`, produces no warning.
+             */
             url: string;
             /**
+             * @description How much discovery work the job does.
+             *
+             *     - `quick` — reads `robots.txt` and the XML sitemaps only. Every
+             *       result has `source: sitemap`.
+             *     - `standard` — the `quick` sources, then fills any remaining
+             *       `max_urls` budget with URLs from your account's completed scrapes of
+             *       the host in the last 90 days (`source: known`).
+             *     - `deep` — the `standard` sources, then crawls page links outward from
+             *       the URLs found so far, up to `max_depth` levels, until `max_urls` is
+             *       reached (`source: links`).
              * @default standard
              * @enum {string}
              */
@@ -2443,7 +2629,11 @@ export interface components {
             max_depth: number;
             /** @default 5000 */
             max_urls: number;
-            /** @default null */
+            /**
+             * @description Accepted, stored and echoed back on the job, but it has no effect: the
+             *     worker logs that the trigger is not implemented and ignores it.
+             * @default null
+             */
             process: {
                 action?: string;
                 options?: {
@@ -2472,6 +2662,17 @@ export interface components {
         SitemapResponse: {
             /** @example sm_01j9abc123 */
             id: string;
+            /**
+             * @description On the `202` creation response, the submitted URL after ByteKit has
+             *     normalised it, when that URL carried a path, query string or fragment
+             *     (discovery still ran on the host only; see `warnings`). Normalisation
+             *     lowercases the scheme and host, puts an international host in
+             *     punycode, percent-encodes non-ASCII characters and trims surrounding
+             *     spaces, so the value can differ from the string you sent. In every
+             *     other case (a bare-host request, `GET /v1/sitemap/{id}` and the
+             *     webhook `data` object) it is the host the job is scoped to, as
+             *     `scheme://host`.
+             */
             url: string;
             strategy: string;
             max_depth: number;
@@ -2510,17 +2711,42 @@ export interface components {
              *     for jobs that completed before the billing node was persisted.
              */
             billing?: components["schemas"]["BillingNode"];
+            /**
+             * @description On the `202` creation response, a single entry naming the path, query
+             *     string or fragment of the submitted `url` that host-scoped discovery
+             *     ignored. It never fails the request. It is not stored with the job:
+             *     `GET /v1/sitemap/{id}` and the webhook `data` object report the
+             *     worker's own warnings, or `null`.
+             */
             warnings: string[] | null;
+            /**
+             * @description Why a `failed` job failed; `null` otherwise. One of the values below. It is typed as
+             *     a free string so that a code added later does not break a client.
+             *
+             *     - `job_timeout` — the job ran past its time limit.
+             *     - `blocked` — the host sits behind a WAF that blocks every discovery
+             *       phase, so the job did not run.
+             *     - `no_urls_found` — discovery finished with no URLs for the host.
+             *     - `internal_error` — an unexpected error while discovering.
+             *     - `worker_crash` — the job sat in `processing` far past the recovery
+             *       threshold, so it was failed as a worker crash.
+             */
             error_code: string | null;
             error_message: string | null;
             compact: boolean;
+            /** @description The `process` value from the request, echoed back. It has no effect. */
             process: Record<string, never> | null;
             metadata: Record<string, never> | null;
             /** Format: date-time */
             created_at: string;
             /** Format: date-time */
             completed_at: string | null;
-            /** Format: date-time */
+            /**
+             * Format: date-time
+             * @description When the job and its results expire: 90 days after the job completes. `null` until the
+             *     job completes, and on a failed job. A `cache: hit` response keeps the expiry of the job
+             *     that answered it.
+             */
             expires_at: string | null;
         };
         WebhookDeliveryResponse: {
@@ -2531,7 +2757,7 @@ export interface components {
              * @example bulk.completed
              * @enum {string}
              */
-            event_type: "bulk.completed" | "scrape.completed" | "scrape.failed" | "monitor.change_detected" | "monitor.captured" | "sitemap.completed" | "sitemap.failed";
+            event_type: "bulk.completed" | "scrape.completed" | "scrape.failed" | "monitor.change_detected" | "monitor.captured" | "monitor.suspended" | "sitemap.completed" | "sitemap.failed";
             target_url: string;
             /** @enum {string} */
             status: "pending" | "delivered" | "failed" | "exhausted";
@@ -2730,7 +2956,7 @@ export interface components {
                 /** @description Whether the account admin wants an email when bandwidth reaches 100 % of the plan limit. */
                 bandwidth_100_enabled: boolean;
             };
-            /** @description The Terms of Service version this account has accepted. An empty string means the account predates clickwrap acceptance (issue #1025). The dashboard diffs this against the published current version to decide whether to show the re-acceptance prompt. */
+            /** @description The Terms of Service version the calling person has accepted. The record is per person, not per account: each member of an account accepts for themselves. An empty string means this person has never accepted the Terms; acceptance is recorded only by `POST /v1/account/accept-terms`, never by bootstrap (issues #5055, #5057). The dashboard diffs this against the published current version to decide whether to show the re-acceptance prompt. */
             terms_version: string;
             /** Format: date-time */
             created_at: string;
@@ -2738,6 +2964,8 @@ export interface components {
             has_activity: boolean;
             /** @description True once a member of the account left onboarding through one of its exits (POST /v1/account/complete-onboarding). Never reset. With `has_activity` it gates the dashboard: the app shows the guided onboarding flow until either one is true, so a user whose first request failed can still reach the dashboard. */
             onboarding_completed: boolean;
+            /** @description True once the calling person left onboarding through one of its exits (POST /v1/account/complete-onboarding). Never reset. False sends this person through the guided onboarding flow even when the account itself is active or finished onboarding, so a teammate invited into an existing account still accepts the Terms and sees the API key once. */
+            user_onboarding_completed: boolean;
             /** @description True when the account has a Stripe subscription, keyed on the same `stripe_subscription_id` column that GET /v1/billing/change-plan's `no_subscription` guard tests — so a client can use it to decide whether that endpoint will answer at all. Stays TRUE while a subscription is mid-cancellation (cancelled but running to the period end): the subscription still exists and a booked plan change is still revocable. It is a boolean, not the bearer path's `subscription` object: this response has no role-dependent fields, so a non-admin member receives it too, and plan pricing does not belong there. */
             has_subscription: boolean;
         };
@@ -2768,7 +2996,7 @@ export interface components {
                 /** @description Whether the account admin wants an email when bandwidth reaches 100 % of the plan limit. */
                 bandwidth_100_enabled: boolean;
             };
-            /** @description The Terms of Service version this account has accepted. An empty string means the account predates clickwrap acceptance (issue #1025). The dashboard diffs this against the published current version to decide whether to show the re-acceptance prompt. */
+            /** @description The Terms of Service version the calling person has accepted. The record is per person, not per account: each member of an account accepts for themselves. An empty string means this person has never accepted the Terms; acceptance is recorded only by `POST /v1/account/accept-terms`, never by bootstrap (issues #5055, #5057). The dashboard diffs this against the published current version to decide whether to show the re-acceptance prompt. */
             terms_version: string;
             /** @description True when the account has a Stripe subscription, keyed on the same `stripe_subscription_id` column that GET /v1/billing/change-plan's `no_subscription` guard tests. */
             has_subscription: boolean;
@@ -2886,6 +3114,45 @@ export interface components {
                 "application/json": components["schemas"]["Error"];
             };
         };
+        /**
+         * @description Unauthorized. The request carried no valid credential, and no work was
+         *     performed. The unified `Error` envelope carries one of the codes below
+         *     in `error.code`; match on the code, never on the prose.
+         *
+         *     - `invalid_api_key` — a bearer API key was presented and rejected:
+         *       unknown, revoked, expired or malformed. The bearer-only operations
+         *       (`/v1/webhook-deliveries*` among them) also return it when no
+         *       `Authorization` header is sent. `GET /v1/account` is the exception
+         *       to "malformed": it returns `invalid_api_key` only for a key that
+         *       starts `sk_test_` or `sk_live_` and is unknown, revoked or expired.
+         *     - `unauthorized` — the `Authorization` header is absent or malformed on
+         *       an operation that also accepts a dashboard session (the dual-auth and
+         *       billing operations). `GET /v1/account` also returns it, for no
+         *       `Authorization` header and for any bearer value that does not start
+         *       `sk_test_` or `sk_live_` (that value is checked as a dashboard
+         *       session token).
+         *
+         *     Not retryable as-is: supply a valid API key first.
+         */
+        Unauthorized: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                /**
+                 * @example {
+                 *       "status": "failed",
+                 *       "error": {
+                 *         "code": "invalid_api_key",
+                 *         "message": "Missing or invalid API key.",
+                 *         "http_status": 401,
+                 *         "failed_at": "2026-01-15T12:00:00Z"
+                 *       }
+                 *     }
+                 */
+                "application/json": components["schemas"]["Error"];
+            };
+        };
     };
     parameters: {
         /**
@@ -2905,7 +3172,16 @@ export interface components {
          */
         ClientSurfaceMarker: string;
         FetchUrl: string;
+        /** @description Two-letter country code. Either case is accepted; the value is upper-cased. */
         FetchCountry: string;
+        /**
+         * @description A JSON-encoded object, URL-encoded in the query string. It is echoed back base64-encoded in
+         *     the `X-Fetch-Custom` response header so callers can correlate the response to caller-side
+         *     state. Capped at 4096 UTF-8 bytes after JSON serialization, and not part of the cache key.
+         *     A value that is not valid JSON answers `422 validation_error` ("custom must be a
+         *     JSON-encoded object"); valid JSON that is not an object is also rejected with `422`.
+         */
+        FetchCustom: string;
         FetchTimeoutMs: number;
         /** @description How long a freshly fetched URL may be served from cache. `0` skips the cache read; cache-eligible fresh results are still written with the default 7-day TTL so later non-zero-TTL callers can HIT. Safety-classified WAF husks remain live-only and are not written. Accepts `Nh` (hours, up to 168h), `Nd` (days, up to 7d), or the integer `0`. Examples: `0`, `48h`, `2d`. Invalid values receive a 422 validation_error with an actionable message. */
         FetchCacheTtl: string | 0;
@@ -2944,9 +3220,10 @@ export interface components {
         XFetchURL: string;
         /**
          * @description Byte length of the response body served on this request (integer as string) — NOT the
-         *     billing basis. The body is always the upstream response bytes, so this equals the upstream wire byte
-         *     count. Billing always reads the upstream compressed wire bytes from `X-Raw-Bytes` /
-         *     `X-Billable-Bytes`, on every path.
+         *     billing basis. When `X-Fetch-Fast-Path` is `true` the body is the upstream response
+         *     bytes, so this equals the upstream wire byte count. When it is `false` the body is the
+         *     rendered page, and this is that page's compressed size. Billing always reads the
+         *     compressed wire bytes from `X-Raw-Bytes` / `X-Billable-Bytes`, on every path.
          */
         XFetchContentLength: string;
         XFetchCreditsCharged: string;
@@ -3037,6 +3314,7 @@ export interface operations {
                     "application/json": components["schemas"]["AccountBearerResponse"] | components["schemas"]["AccountSessionResponse"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
             /** @description Rate limit exceeded (`rate_limited`). Only reachable when authenticated via Clerk session (the 60-request/60-second per-user window) — the bearer and in-process auth branches are not rate-limited at this endpoint. Carries a `Retry-After` header derived from the same clock as the window reset. */
             429: {
                 headers: {
@@ -3389,6 +3667,7 @@ export interface operations {
     createScreenshot: {
         parameters: {
             query?: {
+                /** @description Query-string spelling of the body `async` field. `true` returns the 202 immediately; any other value is ignored. */
                 async?: boolean;
             };
             header?: never;
@@ -3494,7 +3773,25 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
             402: components["responses"]["PaymentRequired"];
+            /**
+             * @description The target is on ByteKit's blocklist. Nothing is captured and nothing is billed.
+             *     The unified `Error` envelope carries one of two codes:
+             *
+             *     - `host_forbidden` — a blocked domain, any `.gov` host, or a blocked port.
+             *       `details` is `{ host }`.
+             *     - `path_forbidden` — an authentication-style path such as a login page.
+             *       `details` is `{ path }`.
+             */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
             /**
              * @description Validation error, or a screenshot that failed inside the sync hold.
              *     The two carry DIFFERENT bodies (issue #2679):
@@ -3583,6 +3880,7 @@ export interface operations {
                     "application/json": components["schemas"]["ScreenshotResponse"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
             /** @description Resource not found. */
             404: {
                 headers: {
@@ -3596,7 +3894,10 @@ export interface operations {
     };
     createScrape: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Query-string spelling of the body `async` field. `true` returns the 202 receipt immediately; any other value is ignored. Either spelling turns async on, and `false` in one never cancels `true` in the other. */
+                async?: boolean;
+            };
             header?: never;
             path?: never;
             cookie?: never;
@@ -3627,7 +3928,7 @@ export interface operations {
             };
         };
         responses: {
-            /** @description Scrape reached a terminal state and the body is that terminal envelope: `success` carrying content, or `failed` carrying the error envelope. Returned by the fast HTTP path in one round trip, and by a browser-path request without `async: true` once its render reaches a terminal state inside the hold window. A held render that ends in failure answers 200 with the same `failed` envelope `GET /v1/scrape/{id}` returns — narrow on `status` before reading the body. A definitive upstream outcome is a result, not a transport error: an unreachable host, a refused connection, or a target whose bot protection defeats every proxy tier all answer 200 with the `failed` envelope, never a 5xx. An inline failure is recorded as a failed job, so its envelope normally carries that job's `id` and polling it returns the same envelope; `id` is `null` only when recording the failed job itself failed. `error.http_status` is present only when a real upstream HTTP status is known. */
+            /** @description Scrape reached a terminal state and the body is that terminal envelope: `success` carrying content, or `failed` carrying the error envelope. Returned by the fast HTTP path in one round trip, and by a browser-path request without `async: true` or `?async=true` once its render reaches a terminal state inside the hold window. A held render that ends in failure answers 200 with the same `failed` envelope `GET /v1/scrape/{id}` returns — narrow on `status` before reading the body. A definitive upstream outcome is a result, not a transport error: an unreachable host, a refused connection, or a target whose bot protection defeats every proxy tier all answer 200 with the `failed` envelope, never a 5xx. An inline failure is recorded as a failed job, so its envelope normally carries that job's `id` and polling it returns the same envelope; `id` is `null` only when recording the failed job itself failed. `error.http_status` is present only when a real upstream HTTP status is known. */
             200: {
                 headers: {
                     /** @description Stable scrape identifier (also present on the envelope as `id`). */
@@ -3650,7 +3951,7 @@ export interface operations {
                     "X-Scrape-Status-Code"?: number;
                     /** @description Compressed wire bytes — the basis for bandwidth billing. */
                     "X-Scrape-Content-Length"?: number;
-                    /** @description Uncompressed body byte count measured before any billing multiplication. */
+                    /** @description Compressed wire byte count of the body, measured before any billing multiplication. It is not the decompressed size. */
                     "X-Raw-Bytes"?: number;
                     /** @description Chargeable bytes after applying the billing multiplier. Equals round(X-Raw-Bytes × X-Billing-Multiplier). */
                     "X-Billable-Bytes"?: number;
@@ -3678,9 +3979,9 @@ export interface operations {
                     "X-Scrape-Markdown-URL"?: string;
                     /** @description Byte length of the markdown artifact. Present only on fast-path responses when formats includes markdown. */
                     "X-Scrape-Markdown-Length"?: number;
-                    /** @description Legacy numeric form of the tier that served: 1 datacenter, 2 residential, 3 mobile. Omitted for the lean-browser tier, which has no numeric form. Deprecated — use X-Scrape-Proxy-Tier-Label. */
+                    /** @description Legacy numeric form of the tier that served: 1 datacenter, 2 residential, 3 mobile. Omitted for the lean-browser and hosted-browser tiers, which have no numeric form. Deprecated — use X-Scrape-Proxy-Tier-Label. */
                     "X-Scrape-Proxy-Tier"?: number;
-                    /** @description The proxy tier that actually served this request's fetch, after any escalation — never the tier first attempted. One of datacenter, residential, mobile, lean. Diagnostic only: it is never an input to routing, billing, caching or escalation. Present on sync fast-path responses. Omitted on a cache hit, which replayed stored bytes and ran no tier; and on responses the fast path did not serve. A third omission — a response replayed from stored bytes after this request's own cache lookup missed, which reports X-Scrape-Cache: miss and likewise ran no tier — exists only as an internal deploy-skew safeguard and is not reachable through this API. */
+                    /** @description The proxy tier that actually served this request's fetch, after any escalation — never the tier first attempted. One of datacenter, residential, mobile, lean, hosted_browser. Diagnostic only: it is never an input to routing, billing, caching or escalation. Present on sync fast-path responses. Omitted on a cache hit, which replayed stored bytes and ran no tier; and on responses the fast path did not serve. A third omission — a response replayed from stored bytes after this request's own cache lookup missed, which reports X-Scrape-Cache: miss and likewise ran no tier — exists only as an internal deploy-skew safeguard and is not reachable through this API. */
                     "X-Scrape-Proxy-Tier-Label"?: string;
                     /** @description WAF vendor detected on the target, if any (diagnostic). May be "suspected" when a low-confidence fail-open block marker was served. Omitted when no WAF is detected. */
                     "X-Scrape-Waf"?: string;
@@ -3694,7 +3995,7 @@ export interface operations {
                     "application/json": components["schemas"]["ScrapeSuccessEnvelope"] | components["schemas"]["ScrapeErrorEnvelope"];
                 };
             };
-            /** @description Scrape accepted for background processing; the body is a receipt, not content. Returned when `async: true` was requested, or when a browser-path request's hold window expired before the render finished. Poll `GET /v1/scrape/{id}` for the result. */
+            /** @description Scrape accepted for background processing; the body is a receipt, not content. Returned when `async: true` or `?async=true` was requested, or when a browser-path request's hold window expired before the render finished. Poll `GET /v1/scrape/{id}` for the result. */
             202: {
                 headers: {
                     /** @description Stable scrape identifier for the queued job. */
@@ -3730,8 +4031,12 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
             402: components["responses"]["PaymentRequired"];
-            /** @description Validation error. */
+            /**
+             * @description Validation error. A `json` format entry whose `schema` the extractor cannot take is
+             *     refused with `schema_incompatible`, before anything is drawn.
+             */
             422: {
                 headers: {
                     [name: string]: unknown;
@@ -3758,6 +4063,19 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /**
+             * @description The request carried a `json` format entry and JSON extraction is unavailable on this
+             *     deployment (`provider_unavailable`). It is refused before anything is drawn. A
+             *     terminal upstream failure is never a `503`: it is a `200` result, described above.
+             */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     getScrape: {
@@ -3774,12 +4092,47 @@ export interface operations {
             /** @description Scrape state (queued, success, or failed). */
             200: {
                 headers: {
+                    /** @description Stable scrape identifier (also present on the envelope as `id`). Present on a completed or failed scrape; absent while it is still queued or processing. */
+                    "X-Scrape-ID"?: string;
+                    /** @description Envelope status discriminator, mirrored as a header for streaming consumers. Present on a completed or failed scrape; absent while it is still queued or processing. */
+                    "X-Scrape-Status"?: "success" | "failed" | "queued";
+                    /** @description The originally requested URL, before any redirects. Present on a completed or failed scrape; absent while it is still queued or processing. */
+                    "X-Scrape-URL"?: string;
+                    /** @description Content-Type of the scraped response body. Present on a completed or failed scrape; absent while it is still queued or processing. */
+                    "X-Scrape-Content-Type"?: string;
+                    /** @description Compressed wire bytes — the basis for bandwidth billing. Present on a completed or failed scrape; absent while it is still queued or processing. */
+                    "X-Scrape-Content-Length"?: number;
+                    /** @description Credits charged for this scrape (multiplier applied to base 1.0 per format). Present on a completed or failed scrape; absent while it is still queued or processing. */
+                    "X-Scrape-Credits-Charged"?: number;
+                    /** @description Handler elapsed time in milliseconds. X-Scrape-Elapsed-Ms emits the same value on gateway slow-path responses. Present on a completed or failed scrape; absent while it is still queued or processing. */
+                    "X-Scrape-Duration-Ms"?: number;
+                    /** @description End-to-end elapsed time in milliseconds. Alias for X-Scrape-Duration-Ms; both are emitted on gateway slow-path responses. Present on a completed or failed scrape; absent while it is still queued or processing. */
+                    "X-Scrape-Elapsed-Ms"?: number;
+                    /** @description Timestamp when the scrape row was created. Present on a completed or failed scrape; absent while it is still queued or processing. */
+                    "X-Scrape-Created-At"?: string;
+                    /** @description Timestamp when the scrape completed. Omitted if not yet completed. Present on a completed or failed scrape whose row records a completion time; absent while it is still queued or processing. */
+                    "X-Scrape-Completed-At"?: string;
+                    /** @description Expiry timestamp for the scrape artifact. Omitted if no retention applies. Present on a completed or failed scrape whose row records an expiry; absent while it is still queued or processing. */
+                    "X-Scrape-Expires-At"?: string;
+                    /** @description The URL after following redirects. Present on a completed or failed scrape whose row records a final URL; absent while it is still queued or processing. */
+                    "X-Scrape-Final-URL"?: string;
+                    /** @description HTTP status code returned by the target site. Present on a completed or failed scrape whose row records a target status code; absent while it is still queued or processing. */
+                    "X-Scrape-Status-Code"?: number;
+                    /** @description Cache outcome — `hit` = served from cache, `miss` = freshly fetched, `bypass` = `cache_ttl=0` requested. On GET present only on a failed scrape whose stored cache disposition is hit, miss or bypass; a completed scrape does not carry it, nor does a queued or processing one. */
+                    "X-Scrape-Cache"?: "hit" | "miss" | "bypass";
+                    /** @description Compressed wire byte count of the body, measured before any billing multiplication. It is not the decompressed size. Present on a completed or failed scrape; absent while it is still queued or processing. */
+                    "X-Raw-Bytes"?: number;
+                    /** @description Chargeable bytes after applying the billing multiplier. Equals round(X-Raw-Bytes × X-Billing-Multiplier). Present on a completed or failed scrape; absent while it is still queued or processing. */
+                    "X-Billable-Bytes"?: number;
+                    /** @description Bandwidth cost multiplier (e.g. 1.0 for a `raw`-only scrape, 1.5 when `markdown` is also requested). Cache hits compose the endpoint format factor, which is a separate number from this one: 0.5 for an unprocessed-source scrape, 0.75 with markdown. Excludes the `clean_markdown` surcharge: when `clean_markdown: true` and the clean succeeded, the settled usage is 3× this header's value, so this header does not predict the amount you are billed. The response body's `billing` node is the authoritative surface — it DOES carry the `clean_markdown` factor, so its `multiplier` and `billed_bytes` are what you are charged. Where the two disagree, the node is correct. Present on a completed or failed scrape; absent while it is still queued or processing. */
+                    "X-Billing-Multiplier"?: number;
                     [name: string]: unknown;
                 };
                 content: {
                     "application/json": components["schemas"]["ScrapeEnvelope"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
             /** @description Resource not found. */
             404: {
                 headers: {
@@ -3970,7 +4323,38 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
             402: components["responses"]["PaymentRequired"];
+            /**
+             * @description One or more URLs in the request are on ByteKit's blocklist. The whole request is
+             *     rejected before anything is queued or billed. This body is NOT the unified `Error`
+             *     envelope: it carries no `status`, `http_status` or `failed_at`. `blocked` lists every
+             *     offending URL with the rule that matched (`domain`, `tld`, `port` or `path`) and the
+             *     code that rule maps to (`host_forbidden` for the first three, `path_forbidden` for
+             *     `path`).
+             */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: {
+                            /** @enum {string} */
+                            code: "url_forbidden";
+                            /** @example One or more URLs in this bulk request are blocked. */
+                            message: string;
+                        };
+                        blocked: {
+                            url: string;
+                            /** @enum {string} */
+                            rule_type: "domain" | "tld" | "port" | "path";
+                            /** @enum {string} */
+                            error_code: "host_forbidden" | "path_forbidden";
+                        }[];
+                    };
+                };
+            };
             /**
              * @description Validation error. `bulk_too_large` is returned when the item count
              *     exceeds the account plan's `max_bulk_size` cap (also surfaced as
@@ -4092,6 +4476,7 @@ export interface operations {
                     };
                 };
             };
+            401: components["responses"]["Unauthorized"];
             /** @description Resource not found. */
             404: {
                 headers: {
@@ -4107,10 +4492,19 @@ export interface operations {
         parameters: {
             query: {
                 url: components["parameters"]["FetchUrl"];
+                /** @description Two-letter country code. Either case is accepted; the value is upper-cased. */
                 country?: components["parameters"]["FetchCountry"];
                 timeout_ms?: components["parameters"]["FetchTimeoutMs"];
                 /** @description How long a freshly fetched URL may be served from cache. `0` skips the cache read; cache-eligible fresh results are still written with the default 7-day TTL so later non-zero-TTL callers can HIT. Safety-classified WAF husks remain live-only and are not written. Accepts `Nh` (hours, up to 168h), `Nd` (days, up to 7d), or the integer `0`. Examples: `0`, `48h`, `2d`. Invalid values receive a 422 validation_error with an actionable message. */
                 cache_ttl?: components["parameters"]["FetchCacheTtl"];
+                /**
+                 * @description A JSON-encoded object, URL-encoded in the query string. It is echoed back base64-encoded in
+                 *     the `X-Fetch-Custom` response header so callers can correlate the response to caller-side
+                 *     state. Capped at 4096 UTF-8 bytes after JSON serialization, and not part of the cache key.
+                 *     A value that is not valid JSON answers `422 validation_error` ("custom must be a
+                 *     JSON-encoded object"); valid JSON that is not an object is also rejected with `422`.
+                 */
+                custom?: components["parameters"]["FetchCustom"];
             };
             header?: never;
             path?: never;
@@ -4136,7 +4530,7 @@ export interface operations {
                     "X-Fetch-Waf-Vendor": components["headers"]["XFetchWafVendor"];
                     "X-Fetch-Content-Type": components["headers"]["XFetchContentType"];
                     "X-Fetch-Custom": components["headers"]["XFetchCustom"];
-                    /** @description Uncompressed body byte count measured before any billing multiplication. */
+                    /** @description Compressed wire byte count of the body, measured before any billing multiplication. It is not the decompressed size. */
                     "X-Raw-Bytes"?: number;
                     /** @description Chargeable bytes after applying the billing multiplier. Equals round(X-Raw-Bytes × X-Billing-Multiplier). */
                     "X-Billable-Bytes"?: number;
@@ -4163,6 +4557,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
             402: components["responses"]["PaymentRequired"];
             /**
              * @description Validation error (e.g. slow-path-only field), or a fetch that failed for a
@@ -4177,9 +4572,10 @@ export interface operations {
              *       failure, such as a host that does not resolve. This is a result about the URL,
              *       not an outage of this API, so it is a `4xx` rather than `502` or `503`. No
              *       upstream HTTP status was received, so `error.http_status` reports `422`,
-             *       mirroring what was served — unlike the relayed `upstream_error` under `502`
-             *       below, whose status is the target's own. The request transfers no billable
-             *       bytes and is charged nothing (#4669).
+             *       mirroring what was served — unlike the relayed `upstream_error` under `503`
+             *       below, whose `error.http_status` is the target's own. A target `502` or `504`
+             *       ends here too whenever it does not meet the condition for `503` below. The
+             *       request transfers no billable bytes and is charged nothing (#4669).
              */
             422: {
                 headers: {
@@ -4209,7 +4605,12 @@ export interface operations {
              *     `error.http_status` reports. Read `error.code` to tell them apart.
              *
              *     - **`upstream_error`** — the target returned HTTP `502` or `504`, relayed here as
-             *       `503`. Cloudflare fronts this API and replaces a clean origin 502 or 504 with its
+             *       `503`. This happens only when the escalation ladder ended on that answer, or when a
+             *       cached copy of it is served. A `502` or `504` is not terminal, so ByteKit first
+             *       retries it through its proxy tiers and the browser fallback; if the ladder ends any
+             *       other way, or a bot-protection vendor was seen on the way, the request answers
+             *       `422` (`upstream_error` or `blocked`) instead.
+             *       Cloudflare fronts this API and replaces a clean origin 502 or 504 with its
              *       own generic `text/plain` error page, discarding the envelope before it reaches
              *       you, while a 503 is passed through unchanged. The body's `error.http_status`
              *       still reports the **true upstream status**, `502` or `504` — not `503` — and is
@@ -4271,7 +4672,7 @@ export interface operations {
                     "X-Fetch-Waf-Vendor": components["headers"]["XFetchWafVendor"];
                     "X-Fetch-Content-Type": components["headers"]["XFetchContentType"];
                     "X-Fetch-Custom": components["headers"]["XFetchCustom"];
-                    /** @description Uncompressed body byte count measured before any billing multiplication. */
+                    /** @description Compressed wire byte count of the body, measured before any billing multiplication. It is not the decompressed size. */
                     "X-Raw-Bytes"?: number;
                     /** @description Chargeable bytes after applying the billing multiplier. Equals round(X-Raw-Bytes × X-Billing-Multiplier). */
                     "X-Billable-Bytes"?: number;
@@ -4298,6 +4699,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
             402: components["responses"]["PaymentRequired"];
             /**
              * @description Validation error (e.g. malformed JSON, unsupported fetch format, or slow-path-only
@@ -4312,9 +4714,10 @@ export interface operations {
              *       failure, such as a host that does not resolve. This is a result about the URL,
              *       not an outage of this API, so it is a `4xx` rather than `502` or `503`. No
              *       upstream HTTP status was received, so `error.http_status` reports `422`,
-             *       mirroring what was served — unlike the relayed `upstream_error` under `502`
-             *       below, whose status is the target's own. The request transfers no billable
-             *       bytes and is charged nothing (#4669).
+             *       mirroring what was served — unlike the relayed `upstream_error` under `503`
+             *       below, whose `error.http_status` is the target's own. A target `502` or `504`
+             *       ends here too whenever it does not meet the condition for `503` below. The
+             *       request transfers no billable bytes and is charged nothing (#4669).
              */
             422: {
                 headers: {
@@ -4344,7 +4747,12 @@ export interface operations {
              *     `error.http_status` reports. Read `error.code` to tell them apart.
              *
              *     - **`upstream_error`** — the target returned HTTP `502` or `504`, relayed here as
-             *       `503`. Cloudflare fronts this API and replaces a clean origin 502 or 504 with its
+             *       `503`. This happens only when the escalation ladder ended on that answer, or when a
+             *       cached copy of it is served. A `502` or `504` is not terminal, so ByteKit first
+             *       retries it through its proxy tiers and the browser fallback; if the ladder ends any
+             *       other way, or a bot-protection vendor was seen on the way, the request answers
+             *       `422` (`upstream_error` or `blocked`) instead.
+             *       Cloudflare fronts this API and replaces a clean origin 502 or 504 with its
              *       own generic `text/plain` error page, discarding the envelope before it reaches
              *       you, while a 503 is passed through unchanged. The body's `error.http_status`
              *       still reports the **true upstream status**, `502` or `504` — not `503` — and is
@@ -4459,7 +4867,38 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
             402: components["responses"]["PaymentRequired"];
+            /**
+             * @description One or more URLs in the request are on ByteKit's blocklist. The whole request is
+             *     rejected before anything is queued or billed. This body is NOT the unified `Error`
+             *     envelope: it carries no `status`, `http_status` or `failed_at`. `blocked` lists every
+             *     offending URL with the rule that matched (`domain`, `tld`, `port` or `path`) and the
+             *     code that rule maps to (`host_forbidden` for the first three, `path_forbidden` for
+             *     `path`).
+             */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: {
+                            /** @enum {string} */
+                            code: "url_forbidden";
+                            /** @example One or more URLs in this bulk request are blocked. */
+                            message: string;
+                        };
+                        blocked: {
+                            url: string;
+                            /** @enum {string} */
+                            rule_type: "domain" | "tld" | "port" | "path";
+                            /** @enum {string} */
+                            error_code: "host_forbidden" | "path_forbidden";
+                        }[];
+                    };
+                };
+            };
             /**
              * @description Validation error. `bulk_too_large` is returned when the item count
              *     exceeds the account plan's `max_bulk_size` cap (also surfaced as
@@ -4677,6 +5116,7 @@ export interface operations {
                     };
                 };
             };
+            401: components["responses"]["Unauthorized"];
             /** @description Resource not found. */
             404: {
                 headers: {
@@ -4738,6 +5178,7 @@ export interface operations {
                     };
                 };
             };
+            401: components["responses"]["Unauthorized"];
             /** @description Validation error. Returned when `status` is not one of the documented values, or when `cursor` is not a cursor this endpoint issued. */
             422: {
                 headers: {
@@ -4973,7 +5414,38 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
             402: components["responses"]["PaymentRequired"];
+            /**
+             * @description One or more URLs in the request are on ByteKit's blocklist. The whole request is
+             *     rejected before anything is queued or billed. This body is NOT the unified `Error`
+             *     envelope: it carries no `status`, `http_status` or `failed_at`. `blocked` lists every
+             *     offending URL with the rule that matched (`domain`, `tld`, `port` or `path`) and the
+             *     code that rule maps to (`host_forbidden` for the first three, `path_forbidden` for
+             *     `path`).
+             */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: {
+                            /** @enum {string} */
+                            code: "url_forbidden";
+                            /** @example One or more URLs in this bulk request are blocked. */
+                            message: string;
+                        };
+                        blocked: {
+                            url: string;
+                            /** @enum {string} */
+                            rule_type: "domain" | "tld" | "port" | "path";
+                            /** @enum {string} */
+                            error_code: "host_forbidden" | "path_forbidden";
+                        }[];
+                    };
+                };
+            };
             /**
              * @description Validation error. `bulk_too_large` is returned when the item count
              *     exceeds the account plan's `max_bulk_size` cap (also surfaced as
@@ -5079,6 +5551,7 @@ export interface operations {
                     };
                 };
             };
+            401: components["responses"]["Unauthorized"];
             /** @description Resource not found. */
             404: {
                 headers: {
@@ -5133,6 +5606,7 @@ export interface operations {
                     };
                 };
             };
+            401: components["responses"]["Unauthorized"];
             /** @description Resource not found. */
             404: {
                 headers: {
@@ -5254,6 +5728,7 @@ export interface operations {
                     };
                 };
             };
+            401: components["responses"]["Unauthorized"];
         };
     };
     listMonitors: {
@@ -5283,6 +5758,7 @@ export interface operations {
                     };
                 };
             };
+            401: components["responses"]["Unauthorized"];
         };
     };
     createMonitor: {
@@ -5327,6 +5803,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
             /** @description Duplicate monitor for this URL. */
             409: {
                 headers: {
@@ -5367,6 +5844,7 @@ export interface operations {
                     "application/json": components["schemas"]["MonitorResponse"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
             /** @description Resource not found. */
             404: {
                 headers: {
@@ -5396,6 +5874,7 @@ export interface operations {
                 };
                 content?: never;
             };
+            401: components["responses"]["Unauthorized"];
             /** @description Resource not found. */
             404: {
                 headers: {
@@ -5451,6 +5930,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
             /** @description Resource not found. */
             404: {
                 headers: {
@@ -5508,6 +5988,7 @@ export interface operations {
                     };
                 };
             };
+            401: components["responses"]["Unauthorized"];
         };
     };
     createSitemap: {
@@ -5551,7 +6032,25 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
             402: components["responses"]["PaymentRequired"];
+            /**
+             * @description The target is on ByteKit's blocklist. Nothing is queued and nothing is billed.
+             *     The unified `Error` envelope carries one of two codes:
+             *
+             *     - `host_forbidden` — a blocked domain, any `.gov` host, or a blocked port.
+             *       `details` is `{ host }`.
+             *     - `path_forbidden` — an authentication-style path such as a login page.
+             *       `details` is `{ path }`.
+             */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
             /** @description Validation error. */
             422: {
                 headers: {
@@ -5600,6 +6099,7 @@ export interface operations {
                     "application/json": components["schemas"]["SitemapResponse"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
             /** @description Resource not found. */
             404: {
                 headers: {
@@ -5639,7 +6139,7 @@ export interface operations {
                  *     }
                  */
                 "application/json": {
-                    /** @description The search query. */
+                    /** @description The search query, up to 2048 characters. */
                     query: string;
                     /**
                      * @description Which search index to query. `web` (default) returns ranked organic results; `news` returns news articles in the same `results` array, additionally populating `source` and `image` on each item; `images` returns image results, populating `source`, `domain`, and a fuller `image` object (full-image dimensions plus a thumbnail URL and dimensions) while omitting `snippet` and `date`. Billing is identical for all three.
@@ -5756,6 +6256,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
             402: components["responses"]["PaymentRequired"];
             /** @description Rate limit exceeded (`rate_limited`). Carries the `X-RateLimit-Limit`/`X-RateLimit-Remaining`/`X-RateLimit-Reset` triplet and a `Retry-After` header. The window is per-second for a bearer API key, or the 60-request/60-second Clerk session window when authenticated via `resolveDualAuth` — `Retry-After` reflects whichever window applies to the request. */
             429: {
@@ -5780,25 +6281,28 @@ export interface operations {
                 };
             };
             /**
-             * @description Upstream search provider error, answered at `503` rather than `502` because
-             *     Cloudflare replaces an origin 502 body with its own page (#4891). The body is a fixed,
-             *     vendor-masked shape — deliberately NOT the unified `Error`
-             *     envelope. The upstream provider's identity and message are
-             *     never surfaced, so the response carries only the constant
-             *     `error` code `search_provider_error`.
+             * @description Two different bodies travel under this status. Tell them apart by the
+             *     type of the top-level `error` key: a string is the first, an object
+             *     is the second.
+             *
+             *     - **Upstream search provider error**, answered at `503` rather than
+             *       `502` because Cloudflare replaces an origin 502 body with its own
+             *       page (#4891). The body is a fixed, vendor-masked shape —
+             *       deliberately NOT the unified `Error` envelope. The upstream
+             *       provider's identity and message are never surfaced, so the
+             *       response carries only the constant `error` code
+             *       `search_provider_error`.
+             *     - **Billing entitlement unavailable** (`billing_entitlement_missing`),
+             *       raised before any search runs, when the account has a Stripe
+             *       subscription but its plan could not be resolved. This one is the
+             *       unified `Error` envelope. No search is run and nothing is charged.
              */
             503: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": {
-                        /**
-                         * @description Fixed vendor-masked error code. Always `search_provider_error`; the upstream provider's identity and failure detail are withheld by design.
-                         * @enum {string}
-                         */
-                        error: "search_provider_error";
-                    };
+                    "application/json": components["schemas"]["CreateSearchResponse503"] | components["schemas"]["Error"];
                 };
             };
         };
@@ -5836,7 +6340,7 @@ export interface operations {
                      * @description Target page URL (HTTP/HTTPS, SSRF-blocked, fast-path only).
                      */
                     url: string;
-                    /** @description JSON Schema (draft 2020-12) describing the desired output. Serialized size ≤ 50 KB, nesting depth ≤ 8, must compile under Ajv, and must be normalizable into Groq's strict-mode subset (root `type: object`; no `pattern`/`format`/`if`/`then`/`else`/ top-level `oneOf`/`anyOf`; `$ref` limited to `#/$defs`). A non-normalizable schema returns `422 schema_incompatible`. */
+                    /** @description JSON Schema (draft 2020-12) describing the desired output. Serialized size ≤ 50 KB, nesting depth ≤ 8, must compile under Ajv, and must be normalizable into Groq's strict-mode subset: root `type: object`, and only an allowlist of keywords at any depth — `type`, `properties`, `required`, `additionalProperties`, `items`, `enum`, `$defs`, `$ref`, `description`, `title` and `default` (`$ref` limited to `#/$defs`). Every other keyword, such as `pattern`, `format`, `minimum`, `maxLength`, `const`, `oneOf`, `anyOf`, `allOf` or `if`/`then`/`else`, returns `422 schema_incompatible`. */
                     schema: Record<string, never>;
                     /** @description Optional natural-language extraction hint. */
                     prompt?: string;
@@ -5860,7 +6364,10 @@ export interface operations {
                      * @default US
                      */
                     country?: string | null;
-                    /** @default null */
+                    /**
+                     * @description Accepted and forwarded to the extraction service, which does not read it: it currently has no effect.
+                     * @default null
+                     */
                     language?: string | null;
                 };
             };
@@ -5893,7 +6400,7 @@ export interface operations {
                             status_code: number | null;
                             /** @description Upstream wire bytes — the bandwidth billing basis. */
                             content_length: number;
-                            /** @description True when markdown exceeded the LLM token budget and was tail-truncated. */
+                            /** @description True when the page sent to the LLM, the structured metadata (JSON-LD and meta tags) plus the markdown, exceeded the token budget and was cut to fit. */
                             truncated: boolean;
                         };
                         /** @description Additive warning codes, e.g. `content_truncated`, `extract_validation_failed`, `exhausted_retries`, `model_refusal`, `empty_extraction`. */
@@ -5910,18 +6417,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Missing or invalid bearer key. */
-            401: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["Error"];
-                };
-            };
+            401: components["responses"]["Unauthorized"];
             402: components["responses"]["PaymentRequired"];
-            /** @description Endpoint not available (feature flag disabled). */
-            404: {
+            /**
+             * @description Validation error (`validation_error`), non-normalizable schema (`schema_incompatible`),
+             *     or the fetched page's HTML could not be converted for extraction — over the size cap or
+             *     past the conversion deadline (`content_too_large`). On `content_too_large` the page's
+             *     bandwidth is billed and the credits are refunded.
+             */
+            422: {
                 headers: {
                     [name: string]: unknown;
                 };
@@ -5929,8 +6433,8 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Validation error (`validation_error`) or non-normalizable schema (`schema_incompatible`). */
-            422: {
+            /** @description Per-account rate limit (`rate_limited`) or upstream provider rate limit (`provider_rate_limited`); a `Retry-After` header may be present. */
+            429: {
                 headers: {
                     [name: string]: unknown;
                 };
@@ -5938,8 +6442,11 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Per-account rate limit (`rate_limited`) or upstream provider rate limit (`provider_rate_limited`); a `Retry-After` header may be present. */
-            429: {
+            /**
+             * @description Internal error (`internal_error`): the request could not be recorded, or its
+             *     bandwidth charge could not be reserved. The credits held for it are refunded.
+             */
+            500: {
                 headers: {
                     [name: string]: unknown;
                 };
@@ -6041,6 +6548,7 @@ export interface operations {
                     };
                 };
             };
+            401: components["responses"]["Unauthorized"];
         };
     };
     getUsageDaily: {
@@ -6109,6 +6617,7 @@ export interface operations {
                     };
                 };
             };
+            401: components["responses"]["Unauthorized"];
         };
     };
     getUsageByEndpoint: {
@@ -6156,6 +6665,7 @@ export interface operations {
                     };
                 };
             };
+            401: components["responses"]["Unauthorized"];
         };
     };
     getLogs: {
@@ -6239,6 +6749,7 @@ export interface operations {
                     };
                 };
             };
+            401: components["responses"]["Unauthorized"];
         };
     };
     createCheckout: {
@@ -6253,23 +6764,23 @@ export interface operations {
                 "application/json": {
                     /** @enum {string} */
                     plan: "starter" | "growth" | "scale";
-                    /** Format: uri */
-                    success_url: string;
-                    /** Format: uri */
-                    cancel_url: string;
+                    /**
+                     * Format: uri
+                     * @description Where Stripe sends the user back if their bank requires leaving the page to authenticate the payment.
+                     */
+                    return_url: string;
                 };
             };
         };
         responses: {
-            /** @description Successful response. */
+            /** @description Checkout session created; pay it in-page with its client secret. */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
                     "application/json": {
-                        /** Format: uri */
-                        checkout_url: string;
+                        client_secret: string;
                         session_id: string;
                     };
                 };
@@ -6283,9 +6794,52 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
         };
     };
     createPortal: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            401: components["responses"]["Unauthorized"];
+            /** @description The portal is retired; manage billing at /settings/billing. */
+            410: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    registerPayg: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            401: components["responses"]["Unauthorized"];
+            /** @description Card setup moved to POST /v1/billing/payment-methods/setup. */
+            410: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    createTopup: {
         parameters: {
             query?: never;
             header?: never;
@@ -6295,27 +6849,33 @@ export interface operations {
         requestBody: {
             content: {
                 "application/json": {
-                    /** @enum {string} */
-                    purpose: "payment_method_update" | "invoice_history" | "subscription_cancel";
-                    /** Format: uri */
+                    /**
+                     * @description Amount to deposit, in US cents. Allowed amounts — $10, $25, $50, $100, $500. Charged exactly; the plan rate prices usage, not the deposit.
+                     * @enum {integer}
+                     */
+                    amount_cents: 1000 | 2500 | 5000 | 10000 | 50000;
+                    /**
+                     * Format: uri
+                     * @description Where Stripe sends the user back if their bank requires leaving the page to authenticate the payment.
+                     */
                     return_url: string;
                 };
             };
         };
         responses: {
-            /** @description Successful response. */
+            /** @description Checkout session created; pay it in-page with its client secret. */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
                     "application/json": {
-                        /** Format: uri */
-                        portal_url: string;
+                        client_secret: string;
+                        session_id: string;
                     };
                 };
             };
-            /** @description No Stripe customer linked. */
+            /** @description No customer or free plan. */
             400: {
                 headers: {
                     [name: string]: unknown;
@@ -6324,8 +6884,18 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Cancellation disclosure revision is absent or stale. */
-            409: {
+            401: components["responses"]["Unauthorized"];
+            /** @description Validation error (missing/invalid fields). */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description Stripe error creating the Checkout session (`stripe_error`). Answered at `503`, not `502`, because Cloudflare replaces an origin 502 body with its own page (#4891). */
+            503: {
                 headers: {
                     [name: string]: unknown;
                 };
@@ -6335,21 +6905,14 @@ export interface operations {
             };
         };
     };
-    registerPayg: {
+    getCancellation: {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        requestBody: {
-            content: {
-                "application/json": {
-                    /** Format: uri */
-                    return_url: string;
-                };
-            };
-        };
+        requestBody?: never;
         responses: {
             /** @description Successful response. */
             200: {
@@ -6358,13 +6921,17 @@ export interface operations {
                 };
                 content: {
                     "application/json": {
-                        /** Format: uri */
-                        checkout_url: string;
-                        session_id: string;
+                        /** @description Whether the plan ends at the period end instead of renewing. */
+                        cancel_at_period_end: boolean;
+                        /**
+                         * Format: date-time
+                         * @description When the paid period ends, read from the plan's subscription item.
+                         */
+                        current_period_end: string | null;
                     };
                 };
             };
-            /** @description Already registered. */
+            /** @description No subscription (`no_subscription`). */
             400: {
                 headers: {
                     [name: string]: unknown;
@@ -6373,51 +6940,54 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
+            /** @description The caller is not an account admin (`forbidden`). */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description The Stripe subscription could not be read (`stripe_error`). Answered at `503`, not `502`, because Cloudflare replaces an origin 502 body with its own page (#4891). */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
-    createTopup: {
+    cancelSubscription: {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        requestBody: {
-            content: {
-                "application/json": {
-                    /**
-                     * @description Amount to deposit, in US cents. Allowed amounts — $10, $25, $50, $100, $500. Charged exactly; the plan rate prices usage, not the deposit.
-                     * @enum {integer}
-                     */
-                    amount_cents: 1000 | 2500 | 5000 | 10000 | 50000;
-                    /**
-                     * Format: uri
-                     * @description Redirect target after a completed Checkout.
-                     */
-                    success_url: string;
-                    /**
-                     * Format: uri
-                     * @description Redirect target when the user abandons Checkout.
-                     */
-                    cancel_url: string;
-                };
-            };
-        };
+        requestBody?: never;
         responses: {
-            /** @description Hosted Checkout session created. */
+            /** @description The plan now ends at the period end. */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
                     "application/json": {
-                        /** Format: uri */
-                        checkout_url: string;
-                        session_id: string;
+                        /** @description Whether the plan ends at the period end instead of renewing. */
+                        cancel_at_period_end: boolean;
+                        /**
+                         * Format: date-time
+                         * @description When the paid period ends, read from the plan's subscription item.
+                         */
+                        current_period_end: string | null;
                     };
                 };
             };
-            /** @description No customer or free plan. */
+            /** @description No subscription (`no_subscription`). */
             400: {
                 headers: {
                     [name: string]: unknown;
@@ -6426,8 +6996,9 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Validation error (missing/invalid fields). */
-            422: {
+            401: components["responses"]["Unauthorized"];
+            /** @description The caller is not an account admin (`forbidden`). */
+            403: {
                 headers: {
                     [name: string]: unknown;
                 };
@@ -6435,7 +7006,16 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Stripe error creating the Checkout session (`stripe_error`). Answered at `503`, not `502`, because Cloudflare replaces an origin 502 body with its own page (#4891). */
+            /** @description Cancellation disclosure revision is absent or stale (`billing_disclosure_stale`). The current revision is in the `Billing-Disclosure-Revision` response header. */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description Stripe refused or failed the cancellation (`stripe_error`). Answered at `503`, not `502`, because Cloudflare replaces an origin 502 body with its own page (#4891). */
             503: {
                 headers: {
                     [name: string]: unknown;
@@ -6446,23 +7026,53 @@ export interface operations {
             };
         };
     };
-    cancelSubscription: {
+    keepSubscription: {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        requestBody: {
-            content: {
-                "application/json": {
-                    reason?: string;
+        requestBody?: never;
+        responses: {
+            /** @description The plan renews at the period end. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @description Whether the plan ends at the period end instead of renewing. */
+                        cancel_at_period_end: boolean;
+                        /**
+                         * Format: date-time
+                         * @description When the paid period ends, read from the plan's subscription item.
+                         */
+                        current_period_end: string | null;
+                    };
                 };
             };
-        };
-        responses: {
-            /** @description Cancellation moved to hosted Billing Portal. */
-            410: {
+            /** @description No subscription (`no_subscription`). */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            /** @description The caller is not an account admin (`forbidden`). */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description Stripe refused or failed the change (`stripe_error`). Answered at `503`, not `502`, because Cloudflare replaces an origin 502 body with its own page (#4891). */
+            503: {
                 headers: {
                     [name: string]: unknown;
                 };
@@ -6507,6 +7117,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
             /** @description The Stripe subscription schedule could not be read (`stripe_error`). Answered at `503`, not `502`, because Cloudflare replaces an origin 502 body with its own page (#4891). */
             503: {
                 headers: {
@@ -6567,6 +7178,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
         };
     };
     revokePlanChange: {
@@ -6601,6 +7213,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
         };
     };
     listInvoices: {
@@ -6635,6 +7248,7 @@ export interface operations {
                             invoice_pdf: string | null;
                             hosted_invoice_url: string | null;
                         }[];
+                        /** @description True when older invoices exist after this page. */
                         has_more: boolean;
                     };
                 };
@@ -6648,6 +7262,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
         };
     };
     getTopupBalance: {
@@ -6703,6 +7318,7 @@ export interface operations {
                     };
                 };
             };
+            401: components["responses"]["Unauthorized"];
         };
     };
     updateAutoTopup: {
@@ -6749,6 +7365,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
         };
     };
     createPaymentMethodSetup: {
@@ -6778,6 +7395,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
         };
     };
     listPaymentMethods: {
@@ -6809,6 +7427,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
         };
     };
     setDefaultPaymentMethod: {
@@ -6840,6 +7459,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
             /** @description Payment method not found. */
             404: {
                 headers: {
@@ -6889,6 +7509,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
             /** @description Payment method not found. */
             404: {
                 headers: {
@@ -6984,6 +7605,7 @@ export interface operations {
                     };
                 };
             };
+            401: components["responses"]["Unauthorized"];
         };
     };
     retryWebhookDelivery: {
@@ -7018,6 +7640,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            401: components["responses"]["Unauthorized"];
             /** @description Delivery not found or not in a retryable state. */
             404: {
                 headers: {
@@ -7110,11 +7733,11 @@ export interface operations {
             path?: never;
             cookie?: never;
         };
-        /** @description Optional clickwrap acceptance signal (issue #1025). When present, terms_version MUST equal the published current version or the request is rejected with 400 terms_version_mismatch. When absent, the server stamps the current version server-side (back-compatible). */
+        /** @description Optional Terms version guard (issue #1025). When present, terms_version MUST equal the published current version or the request is rejected with 400 terms_version_mismatch. It is never recorded as acceptance: a new account starts with an empty terms_version, and acceptance is recorded only by POST /v1/account/accept-terms. When absent, the guard is skipped (back-compatible). */
         requestBody?: {
             content: {
                 "application/json": {
-                    /** @description The Terms of Service version the user is accepting. */
+                    /** @description The Terms of Service version the client was built against. Checked against the current version, never recorded as acceptance. */
                     terms_version?: string;
                 };
             };
@@ -7138,7 +7761,7 @@ export interface operations {
                     "application/json": components["schemas"]["Account"];
                 };
             };
-            /** @description terms_version does not match the published current version. */
+            /** @description terms_version does not match the published current version (version guard only; acceptance is recorded by POST /v1/account/accept-terms). */
             400: {
                 headers: {
                     [name: string]: unknown;