@openserp/sdk 0.1.0

package/dist/generated/oss.d.cts

@@ -0,0 +1,1587 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+interface paths {
+    "/{engine}/search": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Search web results from a specific engine
+         * @description Engine path values are `google`, `yandex`, `baidu`, `bing`, `duck`, and `ecosia` (`duck` maps to DuckDuckGo internally). Use `?format=markdown|text|ndjson` for alternative output formats.
+         */
+        get: operations["searchWeb"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/{engine}/image": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Search image results from a specific engine */
+        get: operations["searchImages"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/google/parse": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Parse a Google SERP HTML document into structured results
+         * @description Accepts raw Google SERP HTML in the request body and returns a standard search envelope. Useful when an upstream provider delivers raw HTML rather than JSON. No browser is used; parsing is done with goquery. The body size limit is 10 MB.
+         */
+        post: operations["parseGoogleHTML"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/bing/parse": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Parse a Bing SERP HTML document into structured results
+         * @description Accepts raw Bing SERP HTML in the request body and returns a standard search envelope. Useful when an upstream provider delivers raw HTML rather than JSON. No browser is used; parsing is done with goquery. The body size limit is 10 MB.
+         */
+        post: operations["parseBingHTML"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/mega/search": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Search across multiple engines with selectable execution mode
+         * @description Mode controls engine execution strategy: `balanced` (default) queries all selected engines in parallel, `any` runs engines sequentially in requested order until first success, and `fast` queries only the fastest engine based on circuit-breaker average response time stats. In `balanced` mode, `dedupe` and `merge` tune aggregation behavior. Partial failures are surfaced in `meta.engines_failed` and `meta.engine_errors`. If all selected engines fail, the endpoint returns a 502 with per-engine error details. Use `?format=markdown|text|ndjson` for alternative output formats.
+         */
+        get: operations["megaSearch"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/mega/image": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Image search across multiple engines with selectable execution mode */
+        get: operations["megaImageSearch"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/mega/engines": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List available engines and runtime state */
+        get: operations["listMegaEngines"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/health": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Service health status */
+        get: operations["healthCheck"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/ready": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Service readiness status */
+        get: operations["readinessCheck"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/stats": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Combined cache, proxy, and circuit-breaker stats */
+        get: operations["getStats"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/stats/cache": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Cache statistics only */
+        get: operations["getCacheStats"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/stats/proxy": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Proxy pool and per-engine proxy policy statistics */
+        get: operations["getProxyStats"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/stats/cb": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Circuit breaker state per engine */
+        get: operations["getCircuitBreakerStats"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/openapi.yaml": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get raw OpenAPI YAML */
+        get: operations["getOpenAPISpec"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/docs": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Swagger UI for interactive API docs */
+        get: operations["getSwaggerUI"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+type webhooks = Record<string, never>;
+interface components {
+    schemas: {
+        QueryEcho: {
+            /** @example golang */
+            text: string;
+            /** @example EN */
+            lang?: string;
+            /** @example US */
+            region?: string;
+            /**
+             * @example [
+             *       "google"
+             *     ]
+             */
+            engines_requested: string[];
+        };
+        ResponseMeta: {
+            /** @example 01HXYZ... */
+            request_id: string;
+            /**
+             * Format: date-time
+             * @example 2026-04-24T12:00:00Z
+             */
+            requested_at: string;
+            /** @example 842 */
+            took_ms: number;
+            /** @example [] */
+            engines_failed: string[];
+            /** @description Sanitized per-engine failures for mega endpoints. */
+            engine_errors?: components["schemas"]["EngineErrorDetail"][];
+            /** @example 2.1 */
+            version: string;
+        };
+        EngineErrorDetail: {
+            /** @example bing */
+            engine: string;
+            /** @example blocked */
+            error: string;
+            /**
+             * @description Sanitized detail; proxy credentials are never included.
+             * @example blocked: 403
+             */
+            message?: string;
+        };
+        Pagination: {
+            /** @example 1 */
+            page: number;
+            /** @example true */
+            has_more: boolean;
+            /** @example 25 */
+            next_start: number;
+        };
+        Position: {
+            /**
+             * @description 1-based rank in the mixed SERP stream, across both organic and ad blocks. Always present so SEO callers can plot rank vs. on-page position without inferring it from result order.
+             * @example 2
+             */
+            absolute: number;
+        };
+        DomainInfo: {
+            /** @example org */
+            tld?: string;
+            /** @example wikipedia */
+            sld?: string;
+            /**
+             * @description Empty string when the domain matches no known category.
+             * @enum {string}
+             */
+            category: "" | "gov" | "edu" | "mil" | "news" | "forum" | "marketplace" | "social";
+        };
+        Classification: {
+            /**
+             * @example article
+             * @enum {string}
+             */
+            content_type?: "article" | "document" | "video" | "forum_thread" | "webpage";
+            /** @example encyclopedia */
+            source_hint?: string;
+        };
+        /**
+         * @description SERP block type. New values require a minor version bump (`meta.version: "2.1"`). In v2.1, engines may emit specialized modules such as `people_also_ask` when a parser can classify them reliably.
+         * @enum {string}
+         */
+        ResultType: "organic" | "ad" | "featured_snippet" | "knowledge_panel" | "people_also_ask" | "video" | "image" | "news" | "shopping" | "local" | "answer_box";
+        Result: {
+            /**
+             * @description Stable identifier: `s_` + hex(first 8 bytes of MD5(engine|normalized_url)). Normalized URL: lowercase scheme+host, trailing slash stripped, utm_*\/fbclid/gclid tracking params removed. Same URL → same ID across requests.
+             * @example s_a1b2c3d4e5f6a1b2
+             */
+            id: string;
+            /** @example 1 */
+            rank: number;
+            type: components["schemas"]["ResultType"];
+            /** @example The Go Programming Language */
+            title: string;
+            /** @example https://go.dev/ */
+            url: string;
+            /**
+             * @description Breadcrumb form of the URL (e.g. `go.dev › doc › install`).
+             * @example go.dev
+             */
+            display_url: string;
+            /** @example Go is an open source programming language... */
+            snippet: string;
+            /**
+             * @description Registrable domain with leading `www.` stripped.
+             * @example go.dev
+             */
+            domain: string;
+            /**
+             * @description Constructed as `https://{domain}/favicon.ico`. Not probed.
+             * @example https://go.dev/favicon.ico
+             */
+            favicon: string;
+            position: components["schemas"]["Position"];
+            /** @example google */
+            engine: string;
+            domain_info?: components["schemas"]["DomainInfo"];
+            classification?: components["schemas"]["Classification"];
+        };
+        ImageData: {
+            /** @example https://example.com/gopher.png */
+            url: string;
+            /** @example https://example.com/gopher-thumb.png */
+            thumbnail?: string;
+            /** @example 1200 */
+            width?: number;
+            /** @example 800 */
+            height?: number;
+        };
+        ImageSource: {
+            /** @example https://example.com/article-about-gophers */
+            page_url: string;
+            /** @example example.com */
+            domain: string;
+        };
+        ImageResult: {
+            /**
+             * @description Stable identifier prefixed with `i_`.
+             * @example i_a1b2c3d4e5f6a1b2
+             */
+            id: string;
+            /** @example 1 */
+            rank: number;
+            /** @enum {string} */
+            type: "image";
+            title: string;
+            image: components["schemas"]["ImageData"];
+            source: components["schemas"]["ImageSource"];
+            engine: string;
+        };
+        ClusterOccurrence: {
+            /** @example google */
+            engine: string;
+            /** @example 1 */
+            rank: number;
+            /** @example s_a1b2c3d4e5f6a1b2 */
+            result_id: string;
+        };
+        Cluster: {
+            /**
+             * @description Stable identifier: `c_` + hex(first 8 bytes of MD5(normalized_url)).
+             * @example c_a1b2c3d4e5f6a1b2
+             */
+            id: string;
+            /** @example https://go.dev/ */
+            canonical_url: string;
+            /** @example go.dev */
+            domain: string;
+            /** @example The Go Programming Language */
+            title: string;
+            occurrences: components["schemas"]["ClusterOccurrence"][];
+            /**
+             * @description Number of engines this URL appeared in.
+             * @example 3
+             */
+            engines_count: number;
+            /**
+             * @description Lowest (best) rank seen across all engines.
+             * @example 1
+             */
+            best_rank: number;
+            /**
+             * Format: float
+             * @description Cross-engine agreement score: sum(1/rank for each occurrence) / engines_queried, capped at 1.0. Higher is better.
+             * @example 0.92
+             */
+            score: number;
+        };
+        SearchEnvelope: {
+            query: components["schemas"]["QueryEcho"];
+            meta: components["schemas"]["ResponseMeta"];
+            results: components["schemas"]["Result"][];
+            pagination: components["schemas"]["Pagination"];
+        };
+        MegaSearchEnvelope: components["schemas"]["SearchEnvelope"] & {
+            /** @description Cross-engine clusters, sorted by score descending. Only present on /mega/search responses. Absent (not null) on single-engine endpoints. */
+            clusters?: components["schemas"]["Cluster"][] | null;
+        };
+        ImageEnvelope: {
+            query: components["schemas"]["QueryEcho"];
+            meta: components["schemas"]["ResponseMeta"];
+            results: components["schemas"]["ImageResult"][];
+            pagination: components["schemas"]["Pagination"];
+        };
+        ErrorResponse: {
+            /**
+             * @description Stable machine-readable error class. Search-pipeline failures use the following codes: `captcha_detected`, `blocked`, `rate_limited`, `search_timeout`, `proxy_connect`, `proxy_auth`, `proxy_timeout`, `proxy_unavailable`, `parser_failure`, `engine_internal`, `all_engines_failed`, `circuit_open`, `request_timeout`, `request_canceled`. Validation errors use `bad_request`. Other generic codes (`not_found`, `service_unavailable`, `server_error`, `client_error`, `error`) may appear for non-search routes.
+             * @example bad_request
+             * @enum {string}
+             */
+            error: "bad_request" | "not_found" | "rate_limited" | "service_unavailable" | "server_error" | "client_error" | "error" | "captcha_detected" | "blocked" | "search_timeout" | "proxy_connect" | "proxy_auth" | "proxy_timeout" | "proxy_unavailable" | "parser_failure" | "engine_internal" | "all_engines_failed" | "circuit_open" | "request_timeout" | "request_canceled";
+            /** @example 400 */
+            code: number;
+            /**
+             * @description Matches the `X-Request-ID` response header.
+             * @example 01HXYZ...
+             */
+            request_id?: string;
+            /** @example INVALID_LIMIT: limit must be between 1 and 100 */
+            message?: string;
+            /**
+             * @description Stable client-actionable reason code. Present on 400 errors. Known values: INVALID_LIMIT, INVALID_START, INVALID_PARAM, EMPTY_QUERY, NO_ENGINES, UNKNOWN_FORMAT, REQUEST_PROXY_URL_DISABLED, UNSUPPORTED_PROXY_SCHEME.
+             * @example INVALID_LIMIT
+             */
+            reason?: string;
+            /** @description Sanitized context for search-pipeline errors. Credentials are never included. */
+            meta?: {
+                /** @example google */
+                engine?: string;
+                /**
+                 * @description Masked `scheme://host:port`; never includes credentials.
+                 * @example http://proxy.example:8080
+                 */
+                proxy_used?: string;
+                /** @example us */
+                proxy_country?: string;
+                /** @example residential */
+                proxy_class?: string;
+                /** @example webshare */
+                proxy_provider?: string;
+                /** @example sid-123 */
+                proxy_session_id?: string;
+                /**
+                 * @description Sanitized underlying error detail when available.
+                 * @example proxy_connect: dial tcp proxy.example:8080: connection refused
+                 */
+                error_detail?: string;
+                engine_errors?: components["schemas"]["EngineErrorDetail"][];
+            } & {
+                [key: string]: unknown;
+            };
+        };
+        EngineHealth: {
+            /** @example google */
+            name: string;
+            /** @example true */
+            initialized: boolean;
+            /** @enum {string} */
+            status: "ready" | "not_initialized" | "circuit_open";
+        };
+        HealthStatus: {
+            /** @enum {string} */
+            status: "healthy" | "degraded" | "unhealthy";
+            /** @example 1h12m3s */
+            uptime: string;
+            engines: components["schemas"]["EngineHealth"][];
+            system: {
+                [key: string]: unknown;
+            };
+        };
+        ReadinessStatus: {
+            /** @enum {string} */
+            status: "ready" | "draining";
+        };
+        CacheStatsEnabled: {
+            /** @enum {boolean} */
+            status: true;
+            entries: number;
+            hits: number;
+            misses: number;
+            bypasses: number;
+            evictions: number;
+            ttl_seconds: number;
+            max_size: number;
+        };
+        CacheStatsDisabled: {
+            /** @enum {boolean} */
+            status: false;
+        };
+        CacheStats: components["schemas"]["CacheStatsEnabled"] | components["schemas"]["CacheStatsDisabled"];
+        ProxyTagSummary: {
+            configured: number;
+            healthy: number;
+        };
+        ProxyStatsEntry: {
+            proxy: string;
+            tags: string[];
+            healthy: boolean;
+            failures: number;
+            disabled: boolean;
+        };
+        ProxyEngineStats: {
+            tag?: string;
+            selected_proxy: string;
+        };
+        /** @description Sticky proxy lane state observed by this worker. */
+        LaneStats: {
+            /**
+             * @description Number of lanes currently held by the worker.
+             * @example 12
+             */
+            active: number;
+            /**
+             * @description Lanes evicted by the LRU bound since worker start.
+             * @example 7
+             */
+            evicted_lru: number;
+            /**
+             * @description Lane cookie drops triggered by captcha/challenge responses.
+             * @example 20
+             */
+            cookies_dropped: number;
+        };
+        /** @description Live state of the per-process Chrome pool. Each authenticated upstream proxy identity (scheme+host+port+username) gets a dedicated Chrome so Chrome can answer 407 challenges natively. Direct and unauthenticated proxies share one Chrome with per-BrowserContext proxy override. */
+        BrowserPoolStats: {
+            /**
+             * @description Number of Chrome processes currently held by the pool.
+             * @example 3
+             */
+            active: number;
+            /**
+             * @description Configured `app.max_processes` LRU cap.
+             * @example 4
+             */
+            max: number;
+            /**
+             * @description Chrome processes closed because the LRU cap was exceeded.
+             * @example 12
+             */
+            evicted_lru: number;
+            /**
+             * @description Chrome processes closed by the idle sweeper after `app.idle_ttl`.
+             * @example 5
+             */
+            evicted_idle: number;
+        };
+        ProxyStats: {
+            configured_count: number;
+            healthy_count: number;
+            unhealthy_count: number;
+            /** @description Whether `proxies.allow_request_proxy_url` is enabled on this worker. */
+            request_proxy_url_enabled: boolean;
+            lanes: components["schemas"]["LaneStats"];
+            browser_processes: components["schemas"]["BrowserPoolStats"];
+            tags: {
+                [key: string]: components["schemas"]["ProxyTagSummary"];
+            };
+            entries: components["schemas"]["ProxyStatsEntry"][];
+            engines?: {
+                [key: string]: components["schemas"]["ProxyEngineStats"];
+            };
+        };
+        CircuitBreakerStat: {
+            engine: string;
+            /** @enum {string} */
+            state: "closed" | "open" | "half-open";
+            failure_count: number;
+            /** Format: date-time */
+            last_changed: string;
+            /** @description Seconds until next half-open attempt (present when state is open). */
+            retry_in?: number;
+            /** @description Average successful engine response time in milliseconds. */
+            avg_response_ms?: number;
+        };
+        CircuitBreakerStatsResponse: {
+            circuit_breakers: components["schemas"]["CircuitBreakerStat"][];
+        };
+        StatsResponse: {
+            cache: components["schemas"]["CacheStats"];
+            proxy: components["schemas"]["ProxyStats"];
+            circuit_breakers: components["schemas"]["CircuitBreakerStat"][];
+        };
+        MegaEngineInfo: {
+            name: string;
+            initialized: boolean;
+            /** @enum {string} */
+            circuit_state?: "closed" | "open" | "half-open";
+        };
+        MegaEnginesResponse: {
+            engines: components["schemas"]["MegaEngineInfo"][];
+            total: number;
+        };
+    };
+    responses: {
+        /** @description Invalid request parameters */
+        BadRequestError: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+        /** @description The search engine blocked the request */
+        ForbiddenError: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+        /** @description Captcha challenge or rate-limit response from the search engine */
+        TooManyRequestsError: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+        /** @description Engine internal failure, parser drift, or all-engine failure when fallback is enabled. */
+        BadGatewayError: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+        /** @description Search timed out waiting for required SERP elements */
+        GatewayTimeoutError: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+        /** @description Proxy-layer failure (no healthy proxy or transport error). The search itself was not produced. */
+        ServiceUnavailableError: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+        /** @description Endpoint not found */
+        NotFoundError: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+        /** @description Internal error while handling request */
+        InternalServerError: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+    };
+    parameters: {
+        /** @description Search engine endpoint alias (`duck` is DuckDuckGo). */
+        EnginePath: "google" | "yandex" | "baidu" | "bing" | "duck" | "ecosia";
+        /**
+         * @description Search query text. At least one of `text`, `site`, or `file` must be non-empty.
+         * @example golang
+         */
+        TextQuery: string;
+        /**
+         * @description Language code (engine-specific behavior).
+         * @example EN
+         */
+        LangQuery: string;
+        /** @description Market/location hint. Yandex accepts numeric `lr` region IDs such as `213`; Google, Bing, and DuckDuckGo use country/locale-style hints such as `RU`, `US`, or `en-GB` where supported. */
+        RegionQuery: string;
+        /**
+         * @description Date interval in `YYYYMMDD..YYYYMMDD` format.
+         * @example 20250101..20250131
+         */
+        DateQuery: string;
+        /**
+         * @description File extension filter (for engines that support it).
+         * @example PDF
+         */
+        FileQuery: string;
+        /**
+         * @description Site/domain filter.
+         * @example github.com
+         */
+        SiteQuery: string;
+        /**
+         * @description Maximum organic results to return (1–100). Ads may be returned in addition.
+         * @example 10
+         */
+        LimitQuery: number;
+        /**
+         * @description Pagination offset (must be >= 0).
+         * @example 20
+         */
+        StartQuery: number;
+        /** @description Duplicate filtering flag (primarily used by Google parser behavior). */
+        FilterQuery: boolean;
+        /** @description Include answer box style results when supported. */
+        AnswersQuery: boolean;
+        /**
+         * @description Comma-separated engine list for mega endpoints. If omitted, all available engines are used.
+         * @example google,bing,duckduckgo
+         */
+        EnginesQuery: string;
+        /** @description Mega execution mode. `balanced` (default) runs all selected engines in parallel. `any` runs selected engines sequentially in request order until first success. `fast` runs only one engine: the fastest by circuit-breaker average response time. */
+        MegaModeQuery: "balanced" | "any" | "fast";
+        /** @description Enable deduplication by normalized URL. Default `true`. */
+        MegaDedupeQuery: boolean;
+        /** @description Merge results from all successful engines into one flat list. Default `true`. When `false`, only the first requested engine that returned results is kept. */
+        MegaMergeQuery: boolean;
+        /** @description Output format. `json` (default) returns the envelope. `markdown` returns a Markdown document suitable for Slack/email. `text` returns a minimal plain-text block optimised for LLM context windows. `ndjson` returns one result object per line with no envelope. The `Accept` header is also checked (`text/markdown`, `text/plain`, `application/x-ndjson`). */
+        FormatQuery: "json" | "markdown" | "text" | "ndjson";
+        /** @description Request-scoped proxy override. Use `direct` to disable proxy or a tag name to force a specific proxy pool. */
+        UseProxyHeader: string;
+        /**
+         * @description Per-request proxy URL supplied by an upstream balancer. Honored only when `proxies.allow_request_proxy_url: true` is set on the worker; otherwise the request is rejected with `400 bad_request` and `reason=REQUEST_PROXY_URL_DISABLED`. Authenticated SOCKS proxies are rejected in browser mode (`reason=UNSUPPORTED_PROXY_SCHEME`). Credentials are never logged or returned. Precedence: `X-Use-Proxy: direct` > `X-Proxy-URL` > `X-Use-Proxy: <tag>` > per-engine configured tag > `proxies.global` > direct.
+         * @example http://user:pass@proxy.example:8080
+         */
+        ProxyURLHeader: string;
+        /**
+         * @description Two-letter market country code for the supplied proxy. Used as part of the cache key so different markets do not share results.
+         * @example us
+         */
+        ProxyCountryHeader: string;
+        /**
+         * @description Proxy class identifier (e.g. `datacenter`, `residential`, `mobile`). Part of the cache key.
+         * @example residential
+         */
+        ProxyClassHeader: string;
+        /**
+         * @description Upstream proxy provider identifier (e.g. `webshare`, `brightdata`). Part of the cache key.
+         * @example webshare
+         */
+        ProxyProviderHeader: string;
+        /**
+         * @description Sticky session identifier minted by the balancer. Reusing the same value lets OpenSERP reuse cookies and browser profile for that lane. Lanes are LRU-bounded by `proxies.lanes.max_lanes`. Rotating the session ID gives a clean lane.
+         * @example sid-123
+         */
+        ProxySessionIDHeader: string;
+        /** @description Optional tenant scope used to namespace sticky lane state across multi-tenant deployments. When present, lanes are keyed by `tenant + engine + session_id`. */
+        TenantHeader: string;
+    };
+    requestBodies: never;
+    headers: {
+        /** @description UUID v7 request identifier. Matches `meta.request_id` in the response body and appears in server logs for correlation. */
+        XRequestID: string;
+        /** @description Cache status when cache is enabled (`HIT`, `MISS`, `BYPASS`). */
+        XCache: "HIT" | "MISS" | "BYPASS";
+        /** @description Engine name used when dedicated endpoint fallback served the response. */
+        XFallbackEngine: string;
+        /** @description Effective proxy mode for the request. `request_url` indicates a per-request `X-Proxy-URL` was honored. */
+        XProxyMode: "off" | "tag_pool" | "request_url";
+        /** @description Effective proxy tag when `X-Proxy-Mode=tag_pool`. Header is omitted when no tag is in effect (i.e. `X-Proxy-Mode` is `request_url` or `off`). */
+        XProxyTag: string;
+        /** @description Effective proxy target used. Values: `direct`, masked `scheme://host:port` URL, `pooled`, `multiple`, or `mixed`. Credentials are never included. */
+        XProxyUsed: string;
+        /** @description Aggregate inbound network bytes consumed while executing the search request. Single-engine endpoints report that engine's request bytes; mega endpoints report the sum across selected engines. Cache hits return `0`. */
+        XNetworkBytes: number;
+        /** @description Browser profile ID selected for browser-mode execution. Mega endpoints may return a comma-separated list when multiple profiles were used. */
+        XBrowserProfileID: string;
+    };
+    pathItems: never;
+}
+type $defs = Record<string, never>;
+interface operations {
+    searchWeb: {
+        parameters: {
+            query?: {
+                /**
+                 * @description Search query text. At least one of `text`, `site`, or `file` must be non-empty.
+                 * @example golang
+                 */
+                text?: components["parameters"]["TextQuery"];
+                /**
+                 * @description Language code (engine-specific behavior).
+                 * @example EN
+                 */
+                lang?: components["parameters"]["LangQuery"];
+                /** @description Market/location hint. Yandex accepts numeric `lr` region IDs such as `213`; Google, Bing, and DuckDuckGo use country/locale-style hints such as `RU`, `US`, or `en-GB` where supported. */
+                region?: components["parameters"]["RegionQuery"];
+                /**
+                 * @description Date interval in `YYYYMMDD..YYYYMMDD` format.
+                 * @example 20250101..20250131
+                 */
+                date?: components["parameters"]["DateQuery"];
+                /**
+                 * @description File extension filter (for engines that support it).
+                 * @example PDF
+                 */
+                file?: components["parameters"]["FileQuery"];
+                /**
+                 * @description Site/domain filter.
+                 * @example github.com
+                 */
+                site?: components["parameters"]["SiteQuery"];
+                /**
+                 * @description Maximum organic results to return (1–100). Ads may be returned in addition.
+                 * @example 10
+                 */
+                limit?: components["parameters"]["LimitQuery"];
+                /**
+                 * @description Pagination offset (must be >= 0).
+                 * @example 20
+                 */
+                start?: components["parameters"]["StartQuery"];
+                /** @description Duplicate filtering flag (primarily used by Google parser behavior). */
+                filter?: components["parameters"]["FilterQuery"];
+                /** @description Include answer box style results when supported. */
+                answers?: components["parameters"]["AnswersQuery"];
+                /** @description Output format. `json` (default) returns the envelope. `markdown` returns a Markdown document suitable for Slack/email. `text` returns a minimal plain-text block optimised for LLM context windows. `ndjson` returns one result object per line with no envelope. The `Accept` header is also checked (`text/markdown`, `text/plain`, `application/x-ndjson`). */
+                format?: components["parameters"]["FormatQuery"];
+            };
+            header?: {
+                /** @description Request-scoped proxy override. Use `direct` to disable proxy or a tag name to force a specific proxy pool. */
+                "X-Use-Proxy"?: components["parameters"]["UseProxyHeader"];
+                /**
+                 * @description Per-request proxy URL supplied by an upstream balancer. Honored only when `proxies.allow_request_proxy_url: true` is set on the worker; otherwise the request is rejected with `400 bad_request` and `reason=REQUEST_PROXY_URL_DISABLED`. Authenticated SOCKS proxies are rejected in browser mode (`reason=UNSUPPORTED_PROXY_SCHEME`). Credentials are never logged or returned. Precedence: `X-Use-Proxy: direct` > `X-Proxy-URL` > `X-Use-Proxy: <tag>` > per-engine configured tag > `proxies.global` > direct.
+                 * @example http://user:pass@proxy.example:8080
+                 */
+                "X-Proxy-URL"?: components["parameters"]["ProxyURLHeader"];
+                /**
+                 * @description Two-letter market country code for the supplied proxy. Used as part of the cache key so different markets do not share results.
+                 * @example us
+                 */
+                "X-Proxy-Country"?: components["parameters"]["ProxyCountryHeader"];
+                /**
+                 * @description Proxy class identifier (e.g. `datacenter`, `residential`, `mobile`). Part of the cache key.
+                 * @example residential
+                 */
+                "X-Proxy-Class"?: components["parameters"]["ProxyClassHeader"];
+                /**
+                 * @description Upstream proxy provider identifier (e.g. `webshare`, `brightdata`). Part of the cache key.
+                 * @example webshare
+                 */
+                "X-Proxy-Provider"?: components["parameters"]["ProxyProviderHeader"];
+                /**
+                 * @description Sticky session identifier minted by the balancer. Reusing the same value lets OpenSERP reuse cookies and browser profile for that lane. Lanes are LRU-bounded by `proxies.lanes.max_lanes`. Rotating the session ID gives a clean lane.
+                 * @example sid-123
+                 */
+                "X-Proxy-Session-ID"?: components["parameters"]["ProxySessionIDHeader"];
+                /** @description Optional tenant scope used to namespace sticky lane state across multi-tenant deployments. When present, lanes are keyed by `tenant + engine + session_id`. */
+                "X-Tenant"?: components["parameters"]["TenantHeader"];
+            };
+            path: {
+                /** @description Search engine endpoint alias (`duck` is DuckDuckGo). */
+                engine: components["parameters"]["EnginePath"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Search results envelope */
+            200: {
+                headers: {
+                    "X-Request-ID": components["headers"]["XRequestID"];
+                    "X-Cache": components["headers"]["XCache"];
+                    "X-Fallback-Engine": components["headers"]["XFallbackEngine"];
+                    "X-Proxy-Mode": components["headers"]["XProxyMode"];
+                    "X-Proxy-Tag": components["headers"]["XProxyTag"];
+                    "X-Proxy-Used": components["headers"]["XProxyUsed"];
+                    "X-Network-Bytes": components["headers"]["XNetworkBytes"];
+                    "X-Browser-Profile-Id": components["headers"]["XBrowserProfileID"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SearchEnvelope"];
+                    "text/markdown": string;
+                    "text/plain": string;
+                    "application/x-ndjson": string;
+                };
+            };
+            400: components["responses"]["BadRequestError"];
+            403: components["responses"]["ForbiddenError"];
+            404: components["responses"]["NotFoundError"];
+            429: components["responses"]["TooManyRequestsError"];
+            500: components["responses"]["InternalServerError"];
+            502: components["responses"]["BadGatewayError"];
+            503: components["responses"]["ServiceUnavailableError"];
+            504: components["responses"]["GatewayTimeoutError"];
+        };
+    };
+    searchImages: {
+        parameters: {
+            query?: {
+                /**
+                 * @description Search query text. At least one of `text`, `site`, or `file` must be non-empty.
+                 * @example golang
+                 */
+                text?: components["parameters"]["TextQuery"];
+                /**
+                 * @description Language code (engine-specific behavior).
+                 * @example EN
+                 */
+                lang?: components["parameters"]["LangQuery"];
+                /** @description Market/location hint. Yandex accepts numeric `lr` region IDs such as `213`; Google, Bing, and DuckDuckGo use country/locale-style hints such as `RU`, `US`, or `en-GB` where supported. */
+                region?: components["parameters"]["RegionQuery"];
+                /**
+                 * @description Date interval in `YYYYMMDD..YYYYMMDD` format.
+                 * @example 20250101..20250131
+                 */
+                date?: components["parameters"]["DateQuery"];
+                /**
+                 * @description File extension filter (for engines that support it).
+                 * @example PDF
+                 */
+                file?: components["parameters"]["FileQuery"];
+                /**
+                 * @description Site/domain filter.
+                 * @example github.com
+                 */
+                site?: components["parameters"]["SiteQuery"];
+                /**
+                 * @description Maximum organic results to return (1–100). Ads may be returned in addition.
+                 * @example 10
+                 */
+                limit?: components["parameters"]["LimitQuery"];
+                /**
+                 * @description Pagination offset (must be >= 0).
+                 * @example 20
+                 */
+                start?: components["parameters"]["StartQuery"];
+                /** @description Duplicate filtering flag (primarily used by Google parser behavior). */
+                filter?: components["parameters"]["FilterQuery"];
+                /** @description Include answer box style results when supported. */
+                answers?: components["parameters"]["AnswersQuery"];
+                /** @description Output format. `json` (default) returns the envelope. `markdown` returns a Markdown document suitable for Slack/email. `text` returns a minimal plain-text block optimised for LLM context windows. `ndjson` returns one result object per line with no envelope. The `Accept` header is also checked (`text/markdown`, `text/plain`, `application/x-ndjson`). */
+                format?: components["parameters"]["FormatQuery"];
+            };
+            header?: {
+                /** @description Request-scoped proxy override. Use `direct` to disable proxy or a tag name to force a specific proxy pool. */
+                "X-Use-Proxy"?: components["parameters"]["UseProxyHeader"];
+                /**
+                 * @description Per-request proxy URL supplied by an upstream balancer. Honored only when `proxies.allow_request_proxy_url: true` is set on the worker; otherwise the request is rejected with `400 bad_request` and `reason=REQUEST_PROXY_URL_DISABLED`. Authenticated SOCKS proxies are rejected in browser mode (`reason=UNSUPPORTED_PROXY_SCHEME`). Credentials are never logged or returned. Precedence: `X-Use-Proxy: direct` > `X-Proxy-URL` > `X-Use-Proxy: <tag>` > per-engine configured tag > `proxies.global` > direct.
+                 * @example http://user:pass@proxy.example:8080
+                 */
+                "X-Proxy-URL"?: components["parameters"]["ProxyURLHeader"];
+                /**
+                 * @description Two-letter market country code for the supplied proxy. Used as part of the cache key so different markets do not share results.
+                 * @example us
+                 */
+                "X-Proxy-Country"?: components["parameters"]["ProxyCountryHeader"];
+                /**
+                 * @description Proxy class identifier (e.g. `datacenter`, `residential`, `mobile`). Part of the cache key.
+                 * @example residential
+                 */
+                "X-Proxy-Class"?: components["parameters"]["ProxyClassHeader"];
+                /**
+                 * @description Upstream proxy provider identifier (e.g. `webshare`, `brightdata`). Part of the cache key.
+                 * @example webshare
+                 */
+                "X-Proxy-Provider"?: components["parameters"]["ProxyProviderHeader"];
+                /**
+                 * @description Sticky session identifier minted by the balancer. Reusing the same value lets OpenSERP reuse cookies and browser profile for that lane. Lanes are LRU-bounded by `proxies.lanes.max_lanes`. Rotating the session ID gives a clean lane.
+                 * @example sid-123
+                 */
+                "X-Proxy-Session-ID"?: components["parameters"]["ProxySessionIDHeader"];
+                /** @description Optional tenant scope used to namespace sticky lane state across multi-tenant deployments. When present, lanes are keyed by `tenant + engine + session_id`. */
+                "X-Tenant"?: components["parameters"]["TenantHeader"];
+            };
+            path: {
+                /** @description Search engine endpoint alias (`duck` is DuckDuckGo). */
+                engine: components["parameters"]["EnginePath"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Image search results envelope */
+            200: {
+                headers: {
+                    "X-Request-ID": components["headers"]["XRequestID"];
+                    "X-Cache": components["headers"]["XCache"];
+                    "X-Fallback-Engine": components["headers"]["XFallbackEngine"];
+                    "X-Proxy-Mode": components["headers"]["XProxyMode"];
+                    "X-Proxy-Tag": components["headers"]["XProxyTag"];
+                    "X-Proxy-Used": components["headers"]["XProxyUsed"];
+                    "X-Network-Bytes": components["headers"]["XNetworkBytes"];
+                    "X-Browser-Profile-Id": components["headers"]["XBrowserProfileID"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ImageEnvelope"];
+                };
+            };
+            400: components["responses"]["BadRequestError"];
+            403: components["responses"]["ForbiddenError"];
+            404: components["responses"]["NotFoundError"];
+            429: components["responses"]["TooManyRequestsError"];
+            500: components["responses"]["InternalServerError"];
+            502: components["responses"]["BadGatewayError"];
+            503: components["responses"]["ServiceUnavailableError"];
+            504: components["responses"]["GatewayTimeoutError"];
+        };
+    };
+    parseGoogleHTML: {
+        parameters: {
+            query?: {
+                /** @description Output format. `json` (default) returns the envelope. `markdown` returns a Markdown document suitable for Slack/email. `text` returns a minimal plain-text block optimised for LLM context windows. `ndjson` returns one result object per line with no envelope. The `Accept` header is also checked (`text/markdown`, `text/plain`, `application/x-ndjson`). */
+                format?: components["parameters"]["FormatQuery"];
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "text/html": string;
+            };
+        };
+        responses: {
+            /** @description Parsed search results envelope */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SearchEnvelope"];
+                    "text/markdown": string;
+                    "text/plain": string;
+                    "application/x-ndjson": string;
+                };
+            };
+            400: components["responses"]["BadRequestError"];
+            500: components["responses"]["InternalServerError"];
+        };
+    };
+    parseBingHTML: {
+        parameters: {
+            query?: {
+                /** @description Output format. `json` (default) returns the envelope. `markdown` returns a Markdown document suitable for Slack/email. `text` returns a minimal plain-text block optimised for LLM context windows. `ndjson` returns one result object per line with no envelope. The `Accept` header is also checked (`text/markdown`, `text/plain`, `application/x-ndjson`). */
+                format?: components["parameters"]["FormatQuery"];
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "text/html": string;
+            };
+        };
+        responses: {
+            /** @description Parsed search results envelope */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SearchEnvelope"];
+                    "text/markdown": string;
+                    "text/plain": string;
+                    "application/x-ndjson": string;
+                };
+            };
+            400: components["responses"]["BadRequestError"];
+            500: components["responses"]["InternalServerError"];
+        };
+    };
+    megaSearch: {
+        parameters: {
+            query?: {
+                /**
+                 * @description Search query text. At least one of `text`, `site`, or `file` must be non-empty.
+                 * @example golang
+                 */
+                text?: components["parameters"]["TextQuery"];
+                /**
+                 * @description Language code (engine-specific behavior).
+                 * @example EN
+                 */
+                lang?: components["parameters"]["LangQuery"];
+                /** @description Market/location hint. Yandex accepts numeric `lr` region IDs such as `213`; Google, Bing, and DuckDuckGo use country/locale-style hints such as `RU`, `US`, or `en-GB` where supported. */
+                region?: components["parameters"]["RegionQuery"];
+                /**
+                 * @description Date interval in `YYYYMMDD..YYYYMMDD` format.
+                 * @example 20250101..20250131
+                 */
+                date?: components["parameters"]["DateQuery"];
+                /**
+                 * @description File extension filter (for engines that support it).
+                 * @example PDF
+                 */
+                file?: components["parameters"]["FileQuery"];
+                /**
+                 * @description Site/domain filter.
+                 * @example github.com
+                 */
+                site?: components["parameters"]["SiteQuery"];
+                /**
+                 * @description Maximum organic results to return (1–100). Ads may be returned in addition.
+                 * @example 10
+                 */
+                limit?: components["parameters"]["LimitQuery"];
+                /**
+                 * @description Pagination offset (must be >= 0).
+                 * @example 20
+                 */
+                start?: components["parameters"]["StartQuery"];
+                /** @description Duplicate filtering flag (primarily used by Google parser behavior). */
+                filter?: components["parameters"]["FilterQuery"];
+                /** @description Include answer box style results when supported. */
+                answers?: components["parameters"]["AnswersQuery"];
+                /**
+                 * @description Comma-separated engine list for mega endpoints. If omitted, all available engines are used.
+                 * @example google,bing,duckduckgo
+                 */
+                engines?: components["parameters"]["EnginesQuery"];
+                /** @description Mega execution mode. `balanced` (default) runs all selected engines in parallel. `any` runs selected engines sequentially in request order until first success. `fast` runs only one engine: the fastest by circuit-breaker average response time. */
+                mode?: components["parameters"]["MegaModeQuery"];
+                /** @description Enable deduplication by normalized URL. Default `true`. */
+                dedupe?: components["parameters"]["MegaDedupeQuery"];
+                /** @description Merge results from all successful engines into one flat list. Default `true`. When `false`, only the first requested engine that returned results is kept. */
+                merge?: components["parameters"]["MegaMergeQuery"];
+                /** @description Output format. `json` (default) returns the envelope. `markdown` returns a Markdown document suitable for Slack/email. `text` returns a minimal plain-text block optimised for LLM context windows. `ndjson` returns one result object per line with no envelope. The `Accept` header is also checked (`text/markdown`, `text/plain`, `application/x-ndjson`). */
+                format?: components["parameters"]["FormatQuery"];
+            };
+            header?: {
+                /** @description Request-scoped proxy override. Use `direct` to disable proxy or a tag name to force a specific proxy pool. */
+                "X-Use-Proxy"?: components["parameters"]["UseProxyHeader"];
+                /**
+                 * @description Per-request proxy URL supplied by an upstream balancer. Honored only when `proxies.allow_request_proxy_url: true` is set on the worker; otherwise the request is rejected with `400 bad_request` and `reason=REQUEST_PROXY_URL_DISABLED`. Authenticated SOCKS proxies are rejected in browser mode (`reason=UNSUPPORTED_PROXY_SCHEME`). Credentials are never logged or returned. Precedence: `X-Use-Proxy: direct` > `X-Proxy-URL` > `X-Use-Proxy: <tag>` > per-engine configured tag > `proxies.global` > direct.
+                 * @example http://user:pass@proxy.example:8080
+                 */
+                "X-Proxy-URL"?: components["parameters"]["ProxyURLHeader"];
+                /**
+                 * @description Two-letter market country code for the supplied proxy. Used as part of the cache key so different markets do not share results.
+                 * @example us
+                 */
+                "X-Proxy-Country"?: components["parameters"]["ProxyCountryHeader"];
+                /**
+                 * @description Proxy class identifier (e.g. `datacenter`, `residential`, `mobile`). Part of the cache key.
+                 * @example residential
+                 */
+                "X-Proxy-Class"?: components["parameters"]["ProxyClassHeader"];
+                /**
+                 * @description Upstream proxy provider identifier (e.g. `webshare`, `brightdata`). Part of the cache key.
+                 * @example webshare
+                 */
+                "X-Proxy-Provider"?: components["parameters"]["ProxyProviderHeader"];
+                /**
+                 * @description Sticky session identifier minted by the balancer. Reusing the same value lets OpenSERP reuse cookies and browser profile for that lane. Lanes are LRU-bounded by `proxies.lanes.max_lanes`. Rotating the session ID gives a clean lane.
+                 * @example sid-123
+                 */
+                "X-Proxy-Session-ID"?: components["parameters"]["ProxySessionIDHeader"];
+                /** @description Optional tenant scope used to namespace sticky lane state across multi-tenant deployments. When present, lanes are keyed by `tenant + engine + session_id`. */
+                "X-Tenant"?: components["parameters"]["TenantHeader"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Aggregated envelope with clusters */
+            200: {
+                headers: {
+                    "X-Request-ID": components["headers"]["XRequestID"];
+                    "X-Cache": components["headers"]["XCache"];
+                    "X-Proxy-Mode": components["headers"]["XProxyMode"];
+                    "X-Proxy-Tag": components["headers"]["XProxyTag"];
+                    "X-Proxy-Used": components["headers"]["XProxyUsed"];
+                    "X-Network-Bytes": components["headers"]["XNetworkBytes"];
+                    "X-Browser-Profile-Id": components["headers"]["XBrowserProfileID"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MegaSearchEnvelope"];
+                    "text/markdown": string;
+                    "text/plain": string;
+                    "application/x-ndjson": string;
+                };
+            };
+            400: components["responses"]["BadRequestError"];
+            403: components["responses"]["ForbiddenError"];
+            429: components["responses"]["TooManyRequestsError"];
+            500: components["responses"]["InternalServerError"];
+            502: components["responses"]["BadGatewayError"];
+            503: components["responses"]["ServiceUnavailableError"];
+            504: components["responses"]["GatewayTimeoutError"];
+        };
+    };
+    megaImageSearch: {
+        parameters: {
+            query?: {
+                /**
+                 * @description Search query text. At least one of `text`, `site`, or `file` must be non-empty.
+                 * @example golang
+                 */
+                text?: components["parameters"]["TextQuery"];
+                /**
+                 * @description Language code (engine-specific behavior).
+                 * @example EN
+                 */
+                lang?: components["parameters"]["LangQuery"];
+                /** @description Market/location hint. Yandex accepts numeric `lr` region IDs such as `213`; Google, Bing, and DuckDuckGo use country/locale-style hints such as `RU`, `US`, or `en-GB` where supported. */
+                region?: components["parameters"]["RegionQuery"];
+                /**
+                 * @description Date interval in `YYYYMMDD..YYYYMMDD` format.
+                 * @example 20250101..20250131
+                 */
+                date?: components["parameters"]["DateQuery"];
+                /**
+                 * @description File extension filter (for engines that support it).
+                 * @example PDF
+                 */
+                file?: components["parameters"]["FileQuery"];
+                /**
+                 * @description Site/domain filter.
+                 * @example github.com
+                 */
+                site?: components["parameters"]["SiteQuery"];
+                /**
+                 * @description Maximum organic results to return (1–100). Ads may be returned in addition.
+                 * @example 10
+                 */
+                limit?: components["parameters"]["LimitQuery"];
+                /**
+                 * @description Pagination offset (must be >= 0).
+                 * @example 20
+                 */
+                start?: components["parameters"]["StartQuery"];
+                /** @description Duplicate filtering flag (primarily used by Google parser behavior). */
+                filter?: components["parameters"]["FilterQuery"];
+                /** @description Include answer box style results when supported. */
+                answers?: components["parameters"]["AnswersQuery"];
+                /**
+                 * @description Comma-separated engine list for mega endpoints. If omitted, all available engines are used.
+                 * @example google,bing,duckduckgo
+                 */
+                engines?: components["parameters"]["EnginesQuery"];
+                /** @description Mega execution mode. `balanced` (default) runs all selected engines in parallel. `any` runs selected engines sequentially in request order until first success. `fast` runs only one engine: the fastest by circuit-breaker average response time. */
+                mode?: components["parameters"]["MegaModeQuery"];
+                /** @description Enable deduplication by normalized URL. Default `true`. */
+                dedupe?: components["parameters"]["MegaDedupeQuery"];
+                /** @description Merge results from all successful engines into one flat list. Default `true`. When `false`, only the first requested engine that returned results is kept. */
+                merge?: components["parameters"]["MegaMergeQuery"];
+                /** @description Output format. `json` (default) returns the envelope. `markdown` returns a Markdown document suitable for Slack/email. `text` returns a minimal plain-text block optimised for LLM context windows. `ndjson` returns one result object per line with no envelope. The `Accept` header is also checked (`text/markdown`, `text/plain`, `application/x-ndjson`). */
+                format?: components["parameters"]["FormatQuery"];
+            };
+            header?: {
+                /** @description Request-scoped proxy override. Use `direct` to disable proxy or a tag name to force a specific proxy pool. */
+                "X-Use-Proxy"?: components["parameters"]["UseProxyHeader"];
+                /**
+                 * @description Per-request proxy URL supplied by an upstream balancer. Honored only when `proxies.allow_request_proxy_url: true` is set on the worker; otherwise the request is rejected with `400 bad_request` and `reason=REQUEST_PROXY_URL_DISABLED`. Authenticated SOCKS proxies are rejected in browser mode (`reason=UNSUPPORTED_PROXY_SCHEME`). Credentials are never logged or returned. Precedence: `X-Use-Proxy: direct` > `X-Proxy-URL` > `X-Use-Proxy: <tag>` > per-engine configured tag > `proxies.global` > direct.
+                 * @example http://user:pass@proxy.example:8080
+                 */
+                "X-Proxy-URL"?: components["parameters"]["ProxyURLHeader"];
+                /**
+                 * @description Two-letter market country code for the supplied proxy. Used as part of the cache key so different markets do not share results.
+                 * @example us
+                 */
+                "X-Proxy-Country"?: components["parameters"]["ProxyCountryHeader"];
+                /**
+                 * @description Proxy class identifier (e.g. `datacenter`, `residential`, `mobile`). Part of the cache key.
+                 * @example residential
+                 */
+                "X-Proxy-Class"?: components["parameters"]["ProxyClassHeader"];
+                /**
+                 * @description Upstream proxy provider identifier (e.g. `webshare`, `brightdata`). Part of the cache key.
+                 * @example webshare
+                 */
+                "X-Proxy-Provider"?: components["parameters"]["ProxyProviderHeader"];
+                /**
+                 * @description Sticky session identifier minted by the balancer. Reusing the same value lets OpenSERP reuse cookies and browser profile for that lane. Lanes are LRU-bounded by `proxies.lanes.max_lanes`. Rotating the session ID gives a clean lane.
+                 * @example sid-123
+                 */
+                "X-Proxy-Session-ID"?: components["parameters"]["ProxySessionIDHeader"];
+                /** @description Optional tenant scope used to namespace sticky lane state across multi-tenant deployments. When present, lanes are keyed by `tenant + engine + session_id`. */
+                "X-Tenant"?: components["parameters"]["TenantHeader"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Aggregated image results envelope */
+            200: {
+                headers: {
+                    "X-Request-ID": components["headers"]["XRequestID"];
+                    "X-Cache": components["headers"]["XCache"];
+                    "X-Proxy-Mode": components["headers"]["XProxyMode"];
+                    "X-Proxy-Tag": components["headers"]["XProxyTag"];
+                    "X-Proxy-Used": components["headers"]["XProxyUsed"];
+                    "X-Network-Bytes": components["headers"]["XNetworkBytes"];
+                    "X-Browser-Profile-Id": components["headers"]["XBrowserProfileID"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ImageEnvelope"];
+                };
+            };
+            400: components["responses"]["BadRequestError"];
+            403: components["responses"]["ForbiddenError"];
+            429: components["responses"]["TooManyRequestsError"];
+            500: components["responses"]["InternalServerError"];
+            502: components["responses"]["BadGatewayError"];
+            503: components["responses"]["ServiceUnavailableError"];
+            504: components["responses"]["GatewayTimeoutError"];
+        };
+    };
+    listMegaEngines: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Engine list */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MegaEnginesResponse"];
+                };
+            };
+        };
+    };
+    healthCheck: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Healthy or degraded service */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HealthStatus"];
+                };
+            };
+            /** @description Unhealthy service */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HealthStatus"];
+                };
+            };
+        };
+    };
+    readinessCheck: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Instance is ready */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ReadinessStatus"];
+                };
+            };
+            /** @description Instance is draining */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ReadinessStatus"];
+                };
+            };
+        };
+    };
+    getStats: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Runtime statistics */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["StatsResponse"];
+                };
+            };
+        };
+    };
+    getCacheStats: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Cache status */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CacheStats"];
+                };
+            };
+        };
+    };
+    getProxyStats: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Proxy stats */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProxyStats"];
+                };
+            };
+        };
+    };
+    getCircuitBreakerStats: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Circuit breaker stats */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CircuitBreakerStatsResponse"];
+                };
+            };
+        };
+    };
+    getOpenAPISpec: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OpenAPI YAML */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/yaml": string;
+                };
+            };
+        };
+    };
+    getSwaggerUI: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description HTML page loading Swagger UI from CDN */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/html": string;
+                };
+            };
+        };
+    };
+}
+
+export type { $defs, components, operations, paths, webhooks };