@search1api/client 0.2.0 → 0.3.0

package/dist/generated.d.ts

@@ -3,6 +3,26 @@
  * Do not make direct changes to the file.
  */
 export interface paths {
+    "/feedback": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Report a Search1API problem or feature request
+         * @description Report a Search1API problem, missing capability, or confusing documentation encountered during a task. Only message is required. Optional request_id refers to the original problem request. Do not include credentials, personal data, or private user content. Reports are stored in Agentback and linked to an opaque account reference. Do not report every empty result or retry the same report automatically; feedback should not block the main task. Returns 201 only after storage succeeds. Maximum JSON body size: 16 KiB. Limited to 10 submissions per account per minute at a Cloudflare location. Free to call.
+         */
+        post: operations["feedback"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/screenshot": {
         parameters: {
             query?: never;
@@ -12,7 +32,10 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Render a web page as a PNG, JPEG, or WebP image */
+        /**
+         * Render a web page as a PNG, JPEG, or WebP image
+         * @description Render a public webpage as a PNG, JPEG, or WebP image. Use it when appearance is the point — layout checks, visual previews, or content that does not survive text extraction — and control the viewport, when the page counts as ready, and whether to capture the full document or a single element by CSS selector. When you want the page's text instead, call POST /crawl. Costs 2 credits per request.
+         */
         post: operations["screenshot"];
         delete?: never;
         options?: never;
@@ -29,7 +52,10 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Search the web using multiple search engines */
+        /**
+         * Search the web using multiple search engines
+         * @description Search the live public web when the answer depends on current information, sources, or research a model's training data cannot cover. Returns ranked results with id, title, URL, snippet, and `published_date` (ISO 8601, when the engine exposes one) across 13+ engines, with optional images. Set `crawl_results` to pull the top N result pages in the same call — each crawled page is billed as an additional crawl — or pass a result URL to POST /crawl separately. Costs 1 credit per request.
+         */
         post: operations["search"];
         delete?: never;
         options?: never;
@@ -46,7 +72,10 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Search news articles across multiple sources */
+        /**
+         * Search news articles across multiple sources
+         * @description Search recent news when the question is about events, announcements, or coverage rather than reference material. Returns articles from verified publishers with title, URL, snippet, `published_date` (ISO 8601, when known), and optional full page content, filterable by site, language, and time range. For questions that are not time-sensitive, prefer POST /search. Costs 1 credit per request.
+         */
         post: operations["news"];
         delete?: never;
         options?: never;
@@ -54,6 +83,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/ask": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Search the engines a natural-language request calls for
+         * @description Agentic search. Describe what you are looking for in plain language and let a decision model (currently TypeSafe Jev) decide where to look. It picks up to five engines (web search, Hacker News, Reddit, GitHub, X, arXiv, Wikipedia, IMDb, WeChat, YouTube), rewrites the request into search keywords, infers a publication window from phrases such as "this week", searches the engines in parallel, and returns only the results judged relevant, merged and ranked, so agents read fewer off-topic results. The request takes only `query`; engines, keywords, and the window are always chosen by the model, and the response reports them in `intent`. Use POST /search instead when you already know the engine and keywords and want its raw ranking. Costs 5 credits per request.
+         */
+        post: operations["ask"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/crawl": {
         parameters: {
             query?: never;
@@ -63,7 +112,10 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Crawl a URL and extract its content */
+        /**
+         * Crawl a URL and extract its content
+         * @description Fetch one public URL and return its readable title and body as clean text, with navigation, boilerplate, and scripts stripped. Use it on a URL the user supplied or one returned by POST /search. To ingest a whole site rather than a single page, use POST /deepcrawl. Send an array of request objects to crawl several URLs in one call: the response is an array containing only the URLs that succeeded, in no guaranteed order, so match items back to your input by `crawlParameters.url`; failed URLs are omitted and not charged. `enable_fallback` is accepted as a snake_case alias of `enableFallback`. Costs 1 credit per request.
+         */
         post: operations["crawl"];
         delete?: never;
         options?: never;
@@ -80,7 +132,10 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Extract sitemap URLs from a website */
+        /**
+         * Extract sitemap URLs from a website
+         * @description Discover the public URLs of a site when you need to know which pages exist before fetching any of them — scoping a crawl, auditing coverage, or locating a section. With the default `type: "sitemap"` this reads the site's own sitemap: `Sitemap:` directives in robots.txt first, then the conventional paths, following sitemap index files and gzipped sitemaps, and returns the URLs it declares for the requested host. A site that publishes no sitemap falls back to the links found on the given page. Use `type: "all"` to skip the sitemap and get every link on that one page instead, including links to other hosts. Neither mode fetches page content. Costs 1 credit per request.
+         */
         post: operations["sitemap"];
         delete?: never;
         options?: never;
@@ -97,7 +152,10 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Get trending topics from various platforms */
+        /**
+         * Get trending topics from various platforms
+         * @description List what is currently popular on a supported platform, such as GitHub repositories or Hacker News stories, when the user asks what is trending or new right now. This reads a platform's own live ranking rather than performing a query — for topic searches use POST /search. Costs 1 credit per request.
+         */
         post: operations["trending"];
         delete?: never;
         options?: never;
@@ -114,7 +172,10 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Extract structured content from a URL */
+        /**
+         * Extract structured content from a URL
+         * @description Pull structured data out of a single webpage using a natural-language prompt and a JSON schema you supply. Use it when you need specific fields — prices, specifications, contact details — rather than the whole document; when you want the full text, use POST /crawl. Costs 10 credits per request.
+         */
         post: operations["extract"];
         delete?: never;
         options?: never;
@@ -131,7 +192,10 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Deep crawl a website across multiple pages */
+        /**
+         * Deep crawl a website across multiple pages
+         * @description Start an asynchronous crawl of an entire site and package the pages as documents. Use it for whole-site ingestion; a single page is POST /crawl. The call returns a task id immediately rather than the result — poll GET /deepcrawl/status/{taskId} until the task reports completion. Costs 20 credits per request.
+         */
         post: operations["deepcrawl"];
         delete?: never;
         options?: never;
@@ -146,7 +210,10 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Check deepcrawl task status */
+        /**
+         * Check deepcrawl task status
+         * @description Poll a deepcrawl task started by POST /deepcrawl. Returns the task's current state and, once it finishes, where to retrieve the packaged result. Safe to call repeatedly. Free to call.
+         */
         get: operations["deepcrawlStatus"];
         put?: never;
         post?: never;
@@ -163,7 +230,10 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Health check */
+        /**
+         * Health check
+         * @description Report whether the API is serving traffic. Takes no credentials, so use it for uptime and readiness checks — it will not tell you whether an API key is valid; call GET /usage for that. Free to call.
+         */
         get: operations["health"];
         put?: never;
         post?: never;
@@ -180,7 +250,10 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Get API key usage statistics */
+        /**
+         * Get API key usage statistics
+         * @description Return the remaining credit balance for the authenticated account. Use it to check headroom before starting an expensive job such as a deepcrawl, or to confirm an API key works. Free to call.
+         */
         get: operations["usage"];
         put?: never;
         post?: never;
@@ -194,7 +267,7 @@ export interface paths {
 export type webhooks = Record<string, never>;
 export interface components {
     schemas: {
-        /** @description Search1API error. Payment challenges may use RFC 9457 problem detail fields. */
+        /** @description Search1API error. Every JSON error carries `ok: false`, `error` (a short status-derived label) and `message` (human-readable detail); validation failures add `errors`. Payment challenges may use RFC 9457 problem detail fields. */
         ApiError: {
             /** @enum {boolean} */
             ok?: false;
@@ -216,9 +289,11 @@ export interface components {
         SearchParameters: {
             query: string;
             /** @enum {string} */
-            search_service?: "google" | "bing" | "duckduckgo" | "yahoo" | "youtube" | "x" | "reddit" | "github" | "arxiv" | "wechat" | "bilibili" | "imdb" | "wikipedia" | "" | "sogou" | "baidu" | "360" | "quark";
+            search_service?: "google" | "bing" | "bingcn" | "duckduckgo" | "yahoo" | "yandex" | "youtube" | "x" | "reddit" | "github" | "arxiv" | "wechat" | "bilibili" | "imdb" | "wikipedia" | "grokipedia" | "" | "baidu" | "360" | "quark";
             /** @default 5 */
             max_results: number;
+            /** @default 1 */
+            page: number;
             /** @default 0 */
             crawl_results: number;
             /** @default false */
@@ -252,7 +327,7 @@ export interface components {
         CrawlRequest: {
             /** Format: uri */
             url: string;
-            /** @default false */
+            /** @default true */
             enableFallback: boolean;
         };
         SitemapRequest: {
@@ -285,6 +360,29 @@ export interface components {
             link: string;
             snippet: string;
             content?: string;
+            /**
+             * @description When the page was published, as ISO 8601: `YYYY-MM-DD` when only the day is known (web search engines), or `YYYY-MM-DDTHH:MM:SSZ` in UTC when the source carries a time (x, reddit, github, arxiv, youtube, bilibili, wechat, news feeds). Omitted when the source exposes no date, so treat it as optional per result.
+             * @example 2026-09-03
+             */
+            published_date?: string;
+            /**
+             * @description What a `github` result is: a repository, an issue, a pull request, or a discussion. Only present for `search_service: "github"`.
+             * @enum {string}
+             */
+            kind?: "repo" | "issue" | "pr" | "discussion";
+            /** @description Stargazer count of a `github` repository result (`kind: "repo"`). */
+            stars?: number;
+            /** @description Primary language of a `github` repository result (`kind: "repo"`). Omitted when GitHub reports none. */
+            language?: string;
+            /** @description Comment count on a `github` issue, pull request or discussion, or on a `hackernews` thread (POST /news). */
+            num_comments?: number;
+            /**
+             * Format: uri
+             * @description POST /news with `search_service: "hackernews"` only: the submitted article. `link` is the Hacker News discussion thread; `story_url` is empty for Ask HN / Show HN text posts.
+             */
+            story_url?: string;
+            /** @description POST /news with `search_service: "hackernews"` only: upvotes on the thread. */
+            points?: number;
         } & {
             [key: string]: unknown;
         };
@@ -332,6 +430,44 @@ export interface components {
                 totalCost: number;
             };
         };
+        AskResult: {
+            title: string;
+            /** Format: uri */
+            link: string;
+            snippet: string;
+            /**
+             * @description When the page was published, as ISO 8601 (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SSZ`). Omitted when the engine exposes no date.
+             * @example 2026-09-03
+             */
+            published_date?: string;
+            /** @description Engine that returned the result. */
+            source: string;
+            /** @description How likely the result is to be about the query, two decimals. Only results scoring at least 0.5 are returned. */
+            relevance: number;
+        };
+        AskResponse: {
+            /** @description The query as sent. */
+            query: string;
+            /** @description How the request was interpreted and searched. */
+            intent: {
+                /** @description Keywords sent to the engines, with platform and time phrases removed. */
+                search_query: string;
+                /** @description Engines searched. */
+                sources: string[];
+                /**
+                 * @description Publication window applied, or null for none.
+                 * @enum {string|null}
+                 */
+                time_range: "day" | "week" | "month" | "year" | null;
+            };
+            /** @description Relevant results from every engine, best first, with duplicates merged. May be empty. */
+            results: components["schemas"]["AskResult"][];
+            /** @description Engines that failed while others completed. The request is still charged. */
+            errors: {
+                source: string;
+                message: string;
+            }[];
+        };
         CrawlResult: {
             title: string;
             /** Format: uri */
@@ -403,6 +539,11 @@ export interface components {
             credential_type: "api_key" | "oauth";
             client_id?: string | null;
         };
+        FeedbackResponse: {
+            id: string;
+            /** @enum {string} */
+            status: "new";
+        };
     };
     responses: never;
     parameters: never;
@@ -412,6 +553,115 @@ export interface components {
 }
 export type $defs = Record<string, never>;
 export interface operations {
+    feedback: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    message: string;
+                    intent?: string;
+                    /**
+                     * @default other
+                     * @enum {string}
+                     */
+                    category?: "bug" | "feature_request" | "docs" | "other";
+                    request_id?: string;
+                    agent?: {
+                        name?: string;
+                        model?: string;
+                    };
+                };
+            };
+        };
+        responses: {
+            /** @description Successful response */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FeedbackResponse"];
+                };
+            };
+            /** @description Bad Request */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Unauthorized */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Forbidden */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Payload Too Large */
+            413: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Unsupported Media Type */
+            415: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Too Many Requests */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Internal Server Error */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Service Unavailable */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+        };
+    };
     screenshot: {
         parameters: {
             query?: never;
@@ -512,6 +762,15 @@ export interface operations {
                     "application/problem+json": components["schemas"]["ApiError"];
                 };
             };
+            /** @description Forbidden */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
             /** @description Validation Error */
             422: {
                 headers: {
@@ -580,9 +839,11 @@ export interface operations {
                 "application/json": {
                     query: string;
                     /** @enum {string} */
-                    search_service?: "google" | "bing" | "duckduckgo" | "yahoo" | "youtube" | "x" | "reddit" | "github" | "arxiv" | "wechat" | "bilibili" | "imdb" | "wikipedia" | "" | "sogou" | "baidu" | "360" | "quark";
+                    search_service?: "google" | "bing" | "bingcn" | "duckduckgo" | "yahoo" | "yandex" | "youtube" | "x" | "reddit" | "github" | "arxiv" | "wechat" | "bilibili" | "imdb" | "wikipedia" | "grokipedia" | "" | "baidu" | "360" | "quark";
                     /** @default 5 */
                     max_results?: number;
+                    /** @default 1 */
+                    page?: number;
                     /** @default 0 */
                     crawl_results?: number;
                     /** @default false */
@@ -597,9 +858,11 @@ export interface operations {
                 } | {
                     query: string;
                     /** @enum {string} */
-                    search_service?: "google" | "bing" | "duckduckgo" | "yahoo" | "youtube" | "x" | "reddit" | "github" | "arxiv" | "wechat" | "bilibili" | "imdb" | "wikipedia" | "" | "sogou" | "baidu" | "360" | "quark";
+                    search_service?: "google" | "bing" | "bingcn" | "duckduckgo" | "yahoo" | "yandex" | "youtube" | "x" | "reddit" | "github" | "arxiv" | "wechat" | "bilibili" | "imdb" | "wikipedia" | "grokipedia" | "" | "baidu" | "360" | "quark";
                     /** @default 5 */
                     max_results?: number;
+                    /** @default 1 */
+                    page?: number;
                     /** @default 0 */
                     crawl_results?: number;
                     /** @default false */
@@ -651,15 +914,6 @@ export interface operations {
                     "application/problem+json": components["schemas"]["ApiError"];
                 };
             };
-            /** @description Not Found */
-            404: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["ApiError"];
-                };
-            };
             /** @description Validation Error */
             422: {
                 headers: {
@@ -781,8 +1035,8 @@ export interface operations {
                     "application/problem+json": components["schemas"]["ApiError"];
                 };
             };
-            /** @description Not Found */
-            404: {
+            /** @description Validation Error */
+            422: {
                 headers: {
                     [name: string]: unknown;
                 };
@@ -790,8 +1044,26 @@ export interface operations {
                     "application/json": components["schemas"]["ApiError"];
                 };
             };
-            /** @description Validation Error */
-            422: {
+            /** @description Too Many Requests */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Internal Server Error */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Bad Gateway */
+            502: {
                 headers: {
                     [name: string]: unknown;
                 };
@@ -799,6 +1071,60 @@ export interface operations {
                     "application/json": components["schemas"]["ApiError"];
                 };
             };
+        };
+    };
+    ask: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @description What you are looking for, in natural language. Platform hints ("on Reddit", "papers") and time hints ("this week") steer engine and time-range selection. */
+                    query: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Successful response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AskResponse"];
+                };
+            };
+            /** @description Bad Request */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Unauthorized */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Payment Required */
+            402: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ApiError"];
+                };
+            };
             /** @description Too Many Requests */
             429: {
                 headers: {
@@ -840,12 +1166,12 @@ export interface operations {
                 "application/json": {
                     /** Format: uri */
                     url: string;
-                    /** @default false */
+                    /** @default true */
                     enableFallback?: boolean;
                 } | {
                     /** Format: uri */
                     url: string;
-                    /** @default false */
+                    /** @default true */
                     enableFallback?: boolean;
                 }[];
             };
@@ -887,6 +1213,24 @@ export interface operations {
                     "application/problem+json": components["schemas"]["ApiError"];
                 };
             };
+            /** @description Not Found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Gone */
+            410: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
             /** @description Validation Error */
             422: {
                 headers: {