serpkite 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -341,10 +341,19 @@ interface paths {
         get?: never;
         put?: never;
         /**
-         * Up to 20 URLs (HTML or PDF) as Markdown, text or HTML, with query-ranked highlights, links and images (1 credit per URL read)
+         * Up to 20 URLs (HTML or PDF) as Markdown, text or HTML, with query-ranked highlights, links, images, an AI summary or JSON extracted with a schema (1 credit per URL read)
          * @description Every URL is billed only when it comes back: 1 credit, 0.5 from cache. URLs that
          *     fail are listed in `failed` and cost nothing. The response is `200` even when every
          *     URL failed. Highlights are ranked with BM25 (lexical, no model).
+         *
+         *     **AI:** `summary: true` adds a 3–6 sentence summary of each page (+4 credits per
+         *     page); `output_schema` (a JSON Schema, at most 16 KB, optionally guided by
+         *     `prompt`) returns each page's data as JSON in `output` (+4 credits per page).
+         *     Claude Haiku writes both; a schema whose fields are all booleans or enums is
+         *     answered by a decision model instead (always valid against the schema). A
+         *     summary or extraction that fails is reported in `summary_error` /
+         *     `output_error` and not charged. With either, `timeout` defaults to 75 seconds
+         *     and the last 25 are kept for the model.
          */
         post: operations["extract"];
         delete?: never;
@@ -437,6 +446,106 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/answer": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * A cited answer grounded on live Google results, written by Claude (fast = 1 + 2 credits; standard = 1 + 1 per page read + 4)
+         * @description Runs the query on Google, then Claude (Haiku by default) writes a concise answer
+         *     that cites the numbered `results` with `[n]` markers. `depth=fast` answers from
+         *     the result page (snippets, answer box, knowledge panel); `depth=standard`
+         *     (default) also reads the top `num_sources` pages and answers from their
+         *     query-ranked passages. Sources are untrusted: instructions inside pages are
+         *     ignored.
+         *
+         *     **Billing:** the search part is priced like `/v1/search` with `include_content`
+         *     (1 credit + 1 per page read, cache rules as usual); the model adds 2 credits at
+         *     `fast` and 4 when it read pages (`standard`; 2 if no page could be read).
+         *     `meta.credits` splits the two. When the model fails the answer part is refunded
+         *     (`503 ai_unavailable`); a search that returned nothing to answer from is answered
+         *     with `answer: null`, a warning, and no model charge.
+         *
+         *     **Structured output:** with `output_schema` (a JSON Schema, at most 16 KB) the
+         *     answer is a JSON value in `output` (and `answer` is null). Can't be combined
+         *     with `stream`.
+         *
+         *     **Streaming:** `stream: true` returns `text/event-stream` with these events, in
+         *     order: `results` (`{request, results}`), `delta` (`{text}`, repeated), then
+         *     `done` (`{answer, citations, meta}`) or `error` (`{error}`). Billing headers on a
+         *     stream carry the search part only; the final `meta` has the total.
+         */
+        post: operations["answer"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/research": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Start an async deep-research task — planned searches, page reading, a cited Markdown report written by Claude (lite 30, standard 75, deep 200 credits)
+         * @description Claude plans Google queries for `input`, the pages they find are read and
+         *     ranked, a decision model checks whether the notes already cover the task (and
+         *     drops off-topic sources), Claude reviews gaps and plans follow-up rounds, then
+         *     writes a Markdown report citing numbered sources (and, with `output_schema`, a
+         *     JSON value in `output`).
+         *
+         *     | effort | credits | first-round queries | rounds | pages per query |
+         *     |---|---:|---:|---:|---:|
+         *     | lite | 30 | 3 | 1 | 2 |
+         *     | standard | 75 | 5 | 2 | 3 |
+         *     | deep | 200 | 8 | 3 | 4 |
+         *
+         *     The flat price is reserved at enqueue and charged only when the report is
+         *     written; failed research is refunded. A canceled task is charged 1 credit per
+         *     search already run. Returns `202`; poll `GET /v1/research/{id}` or wait for the
+         *     signed `research.completed` webhook. At most 20 crawl and research tasks per
+         *     account may be queued or running at once (`429`).
+         */
+        post: operations["createResearch"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/research/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        /** Poll a research task (kept for 24 hours) */
+        get: operations["getResearch"];
+        put?: never;
+        post?: never;
+        /**
+         * Cancel a research task. A queued task is refunded at once; a running one stops at its next round and is charged for the searches run
+         * @description `404` when there is no such task, `409` when it already finished.
+         */
+        delete: operations["cancelResearch"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/monitors": {
         parameters: {
             query?: never;
@@ -604,7 +713,8 @@ interface paths {
          * @description Credits for the whole batch are reserved together: if the balance, spend cap, key limit or
          *     free daily cap can't cover every valid request, none is queued and each gets the error
          *     (invalid requests get their own 400 entry either way). Each job is settled and refunded on
-         *     its own once it runs.
+         *     its own once it runs. Half price applies to the search part; an AI surcharge
+         *     (`include_answer`) is charged in full.
          *
          *     **Retries.** Send an `Idempotency-Key` to make the call safe to retry: for 24 hours a
          *     repeat with the same key and the same body returns the first response (with
@@ -848,9 +958,9 @@ interface components {
             /** @description Accept a cached result up to this many seconds old (50% of credits on a hit) */
             max_age?: number;
             engine?: components["schemas"]["EngineParam"];
-            /** @description Only results from these domains (search, news, images, videos). Compiled into site: operators and enforced on the results. Not with engine=consensus */
+            /** @description Only results from these domains (search, news, images, videos). Compiled into site: operators and enforced on the results. With engine=consensus, every provider gets the operators and only providers with a remaining result are billed */
             include_domains?: components["schemas"]["DomainList"];
-            /** @description Drop results from these domains (search, news, images, videos). Not with engine=consensus */
+            /** @description Drop results from these domains (search, news, images, videos) */
             exclude_domains?: components["schemas"]["DomainList"];
             /** @description Move results from these domains to the top, keeping the order within both groups (search, news) */
             boost_domains?: components["schemas"]["DomainList"];
@@ -869,6 +979,11 @@ interface components {
              * @default false
              */
             highlights?: boolean;
+            /**
+             * @description Add a cited AI `answer` written by Claude over this response's results (search and news; +2 credits, +4 when it read pages via `include_content`; refunded with a `meta.warnings` entry when the model fails)
+             * @default false
+             */
+            include_answer?: boolean;
         };
         /** @description Domains as an array or a comma-separated string, at most 20: a host (`example.com`, subdomains match), a host with a path prefix (`github.com/org`) or a TLD (`.gov`). */
         DomainList: string | string[];
@@ -991,10 +1106,21 @@ interface components {
             /** @description Fetch through an exit in this country (ISO 3166-1 alpha-2) */
             country?: string;
             /**
-             * @description Seconds to wait for the pages; a page still loading is listed in `failed` (`upstream_timeout`, not charged)
+             * @description Seconds to wait for the pages; a page still loading is listed in `failed` (`upstream_timeout`, not charged). Default 75 with summary or output_schema
              * @default 50
              */
             timeout?: number;
+            /**
+             * @description Add a 3-6 sentence AI summary of each page (+4 credits per page; focused on `query` when set)
+             * @default false
+             */
+            summary?: boolean;
+            /** @description A JSON Schema (at most 16 KB): each page's data is returned as JSON matching it in `output` (+4 credits per page) */
+            output_schema?: {
+                [key: string]: unknown;
+            };
+            /** @description Guides output_schema extraction (what to pick, how to normalise); needs output_schema */
+            prompt?: string;
         };
         ExtractResult: {
             /** @description Final URL after redirects */
@@ -1017,6 +1143,12 @@ interface components {
             images?: string[];
             /** @description highlights > 0 only */
             highlights?: components["schemas"]["Highlight"][];
+            /** @description summary=true only (null when it failed) */
+            summary?: string | null;
+            summary_error?: string;
+            /** @description output_schema only: the JSON value matching the schema (null when it failed) */
+            output?: unknown;
+            output_error?: string;
         };
         ExtractFailure: {
             url: string;
@@ -1049,8 +1181,189 @@ interface components {
                 latency_ms?: number;
                 succeeded: number;
                 failed: number;
+                llm?: components["schemas"]["LLMUsage"];
             };
         };
+        AnswerRequest: {
+            q: string;
+            /**
+             * @description `fast` answers from the result page (1 + 2 credits); `standard` also reads the top `num_sources` pages (1 + 1 per page + 4 credits)
+             * @default standard
+             * @enum {string}
+             */
+            depth?: "fast" | "standard";
+            /**
+             * @description Pages read (depth=standard only)
+             * @default 3
+             */
+            num_sources?: number;
+            /**
+             * @description Send Server-Sent Events (`results`, `delta`…, `done` | `error`) instead of one JSON body
+             * @default false
+             */
+            stream?: boolean;
+            /** @description A JSON Schema (at most 16 KB). The answer becomes a JSON value in `output`. Not with stream */
+            output_schema?: {
+                [key: string]: unknown;
+            };
+            /** @default us */
+            country?: string;
+            /** @default en */
+            language?: string;
+            location?: string;
+            uule?: string;
+            /** @enum {string} */
+            time?: "hour" | "day" | "week" | "month" | "year";
+            tbs?: string;
+            /**
+             * @default desktop
+             * @enum {string}
+             */
+            device?: "desktop" | "mobile";
+            /**
+             * @default off
+             * @enum {string}
+             */
+            safe?: "active" | "off";
+            /** @default true */
+            autocorrect?: boolean;
+            /** @description Accept a cached search up to this many seconds old */
+            max_age?: number;
+            engine?: components["schemas"]["EngineParam"];
+            include_domains?: components["schemas"]["DomainList"];
+            exclude_domains?: components["schemas"]["DomainList"];
+            boost_domains?: components["schemas"]["DomainList"];
+            /** Format: date */
+            start_date?: string;
+            /** Format: date */
+            end_date?: string;
+        };
+        /** @description A result the answer may cite, numbered as in the prompt (`[index]`) */
+        AnswerSource: {
+            index: number;
+            title: string;
+            link: string;
+            domain?: string;
+            /** @description Publish date (ISO 8601 when known, else as shown) */
+            date?: string;
+        };
+        AnswerMeta: components["schemas"]["Meta"] & {
+            /** @description `credits_used` split into the search and the model part */
+            credits?: {
+                search?: number;
+                answer?: number;
+            };
+        };
+        AnswerResponse: {
+            request: components["schemas"]["RequestEcho"];
+            /** @description Markdown with `[n]` citation markers. Null with output_schema, or when there was nothing to answer from */
+            answer: string | null;
+            /** @description output_schema only: the JSON value matching the schema */
+            output?: unknown;
+            /** @description The sources the answer cites, in first-cited order */
+            citations: components["schemas"]["Citation"][];
+            results: components["schemas"]["AnswerSource"][];
+            meta: components["schemas"]["AnswerMeta"];
+        };
+        /** @description `event: results`, sent first */
+        AnswerStreamResults: {
+            request: components["schemas"]["RequestEcho"];
+            results: components["schemas"]["AnswerSource"][];
+        };
+        /** @description `event: delta`: the next piece of answer text */
+        AnswerStreamDelta: {
+            text: string;
+        };
+        /** @description `event: done`, sent last: the final answer (citation markers checked) and meta with the total credits */
+        AnswerStreamDone: {
+            answer: string;
+            citations: components["schemas"]["Citation"][];
+            meta: components["schemas"]["AnswerMeta"];
+        };
+        ResearchRequest: {
+            /** @description The research task in plain words (`q` is accepted as an alias) */
+            input: string;
+            /**
+             * @description lite = 30, standard = 75, deep = 200 credits
+             * @default standard
+             * @enum {string}
+             */
+            effort?: "lite" | "standard" | "deep";
+            /** @description A JSON Schema (at most 16 KB); the report is also returned as a JSON value in `result.output` */
+            output_schema?: {
+                [key: string]: unknown;
+            };
+            country?: string;
+            language?: string;
+            include_domains?: string[];
+            exclude_domains?: string[];
+            /**
+             * Format: uri
+             * @description Receives the signed `research.completed` event. Defaults to the account webhook
+             */
+            webhook_url?: string;
+        };
+        ResearchSource: {
+            index: number;
+            title: string;
+            link: string;
+            domain?: string;
+            published_at?: string;
+            /** @description The query that found it */
+            query?: string;
+        };
+        ResearchResult: {
+            input: string;
+            /** @enum {string} */
+            effort: "lite" | "standard" | "deep";
+            /** @description Markdown report with `[n]` citation markers */
+            report: string;
+            citations: components["schemas"]["Citation"][];
+            sources: components["schemas"]["ResearchSource"][];
+            /** @description Every search the research ran */
+            queries: string[];
+            stats?: {
+                searches?: number;
+                sources?: number;
+                rounds?: number;
+            };
+            llm?: components["schemas"]["LLMUsage"];
+            /** @description output_schema only: the JSON value (null when it could not be produced) */
+            output?: unknown;
+            output_error?: string;
+        };
+        ResearchTask: {
+            /** Format: uuid */
+            id: string;
+            /** @constant */
+            kind: "research";
+            status: components["schemas"]["TaskStatus"];
+            /** Format: date-time */
+            created_at: string;
+            /** Format: date-time */
+            started_at?: string | null;
+            /** Format: date-time */
+            completed_at?: string | null;
+            credits_reserved: number;
+            credits_used: number;
+            /** @enum {string|null} */
+            webhook_status?: "pending" | "delivered" | "failed" | null;
+            progress?: ({
+                round?: number;
+                rounds?: number;
+                queries?: number;
+                sources?: number;
+                /** @enum {string} */
+                step?: "searching" | "reviewing" | "writing";
+            } & {
+                [key: string]: unknown;
+            }) | null;
+            /** @description Set once the report is written (a failed or canceled task may carry only `queries`) */
+            result?: components["schemas"]["ResearchResult"] | {
+                [key: string]: unknown;
+            } | null;
+            error?: components["schemas"]["TaskError"];
+        };
         CrawlRequest: {
             /**
              * Format: uri
@@ -1112,7 +1425,7 @@ interface components {
             /** Format: uuid */
             id: string;
             /** @enum {string} */
-            kind: "crawl";
+            kind: "crawl" | "research";
             status: components["schemas"]["TaskStatus"];
             /** Format: date-time */
             created_at: string;
@@ -1217,7 +1530,7 @@ interface components {
              * @description The site (any page of it; sitemaps are read from its origin)
              */
             url: string;
-            /** @description Keep only URLs relevant to these words, most relevant first */
+            /** @description Keep only URLs relevant to these words, most relevant first. When the sitemap lists fewer than 50 URLs, up to 8 of the start page's links are read too, one level deeper */
             search?: string;
             /** @default 100 */
             limit?: number;
@@ -1275,7 +1588,7 @@ interface components {
          * @enum {string}
          */
         Provider: "google" | "brave" | "bing" | "yahoo" | "duckduckgo" | "mojeek" | "wikipedia" | "yandex";
-        /** @description Which search providers may answer. `google` (the default) is Google only; within Google, SerpKite always fails over across its own proxy pools. `auto` allows falling back to other enabled providers, in route order, when Google is blocked or times out. A single other provider (`brave`) or a list (`["google","brave"]`, or `google,brave` in a query string) restricts the request to those providers. `meta.engine` always names the provider that answered and credits follow that provider's price. A key with "Allow fallback to other search engines" on treats a request without `engine` as `auto`. `consensus` (`/v1/search` only; 400 elsewhere, and it can't be combined with other names) queries several independent search indexes in parallel (at most one Bing-backed provider, so Yahoo or DuckDuckGo never count as agreeing with Bing), merges the results by URL and ranks them by how many providers returned each one. Each result lists its `sources`; `meta.engine` is `consensus` and `meta.route` lists every provider attempt. It stops once `num` unique results are in hand or after a few seconds, and costs the sum of one page at each provider that returned results (providers that failed, came back empty or were never started are free). `yandex` serves `/v1/maps`, `/v1/places` and `/v1/place` from Yandex Maps where the deployment enables it (otherwise a 503 `unavailable`, not charged); with `auto` it is the last fallback there. */
+        /** @description Which search providers may answer. `google` (the default) is Google only; within Google, SerpKite always fails over across its own proxy pools. `auto` allows falling back to other enabled providers, in route order, when Google is blocked or times out. A single other provider (`brave`) or a list (`["google","brave"]`, or `google,brave` in a query string) restricts the request to those providers. `meta.engine` always names the provider that answered and credits follow that provider's price. A key with "Allow fallback to other search engines" on treats a request without `engine` as `auto`. `consensus` (`/v1/search` only; 400 elsewhere, and it can't be combined with other names) queries several independent search indexes in parallel (at most one Bing-backed provider, so Yahoo or DuckDuckGo never count as agreeing with Bing), merges the results by URL and ranks them by how many providers returned each one. Each result lists its `sources`; `meta.engine` is `consensus` and `meta.route` lists every provider attempt. Up to three providers answer: a provider that fails or comes back empty hands its turn to the next one in the route. It stops once `num` unique results are in hand or after a few seconds, and costs the sum of one page at each provider that returned results (providers that failed, came back empty or were never started are free). `yandex` serves `/v1/search` from Yandex web search (no `time` filter or `safe: active`: a request naming it gets a 400 with them) and `/v1/maps`, `/v1/places` and `/v1/place` from Yandex Maps, where the deployment enables it (otherwise a 503 `unavailable`, not charged); with `auto` it is the last fallback there. */
         EngineParam: string | components["schemas"]["Provider"][];
         /** @description One provider attempt behind this answer. Proxy pools are internal and never listed. */
         RouteStep: {
@@ -1309,6 +1622,37 @@ interface components {
             /** @enum {string} */
             parse_quality?: "ok" | "partial" | "empty";
             latency_ms?: number;
+            llm?: components["schemas"]["LLMUsage"];
+            /** @description Non-fatal problems, e.g. an include_answer that failed (and was refunded) */
+            warnings?: string[];
+        };
+        /** @description The model that wrote this response's AI part and the tokens it used */
+        LLMUsage: {
+            /**
+             * @example anthropic
+             * @example openai
+             */
+            provider?: string;
+            /**
+             * @example claude-haiku-5-5
+             * @example gpt-6-luna
+             */
+            model?: string;
+            input_tokens?: number;
+            output_tokens?: number;
+        };
+        Citation: {
+            /** @description The `[n]` marker used in the text (1-based source number) */
+            index: number;
+            title: string;
+            link: string;
+            domain?: string;
+        };
+        /** @description include_answer: a cited answer over this response's results */
+        SearchAnswer: {
+            /** @description Markdown with `[n]` citation markers (n = the numbered sources: answer box, knowledge panel, then results) */
+            text: string;
+            citations: components["schemas"]["Citation"][];
         };
         /** @description The normalised request that produced this response (defaults filled in) */
         RequestEcho: {
@@ -1346,6 +1690,7 @@ interface components {
             exclude_domains?: string[];
             boost_domains?: string[];
             highlights?: boolean;
+            include_answer?: boolean;
         } & {
             [key: string]: unknown;
         };
@@ -1428,6 +1773,7 @@ interface components {
             related_searches: components["schemas"]["RelatedSearch"][];
             top_stories?: components["schemas"]["NewsResult"][];
             places?: components["schemas"]["PlaceResult"][];
+            answer?: components["schemas"]["SearchAnswer"];
             meta: components["schemas"]["Meta"];
         };
         ImageResult: {
@@ -1480,6 +1826,7 @@ interface components {
         NewsResponse: {
             request: components["schemas"]["RequestEcho"];
             results: components["schemas"]["NewsResult"][];
+            answer?: components["schemas"]["SearchAnswer"];
             meta: components["schemas"]["Meta"];
         };
         PlaceResult: {
@@ -1830,14 +2177,14 @@ interface components {
                 requests: number;
             };
         };
-        /** @description Body of `crawl.completed` */
+        /** @description Body of `crawl.completed` and `research.completed` */
         TaskCompletedEvent: {
-            /** @constant */
-            event: "crawl.completed";
+            /** @enum {string} */
+            event: "crawl.completed" | "research.completed";
             /** Format: uuid */
             id: string;
-            /** @constant */
-            kind: "crawl";
+            /** @enum {string} */
+            kind: "crawl" | "research";
             status: components["schemas"]["TaskStatus"];
             /** Format: date-time */
             created_at: string;
@@ -1846,7 +2193,7 @@ interface components {
             credits_used: number;
             /** @description Where the task (and its full result) can be fetched for 24 hours */
             poll_url?: string;
-            /** @description The CrawlResult (null when the crawl failed without one, or when it is larger than 4 MB: see result_omitted) */
+            /** @description The CrawlResult or ResearchResult (null when the task failed without one, or when it is larger than 4 MB: see result_omitted) */
             result?: unknown;
             /** @description Set when the result was too large for the webhook; GET poll_url for it */
             result_omitted?: boolean;
@@ -2468,6 +2815,8 @@ interface operations {
                 end_date?: string;
                 /** @description Needs include_content */
                 highlights?: boolean;
+                /** @description Add a cited AI answer (+2 credits; +4 with include_content) */
+                include_answer?: boolean;
                 api_key?: string;
             };
             header?: never;
@@ -2867,6 +3216,203 @@ interface operations {
             429: components["responses"]["Error"];
         };
     };
+    answer: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                /**
+                 * @example {
+                 *       "q": "what is retrieval-augmented generation",
+                 *       "depth": "standard",
+                 *       "num_sources": 3
+                 *     }
+                 */
+                "application/json": components["schemas"]["AnswerRequest"];
+            };
+        };
+        responses: {
+            /** @description OK (`text/event-stream` when `stream` is true) */
+            200: {
+                headers: {
+                    "X-Credits-Used": components["headers"]["CreditsUsed"];
+                    "X-Credits-Remaining": components["headers"]["CreditsRemaining"];
+                    "X-Cost-USD": components["headers"]["CostUSD"];
+                    "X-Cache": components["headers"]["Cache"];
+                    "X-Latency-Ms": components["headers"]["LatencyMs"];
+                    "X-Tokens-Estimate": components["headers"]["TokensEstimate"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "request": {
+                     *         "endpoint": "answer",
+                     *         "engine": "google",
+                     *         "q": "what is retrieval-augmented generation",
+                     *         "country": "us",
+                     *         "language": "en",
+                     *         "num": 10,
+                     *         "page": 1,
+                     *         "autocorrect": true,
+                     *         "device": "desktop",
+                     *         "include_content": 3,
+                     *         "depth": "standard",
+                     *         "num_sources": 3
+                     *       },
+                     *       "answer": "Retrieval-augmented generation (RAG) grounds a language model's answer in documents retrieved at query time [1], which reduces hallucinations and keeps answers current [2].",
+                     *       "citations": [
+                     *         {
+                     *           "index": 1,
+                     *           "title": "Retrieval-augmented generation",
+                     *           "link": "https://en.wikipedia.org/wiki/Retrieval-augmented_generation",
+                     *           "domain": "en.wikipedia.org"
+                     *         },
+                     *         {
+                     *           "index": 2,
+                     *           "title": "What is RAG?",
+                     *           "link": "https://www.ibm.com/think/topics/retrieval-augmented-generation",
+                     *           "domain": "ibm.com"
+                     *         }
+                     *       ],
+                     *       "results": [
+                     *         {
+                     *           "index": 1,
+                     *           "title": "Retrieval-augmented generation",
+                     *           "link": "https://en.wikipedia.org/wiki/Retrieval-augmented_generation",
+                     *           "domain": "en.wikipedia.org"
+                     *         },
+                     *         {
+                     *           "index": 2,
+                     *           "title": "What is RAG?",
+                     *           "link": "https://www.ibm.com/think/topics/retrieval-augmented-generation",
+                     *           "domain": "ibm.com"
+                     *         }
+                     *       ],
+                     *       "meta": {
+                     *         "request_id": "req_01J9",
+                     *         "credits_used": 6,
+                     *         "credits": {
+                     *           "search": 4,
+                     *           "answer": 2
+                     *         },
+                     *         "cached": false,
+                     *         "engine": "google",
+                     *         "latency_ms": 4410,
+                     *         "llm": {
+                     *           "provider": "anthropic",
+                     *           "model": "claude-haiku-5-5",
+                     *           "input_tokens": 3120,
+                     *           "output_tokens": 88
+                     *         }
+                     *       }
+                     *     }
+                     */
+                    "application/json": components["schemas"]["AnswerResponse"];
+                    /**
+                     * @example event: results
+                     *     data: {"request":{"endpoint":"answer","q":"what is retrieval-augmented generation"},"results":[{"index":1,"title":"Retrieval-augmented generation","link":"https://en.wikipedia.org/wiki/Retrieval-augmented_generation","domain":"en.wikipedia.org"}]}
+                     *
+                     *     event: delta
+                     *     data: {"text":"Retrieval-augmented generation grounds "}
+                     *
+                     *     event: done
+                     *     data: {"answer":"Retrieval-augmented generation grounds a model's answer in documents retrieved at query time [1].","citations":[{"index":1,"title":"Retrieval-augmented generation","link":"https://en.wikipedia.org/wiki/Retrieval-augmented_generation","domain":"en.wikipedia.org"}],"meta":{"request_id":"req_01J9","credits_used":3,"cached":false}}
+                     */
+                    "text/event-stream": string;
+                };
+            };
+            400: components["responses"]["Error"];
+            401: components["responses"]["Error"];
+            402: components["responses"]["Error"];
+            403: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+            503: components["responses"]["Unavailable"];
+        };
+    };
+    createResearch: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                /**
+                 * @example {
+                 *       "input": "compare espresso machines under $500 for a small office",
+                 *       "effort": "standard",
+                 *       "output_schema": {
+                 *         "type": "object",
+                 *         "properties": {
+                 *           "winner": {
+                 *             "type": "string"
+                 *           }
+                 *         }
+                 *       }
+                 *     }
+                 */
+                "application/json": components["schemas"]["ResearchRequest"];
+            };
+        };
+        responses: {
+            202: components["responses"]["TaskAccepted"];
+            400: components["responses"]["Error"];
+            401: components["responses"]["Error"];
+            402: components["responses"]["Error"];
+            403: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+            503: components["responses"]["Unavailable"];
+        };
+    };
+    getResearch: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ResearchTask"];
+                };
+            };
+            401: components["responses"]["Error"];
+            404: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+        };
+    };
+    cancelResearch: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: components["responses"]["TaskCanceled"];
+            401: components["responses"]["Error"];
+            404: components["responses"]["Error"];
+            409: components["responses"]["Error"];
+            429: components["responses"]["Error"];
+        };
+    };
     listMonitors: {
         parameters: {
             query?: never;
@@ -3393,6 +3939,28 @@ interface operations {
             };
         };
     };
+    researchCompletedWebhook: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["TaskCompletedEvent"];
+            };
+        };
+        responses: {
+            /** @description Any 2xx acknowledges the delivery */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     monitorResultsWebhook: {
         parameters: {
             query?: never;
@@ -3496,6 +4064,15 @@ type MapURL = Schemas["MapURL"];
 type ExtractResult = Schemas["ExtractResult"];
 type ExtractFailure = Schemas["ExtractFailure"];
 type RankMatch = Schemas["RankResponse"]["matches"][number];
+/** A source an AI answer or report cites with an `[index]` marker. */
+type Citation = Schemas["Citation"];
+/**
+ * `include_answer: true` on `search` / `news`: a cited answer over the response's results
+ * (`text` with `[n]` markers). Absent when the model failed (refunded, see `meta.warnings`).
+ */
+type SearchAnswer = Schemas["SearchAnswer"];
+/** `meta.llm`: the model behind an AI response and the tokens it used. */
+type LLMUsage = Schemas["LLMUsage"];
 type SearchResponse = Schemas["SearchResponse"];
 type ImagesResponse = Schemas["ImagesResponse"];
 type VideosResponse = Schemas["VideosResponse"];
@@ -3523,6 +4100,34 @@ interface CompactResponse {
     meta: Meta;
     [key: string]: unknown;
 }
+/** Body of `POST /v1/answer` (`stream` is set by `answerStream`). */
+type AnswerParams = Omit<Schemas["AnswerRequest"], "engine" | "stream"> & {
+    /** Search providers allowed to answer. Default `"google"`. See {@link Engine}. */
+    engine?: Engine;
+};
+type AnswerResponse = Schemas["AnswerResponse"];
+/** A result the answer may cite, numbered as in the prompt (`[index]`). */
+type AnswerSource = Schemas["AnswerSource"];
+/** `meta` of an answer: `credits` splits `credits_used` into search and model; `llm` names the model. */
+type AnswerMeta = Schemas["AnswerMeta"];
+type AnswerStreamResults = Schemas["AnswerStreamResults"];
+type AnswerStreamDelta = Schemas["AnswerStreamDelta"];
+type AnswerStreamDone = Schemas["AnswerStreamDone"];
+/**
+ * One Server-Sent Event of `answerStream`: `results` first, then `delta` pieces of text,
+ * then `done` with the final answer, citations and meta. A server `error` event is thrown
+ * as a `SerpKiteError` instead of being yielded.
+ */
+type AnswerStreamEvent = {
+    event: "results";
+    data: AnswerStreamResults;
+} | {
+    event: "delta";
+    data: AnswerStreamDelta;
+} | {
+    event: "done";
+    data: AnswerStreamDone;
+};
 type Batch = Schemas["Batch"];
 type BatchStatus = Batch["status"];
 type BatchEndpoint = Schemas["BatchCreateRequest"]["endpoint"];
@@ -3562,7 +4167,7 @@ type BatchCreateParams = {
     };
 }[BatchEndpoint];
 type TaskStatus = Schemas["TaskStatus"];
-/** The `202` body of `crawl`. */
+/** The `202` body of `crawl` and `research`. */
 type TaskCreated = Schemas["TaskCreated"];
 type TaskCancelResponse = Schemas["TaskCancelResponse"];
 type TaskError = Schemas["TaskError"];
@@ -3581,6 +4186,24 @@ type CrawlStats = CrawlResult["stats"];
 /** Why a crawl ended (`result.stats.stopped`). */
 type CrawlStopReason = NonNullable<CrawlStats["stopped"]>;
 type CrawlPage = Schemas["CrawlPage"];
+/**
+ * Body of `POST /v1/research`: `input` (the task in plain words), `effort` (`lite`, `standard`
+ * (default) or `deep`; flat prices at https://serpkite.com/pricing), optional `output_schema`,
+ * locale, domain filters and `webhook_url` (receives `research.completed`).
+ */
+type ResearchParams = Schemas["ResearchRequest"];
+type ResearchEffort = NonNullable<ResearchParams["effort"]>;
+type ResearchResult = Schemas["ResearchResult"];
+type ResearchSource = Schemas["ResearchSource"];
+/**
+ * A research task. `result` is set once the report is written (`status: "completed"`); a
+ * failed or canceled task may carry a partial result with only `queries`.
+ */
+type ResearchTask = Omit<Schemas["ResearchTask"], "result"> & {
+    result?: ResearchResult | null;
+};
+/** `progress` of a running research task (round, queries, sources, current step). */
+type ResearchProgress = NonNullable<Schemas["ResearchTask"]["progress"]>;
 /**
  * Body of `POST /v1/monitors`. `search` and `news` monitors need `q`; `webpage` monitors need
  * `url` (and take only `country` besides) and report the page when its content changes.
@@ -3629,10 +4252,17 @@ type BatchCompletedEvent = Omit<Batch, "poll_url" | "webhook_url" | "webhook_sta
     event: "batch.completed";
 };
 /**
- * Body of `crawl.completed`. When the result is over 4 MB, `result` is null and
+ * Body of `crawl.completed` and `research.completed` (`kind` says which; `result` is a
+ * `CrawlResult` or `ResearchResult`). When the result is over 4 MB, `result` is null and
  * `result_omitted` is true: fetch the task from `poll_url`.
  */
 type TaskCompletedEvent = Schemas["TaskCompletedEvent"];
+/** Body of `research.completed`: a {@link TaskCompletedEvent} whose `result` is a `ResearchResult`. */
+type ResearchCompletedEvent = Omit<TaskCompletedEvent, "event" | "kind" | "result"> & {
+    event: "research.completed";
+    kind: "research";
+    result?: ResearchResult | null;
+};
 /**
  * Body of `monitor.results`. `run_id` is also the `X-SerpKite-Delivery` header (dedupe retries
  * on it). Carries the monitor's `metadata`, and `url` for webpage monitors (whose `new_results`
@@ -3640,7 +4270,7 @@ type TaskCompletedEvent = Schemas["TaskCompletedEvent"];
  */
 type MonitorResultsEvent = Schemas["MonitorResultsEvent"];
 /** `X-SerpKite-Event` values. Plain strings stay accepted for events added later. */
-type WebhookEventType = "batch.completed" | "crawl.completed" | "monitor.results" | (string & {});
+type WebhookEventType = "batch.completed" | "crawl.completed" | "research.completed" | "monitor.results" | (string & {});
 /** A verified webhook delivery, from `parseWebhook`. */
 type WebhookEvent = {
     type: "batch.completed";
@@ -3650,13 +4280,17 @@ type WebhookEvent = {
     type: "crawl.completed";
     deliveryId: string | undefined;
     data: TaskCompletedEvent;
+} | {
+    type: "research.completed";
+    deliveryId: string | undefined;
+    data: ResearchCompletedEvent;
 } | {
     type: "monitor.results";
     deliveryId: string | undefined;
     data: MonitorResultsEvent;
 };
 
-declare const VERSION = "0.6.0";
+declare const VERSION = "0.7.0";
 declare const DEFAULT_BASE_URL = "https://api.serpkite.com";
 interface SerpKiteOptions {
     /** API key (`skt_live_…`). Defaults to the `SERPKITE_API_KEY` environment variable. */
@@ -3707,8 +4341,9 @@ interface BatchCreateOptions extends RequestOptions {
 }
 interface WaitOptions {
     /**
-     * Give up after this many milliseconds. Default 600000 (10 minutes) for batches and
-     * 2100000 (35 minutes) for `waitForCrawl`: a crawl runs for up to 30 minutes.
+     * Give up after this many milliseconds. Default 600000 (10 minutes) for batches,
+     * 2100000 (35 minutes) for `waitForCrawl` (a crawl runs for up to 30 minutes) and
+     * 900000 (15 minutes) for `waitResearch`.
      */
     timeoutMs?: number;
     /** First delay between polls. Default 1000. Grows 1.5× per poll. */
@@ -3757,6 +4392,7 @@ declare class SerpKite {
         related_searches: components["schemas"]["RelatedSearch"][];
         top_stories?: components["schemas"]["NewsResult"][];
         places?: components["schemas"]["PlaceResult"][];
+        answer?: components["schemas"]["SearchAnswer"];
         meta: components["schemas"]["Meta"];
     }>;
     /** Google Images. */
@@ -3775,6 +4411,7 @@ declare class SerpKite {
     readonly news: VerticalMethod<SearchParams, {
         request: components["schemas"]["RequestEcho"];
         results: components["schemas"]["NewsResult"][];
+        answer?: components["schemas"]["SearchAnswer"];
         meta: components["schemas"]["Meta"];
     }>;
     /**
@@ -3873,6 +4510,10 @@ declare class SerpKite {
      * Read up to 20 URLs (HTML or PDF) as Markdown, text or HTML in one call, with optional
      * query-ranked `highlights` (BM25), `include_links` and `include_images`. 1 credit per URL
      * that comes back (0.5 from cache); URLs that fail are listed in `failed` and cost nothing.
+     * `summary: true` adds an AI summary of each page and `output_schema` (a JSON Schema, guided
+     * by an optional `prompt`) returns each page's data as JSON in `output`, each at an extra
+     * per-page price (https://serpkite.com/pricing); a page whose model step failed has
+     * `summary_error` / `output_error` instead and isn't charged for it.
      */
     extract(params: ExtractParams, options?: RequestOptions): Promise<ExtractResponse>;
     /**
@@ -3884,6 +4525,29 @@ declare class SerpKite {
     map(params: MapParams, options?: RequestOptions): Promise<MapResponse>;
     /** Balance, limits and this month's usage for the key's account. */
     account(options?: RequestOptions): Promise<Account>;
+    /**
+     * A cited answer grounded on live Google results: Markdown with `[n]` markers in `answer`,
+     * the cited sources in `citations`. `depth: "fast"` answers from the result page;
+     * `"standard"` (default) also reads the top `num_sources` pages and costs more
+     * (https://serpkite.com/pricing; `meta.credits` splits search and model). With
+     * `output_schema` the answer is a JSON value in `output`.
+     * When the model fails the call throws `ai_unavailable` (503) and the model part is refunded;
+     * a search with nothing to answer from returns `answer: null` and a `meta.warnings` entry.
+     */
+    answer(params: AnswerParams, options?: RequestOptions): Promise<AnswerResponse>;
+    /**
+     * Streams an answer as Server-Sent Events: `results` first, then `delta` text pieces,
+     * then `done` (final answer, citations, meta). A server `error` event is thrown as a
+     * `SerpKiteError` (`ai_unavailable`). Breaking out of the loop closes the connection
+     * (the model part is then not charged). Can't be combined with `output_schema`.
+     *
+     * ```ts
+     * for await (const ev of sk.answerStream({ q: "what is retrieval-augmented generation" })) {
+     *   if (ev.event === "delta") process.stdout.write(ev.data.text);
+     * }
+     * ```
+     */
+    answerStream(params: AnswerParams, options?: RequestOptions): AsyncIterable<AnswerStreamEvent>;
     /**
      * Starts an async crawl of one site and returns the queued task (`202`). 1 credit per page
      * read (0.5 from cache); `limit` credits (up to 1000 pages, `max_depth` up to 10) are
@@ -3906,6 +4570,33 @@ declare class SerpKite {
     waitForCrawl(idOrTask: string | {
         id: string;
     }, options?: WaitOptions): Promise<CrawlTask>;
+    /**
+     * Starts an async research task: the model plans searches, reads the sources and writes a
+     * cited Markdown report (`result.report`). `effort` (`lite`, `standard` (default), `deep`)
+     * sets how much is searched and read; its flat price (https://serpkite.com/pricing) is
+     * reserved up front and charged only when the report is written (a canceled task is charged
+     * for the searches already run). With
+     * `output_schema` the report is also returned as JSON in `result.output`. Poll with
+     * `getResearch` / `waitResearch` or receive the signed `research.completed` webhook.
+     * Only retried on 429, so a lost response never starts (and reserves) a second task.
+     */
+    research(params: ResearchParams, options?: RequestOptions): Promise<TaskCreated>;
+    /** Polls a research task (`progress` while it runs; results are kept for 24 hours). */
+    getResearch(id: string, options?: RequestOptions): Promise<ResearchTask>;
+    /**
+     * Cancels a research task: refunded if still queued, else stops at its next round and is
+     * charged for the searches run.
+     */
+    cancelResearch(id: string, options?: RequestOptions): Promise<TaskCancelResponse>;
+    /**
+     * Polls until the research task is `completed`, `failed` or `canceled` and returns it (a
+     * failed task is returned, not thrown; check `status` and `error`). The report is in
+     * `result.report`. Accepts an id or the task returned by `research`. Default timeout
+     * 15 minutes.
+     */
+    waitResearch(idOrTask: string | {
+        id: string;
+    }, options?: WaitOptions): Promise<ResearchTask>;
     readonly monitors: {
         /**
          * Saves a `search` or `news` request (`q`) that runs on a schedule (hourly to monthly) and
@@ -4022,7 +4713,7 @@ interface VerifyWebhookOptions {
 }
 type HeaderSource = Headers | Record<string, string | string[] | undefined>;
 /**
- * Checks a webhook delivery (any event: `batch.completed`, `crawl.completed`,
+ * Checks a webhook delivery (any event: `batch.completed`, `crawl.completed`, `research.completed`,
  * `monitor.results`): `X-SerpKite-Signature` must be
  * `v1=<hex HMAC-SHA256(secret, "<X-SerpKite-Timestamp>.<raw body>")>` and the
  * timestamp recent. Pass the raw request body exactly as received (not
@@ -4037,7 +4728,7 @@ declare function verifyWebhook(secret: string, payload: string | Uint8Array, hea
  * Verifies a delivery (see {@link verifyWebhook}) and returns it typed by its
  * `X-SerpKite-Event` header. `deliveryId` is `X-SerpKite-Delivery` (for
  * `monitor.results` it equals `data.run_id`): use it to deduplicate retries. A
- * `crawl.completed` result over 4 MB arrives as `result: null` with
+ * `crawl.completed` or `research.completed` result over 4 MB arrives as `result: null` with
  * `result_omitted: true`; fetch it from `data.poll_url`. Throws a
  * `SerpKiteError` with code `invalid_signature` when the signature or timestamp
  * doesn't check out.
@@ -4049,4 +4740,4 @@ declare function verifyWebhook(secret: string, payload: string | Uint8Array, hea
  */
 declare function parseWebhook(secret: string, payload: string | Uint8Array, headers: HeaderSource, options?: VerifyWebhookOptions): Promise<WebhookEvent>;
 
-export { type Account, type AnswerBox, type AutocompleteResponse, type Batch, type BatchCompletedEvent, type BatchCreateEntry, type BatchCreateError, type BatchCreateOptions, type BatchCreateParams, type BatchCreateResponse, type BatchEndpoint, type BatchStatus, type CompactResponse, type CrawlPage, type CrawlParams, type CrawlResult, type CrawlSitemapMode, type CrawlStats, type CrawlStopReason, type CrawlTask, DEFAULT_BASE_URL, type DomainList, type Engine, type ErrorBody, type ExtractFailure, type ExtractParams, type ExtractResponse, type ExtractResult, type Format, type Highlight, type HoursInterval, type ImageResult, type ImagesResponse, type KnowledgeGraph, type MapParams, type MapResponse, type MapURL, type MapsResponse, type Meta, type Monitor, type MonitorCreateParams, type MonitorEndpoint, type MonitorList, type MonitorMetadata, type MonitorPageChange, type MonitorResultsEvent, type MonitorRun, type MonitorRunList, type MonitorRunsParams, type MonitorSearch, type MonitorStatus, type MonitorUpdateParams, type NewsResponse, type NewsResult, type OrganicResult, type PageLink, type PageMetadata, type PatentResult, type PatentsResponse, type PeopleAlsoAsk, type PlaceParams, type PlacePhoto, type PlaceResult, type PlacesResponse, type Provider, type RankMatch, type RankParams, type RankResponse, type RelatedSearch, type RequestEcho, type RequestOptions, type ResponseInfo, type ReviewResult, type ReviewsParams, type ReviewsResponse, type RouteOutcome, type RouteStep, type ScholarResponse, type ScholarResult, type SearchParams, type SearchResponse, SerpKite, SerpKiteError, type SerpKiteOptions, type ShoppingResponse, type ShoppingResult, type Sitelink, type Status, type Suggestion, type TaskCancelResponse, type TaskCompletedEvent, type TaskCreated, type TaskError, type TaskStatus, VERSION, type VerifyWebhookOptions, type VerticalMethod, type VideoResult, type VideosResponse, type WaitOptions, type WebhookEvent, type WebhookEventType, type WebpageParams, type WebpageResponse, type WeeklyHours, type components, isBatchError, type operations, parseRetryAfter, parseWebhook, type paths, verifyWebhook };
+export { type Account, type AnswerBox, type AnswerMeta, type AnswerParams, type AnswerResponse, type AnswerSource, type AnswerStreamDelta, type AnswerStreamDone, type AnswerStreamEvent, type AnswerStreamResults, type AutocompleteResponse, type Batch, type BatchCompletedEvent, type BatchCreateEntry, type BatchCreateError, type BatchCreateOptions, type BatchCreateParams, type BatchCreateResponse, type BatchEndpoint, type BatchStatus, type Citation, type CompactResponse, type CrawlPage, type CrawlParams, type CrawlResult, type CrawlSitemapMode, type CrawlStats, type CrawlStopReason, type CrawlTask, DEFAULT_BASE_URL, type DomainList, type Engine, type ErrorBody, type ExtractFailure, type ExtractParams, type ExtractResponse, type ExtractResult, type Format, type Highlight, type HoursInterval, type ImageResult, type ImagesResponse, type KnowledgeGraph, type LLMUsage, type MapParams, type MapResponse, type MapURL, type MapsResponse, type Meta, type Monitor, type MonitorCreateParams, type MonitorEndpoint, type MonitorList, type MonitorMetadata, type MonitorPageChange, type MonitorResultsEvent, type MonitorRun, type MonitorRunList, type MonitorRunsParams, type MonitorSearch, type MonitorStatus, type MonitorUpdateParams, type NewsResponse, type NewsResult, type OrganicResult, type PageLink, type PageMetadata, type PatentResult, type PatentsResponse, type PeopleAlsoAsk, type PlaceParams, type PlacePhoto, type PlaceResult, type PlacesResponse, type Provider, type RankMatch, type RankParams, type RankResponse, type RelatedSearch, type RequestEcho, type RequestOptions, type ResearchCompletedEvent, type ResearchEffort, type ResearchParams, type ResearchProgress, type ResearchResult, type ResearchSource, type ResearchTask, type ResponseInfo, type ReviewResult, type ReviewsParams, type ReviewsResponse, type RouteOutcome, type RouteStep, type ScholarResponse, type ScholarResult, type SearchAnswer, type SearchParams, type SearchResponse, SerpKite, SerpKiteError, type SerpKiteOptions, type ShoppingResponse, type ShoppingResult, type Sitelink, type Status, type Suggestion, type TaskCancelResponse, type TaskCompletedEvent, type TaskCreated, type TaskError, type TaskStatus, VERSION, type VerifyWebhookOptions, type VerticalMethod, type VideoResult, type VideosResponse, type WaitOptions, type WebhookEvent, type WebhookEventType, type WebpageParams, type WebpageResponse, type WeeklyHours, type components, isBatchError, type operations, parseRetryAfter, parseWebhook, type paths, verifyWebhook };