{ "components": { "callbacks": {}, "examples": {}, "headers": {}, "links": {}, "parameters": {}, "pathItems": {}, "requestBodies": {}, "responses": {}, "schemas": {}, "securitySchemes": { "bearerAuth": { "scheme": "bearer", "type": "http" } } }, "info": { "description": "", "title": "Oxylabs Web API", "version": "1", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "header": "X-AISA-Cost-Mode", "value": "quote" } }, "x-aisa-catalogs": { "oxylabs": { "description": "", "title": "Oxylabs Web API", "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "quote": { "header": "X-AISA-Cost-Mode", "value": "quote" } }, "x-aisa-document": { "facts_hash": "330a1b946e291c58fa7755e63e8cb2a4ec60e05fb4b373af15c0723c4dc1d294", "generator_version": "3", "protocol_version": "1", "schema_version": "1" }, "x-aisa-plans": { "builder": 1.0, "display_plan": "payg", "payg": 1.0, "similarweb_payg": 1.0, "team": 1.0, "version": "e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb" } } }, "x-aisa-configured-paths": [ "/apis/v1/oxylabs/ai-search", "/apis/v1/oxylabs/scrape", "/apis/v1/oxylabs/search" ], "x-aisa-document": { "composer_version": "26", "document_hash": "sha256:eba3ef86733db91138e8b31aab5f21802c02ad058101de9d3dfe79120b82eb64", "facts_hash": "330a1b946e291c58fa7755e63e8cb2a4ec60e05fb4b373af15c0723c4dc1d294", "generator_version": "3", "protocol_version": "1", "response_pending": [], "schema_version": "1" }, "x-aisa-plans": { "builder": 1.0, "display_plan": "payg", "payg": 1.0, "similarweb_payg": 1.0, "team": 1.0, "version": "e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb" }, "x-aisa-provider": "oxylabs" }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "openapi": "3.1.0", "paths": { "/apis/v1/oxylabs/ai-search": { "post": { "description": "透传 AI 搜索 source: chatgpt/gemini/perplexity/google_search/google_ai_mode;返回 答案+引用+来源URL。Caller 传完整 body(含 source),原样转发 POST /v1/queries。\n\n\n公开参考价格：每次成功请求 $0.00145 USD。 最终费用以账户适用价格及实际结算为准。\n", "operationId": "post_oxylabs_ai_search", "requestBody": { "content": { "application/json": { "examples": { "google_ai_mode": { "summary": "Google AI Mode (google_ai_mode)", "value": { "geo_location": "United States", "parse": true, "query": "best noise cancelling headphones 2026", "render": "html", "source": "google_ai_mode" } }, "google_search": { "summary": "Google AI Overviews (google_search)", "value": { "geo_location": "United States", "parse": true, "query": "best noise cancelling headphones 2026", "render": "html", "source": "google_search" } } }, "schema": { "additionalProperties": true, "description": "Passthrough body for the Google answer engines. `source` selects the engine; `query`, `render`, `parse`, and `geo_location` are the parameters Google sources expect. Additional upstream parameters are passed through as-is.", "properties": { "geo_location": { "description": "Country-level geo-location for the query, e.g. \"United States\".", "example": "United States", "type": "string" }, "parse": { "description": "Return structured, parsed results instead of raw output. Recommended for every source.", "example": true, "type": "boolean" }, "query": { "description": "The search query. Required for `google_search` and `google_ai_mode`.", "example": "best noise cancelling headphones 2026", "type": "string" }, "render": { "description": "For `google_search` and `google_ai_mode`, set to \"html\" to render the page before parsing.", "enum": [ "html" ], "example": "html", "type": "string" }, "source": { "description": "The Google AI answer engine to query. `google_search` returns Google AI Overviews; `google_ai_mode` returns Google AI Mode. For ChatGPT/Gemini/Perplexity use the async endpoint `post_oxylabs_llm` instead.", "enum": [ "google_search", "google_ai_mode" ], "example": "google_search", "type": "string" } }, "required": [ "source" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "results": { "description": "One entry per query. A Realtime single query returns exactly one result, which is the billed unit.", "items": { "properties": { "content": { "description": "Parsed answer payload. The structure varies by the Google source:\n- `google_search` → `content.results.ai_overviews[]` with `answer_text` and `references[]{source, url}` (shown below).\n- `google_ai_mode` → `content.citations[]{text, urls[]}`.", "properties": { "results": { "description": "Google-type parsed results container.", "properties": { "ai_overviews": { "description": "Google AI Overviews returned for the query.", "items": { "properties": { "answer_text": { "description": "The AI-generated answer, split into fragments that may carry inline references.", "items": { "properties": { "fragments": { "items": { "properties": { "references": { "items": {}, "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" }, "references": { "description": "Cited sources for this overview.", "items": { "properties": { "source": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Query completed successfully. `results[]` holds one result per query. The parsed shape inside `content` varies by source (see property descriptions); the example below shows the `google_search` (Google AI Overviews) shape." }, "default": { "content": { "application/json": { "schema": {} } }, "description": "Error response; upstream passthrough responses may use provider formats" } }, "summary": "Oxylabs AI-search (Realtime, passthrough)", "tags": [ "oxylabs" ], "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "mpp": false, "mpp_methods": [], "quote": { "header": "X-AISA-Cost-Mode", "value": "quote" }, "x402": false }, "x-aisa-catalog-id": "oxylabs", "x-aisa-category": "ai-search", "x-aisa-docs-url": "https://aisa.one/docs/api-reference/oxylabs/post_oxylabs_ai_search", "x-aisa-passthrough": true, "x-aisa-pricing": { "cost_contract": "fixed_success", "customer_multiplier": 1.45, "customer_pricing": "provider_cost_multiplier", "default_request_estimate_usd": 0.00145, "estimate_source": "profile_seed", "evidence_source": "request_snapshot" }, "x-aisa-query-policy": { "ignore_undeclared": false, "request_wins": true }, "x-aisa-response-source": { "content_hash": "sha256:98bed2cec70fa12e0a172f9db2931db46a0269935c1ad31de526797d298f2539", "kind": "upstream_success_contract", "source": { "content_hash": "sha256:ae1695c337dc3e2d1617a70a5f88c32efb874b238f009510eb359c5215bbbec4", "converter": "scripts/import_existing_contracts.py@1", "fetched_at": "2026-09-29T21:25:55+08:00", "kind": "manual", "owner": "AIsa-team/docs", "path_space": "public", "policy_revision": "sha256:d98e7453f752be0954aa84294ebc05362a84c197150941f0df6b639b835b0e9a", "refresh_policy": "manual", "review_period_days": 30, "url": "https://github.com/AIsa-team/docs/blob/7783840e4710bb00886143feab84606f8aaea67c/openapi/oxylabs.json" } }, "x-aisa-revision": { "customer_pricing_ref": "cb865f6ebfa6", "plan_policy_version": "e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb", "profile_ref": "d66a14345ef8" }, "x-aisa-runtime-operation": { "method": "ANY", "operation_id": "post_oxylabs_ai_search", "path": "/apis/v1/oxylabs/ai-search" }, "x-aisa-source": { "content_hash": "sha256:ae1695c337dc3e2d1617a70a5f88c32efb874b238f009510eb359c5215bbbec4", "converter": "scripts/import_existing_contracts.py@1", "fetched_at": "2026-09-29T21:25:55+08:00", "kind": "manual", "owner": "AIsa-team/docs", "path_space": "public", "policy_revision": "sha256:d98e7453f752be0954aa84294ebc05362a84c197150941f0df6b639b835b0e9a", "refresh_policy": "manual", "review_period_days": 30, "url": "https://github.com/AIsa-team/docs/blob/7783840e4710bb00886143feab84606f8aaea67c/openapi/oxylabs.json" }, "x-aisa-status": "disabled", "x-aisa-upstream-path": "/v1/queries", "x-aisa-validation": "provider", "x-codeSamples": [ { "label": "Reference example", "lang": "text", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/oxylabs/ai-search \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"source\": \"google_search\"\n}'" } ] } }, "/apis/v1/oxylabs/scrape": { "post": { "description": "\n公开参考价格：每次成功请求 $0.00145 USD。 最终费用以账户适用价格及实际结算为准。\n", "operationId": "post_oxylabs_apis_v1_oxylabs_scrape", "requestBody": { "content": { "application/json": { "examples": { "default": { "value": { "output": [ "html" ], "run_js": false, "url": "https://example.com" } }, "minimal": { "value": { "url": "https://example.com" } } }, "schema": { "additionalProperties": false, "properties": { "device": { "enum": [ "desktop", "mobile" ], "type": "string" }, "location": { "maxLength": 2, "minLength": 2, "type": "string" }, "output": { "default": [ "html" ], "items": { "enum": [ "html", "markdown" ], "type": "string" }, "maxItems": 2, "minItems": 1, "type": "array" }, "run_js": { "default": false, "enum": [ false ], "type": "boolean" }, "url": { "format": "https_url", "maxLength": 8192, "type": "string" } }, "required": [ "url" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "required": [ "state" ] }, { "required": [ "status" ] } ], "properties": { "metadata": { "properties": { "request_id": { "description": "供应商请求标识符。", "type": "string" }, "timestamp": { "description": "Unix 时间戳，单位为秒。", "type": "integer" } }, "type": "object" }, "params": { "description": "执行参数，包含供应商的默认值；响应中回显的字段不代表 AISA 请求支持额外参数。", "type": "object" }, "results": { "allOf": [ { "prefixItems": [ { "anyOf": [ { "properties": { "html": { "type": "string" } }, "required": [ "html" ] }, { "properties": { "markdown": { "type": "string" } }, "required": [ "markdown" ] } ] } ] } ], "items": { "properties": { "html": { "description": "请求的 HTML 内容；未请求该格式时为 null。", "type": [ "string", "null" ] }, "json": { "description": "当前 AISA 接口不请求此格式，通常为 null。", "type": [ "object", "null" ] }, "markdown": { "description": "请求的 Markdown 内容；未请求该格式时为 null。", "type": [ "string", "null" ] }, "metadata": { "properties": { "page": { "type": "integer" }, "run_js": { "type": "boolean" }, "url": { "description": "重定向后实际抓取的 URL。", "type": "string" } }, "type": "object" }, "screenshot": { "description": "当前 AISA 接口不请求此格式，通常为 null。", "type": [ "string", "null" ] } }, "type": "object" }, "minItems": 1, "type": "array" }, "state": { "const": "done", "description": "实际观测到的同步成功标记；当前 Web API 响应可能省略 status 字段。", "type": "string" }, "status": { "const": 200, "description": "官方响应示例中的成功标记；state 为 done 时可能省略此字段。", "type": "integer" } }, "required": [ "results" ], "type": "object" } } }, "description": "Web API 原生网页抓取成功响应。" }, "default": { "content": { "application/json": { "schema": {} } }, "description": "Error response; upstream passthrough responses may use provider formats" } }, "summary": "Oxylabs Web API 网页抓取", "tags": [ "oxylabs" ], "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "mpp": false, "mpp_methods": [], "quote": { "header": "X-AISA-Cost-Mode", "value": "quote" }, "x402": false }, "x-aisa-catalog-id": "oxylabs", "x-aisa-category": "scrape", "x-aisa-docs-url": "https://aisa.one/docs/api-reference/oxylabs/post_oxylabs_apis_v1_oxylabs_scrape", "x-aisa-pricing": { "cost_contract": "request_formula", "customer_pricing": "fixed_success", "default_request_estimate_usd": 0.00145, "estimate_source": "profile_seed", "evidence_source": "request_snapshot" }, "x-aisa-query-policy": { "ignore_undeclared": false, "request_wins": false }, "x-aisa-response-passthrough": true, "x-aisa-response-source": { "content_hash": "sha256:c8a1ec860117bfeb2a92bc01d6e68648e8a24ea18f86cbb43235211564c3c053", "kind": "upstream_success_contract", "source": { "content_hash": "sha256:f38a334513d184144abdc947d1cb58f540613206dbb44bdffb81d4f79e2c85d1", "converter": "reviewed-oxylabs-web-response@1", "fetched_at": "2026-11-02T16:37:40.287037+00:00", "kind": "manual", "owner": "AIsa-team/docs", "path_space": "public", "policy_revision": "sha256:6c1eb0c57dc9a6615fe33835e6a695ad99e1a2b4eba269e947d070e4129acf83", "refresh_policy": "manual", "response_only": true, "review_evidence": "Official Web API output dictionary and response example. Scrape additionally accepts the state:done envelope observed in authenticated native runtime smoke; no Classic schema or request/pricing authority is reused.", "review_period_days": 30, "source_pages": [ { "raw_content_hash": "sha256:d7277b71e499a5f15478c01037beb24a6085462a56b5abd8e88733e02c1f62c6", "url": "https://developers.oxylabs.io/products/web-api/scrape" } ], "upstream_origin_sha256": "f1f392fb4bb48552e1f54f161e1d716169387496d2a59837c542c9c2414747f9", "upstream_path_sha256": "7884a9d80e867f60ed352625b21f33e29f7036352f1ce1921d8adf23fe2ddae8", "url": "https://developers.oxylabs.io/products/web-api/scrape" } }, "x-aisa-response-upstream-origin-sha256": "f1f392fb4bb48552e1f54f161e1d716169387496d2a59837c542c9c2414747f9", "x-aisa-response-upstream-path-sha256": "7884a9d80e867f60ed352625b21f33e29f7036352f1ce1921d8adf23fe2ddae8", "x-aisa-revision": { "customer_pricing_ref": "a267a431fadb", "plan_policy_version": "e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb", "profile_ref": "0a74ac2e592c" }, "x-aisa-runtime-operation": { "method": "POST", "operation_id": "post_oxylabs_apis_v1_oxylabs_scrape", "path": "/apis/v1/oxylabs/scrape" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-codeSamples": [ { "label": "Reference example", "lang": "text", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/oxylabs/scrape \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"output\": [\n \"html\"\n ],\n \"run_js\": false,\n \"url\": \"https://example.com\"\n}'" } ] } }, "/apis/v1/oxylabs/search": { "post": { "description": "\n公开参考价格：每次成功请求 $0.00145 USD。 最终费用以账户适用价格及实际结算为准。\n", "operationId": "post_oxylabs_apis_v1_oxylabs_search", "requestBody": { "content": { "application/json": { "examples": { "default": { "value": { "max_results": 10, "query": "nike" } }, "minimal": { "value": { "query": "nike" } } }, "schema": { "additionalProperties": false, "properties": { "location": { "maxLength": 2, "minLength": 2, "type": "string" }, "max_results": { "default": 10, "maximum": 20, "minimum": 1, "type": "integer" }, "query": { "maxLength": 2048, "minLength": 1, "type": "string" } }, "required": [ "query" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "metadata": { "properties": { "request_id": { "description": "供应商请求标识符。", "type": "string" }, "timestamp": { "description": "Unix 时间戳，单位为秒。", "type": "integer" } }, "type": "object" }, "params": { "properties": { "location": { "type": "string" }, "max_results": { "type": "integer" }, "query": { "type": "string" } }, "type": "object" }, "related_questions": { "items": { "properties": { "question": { "type": "string" }, "snippet": { "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "type": "array" }, "related_searches": { "items": { "properties": { "query": { "type": "string" } }, "type": "object" }, "type": "array" }, "results": { "items": { "properties": { "metadata": { "properties": { "position": { "minimum": 1, "type": "integer" } }, "type": "object" }, "outline": { "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" }, "url": { "description": "搜索结果的绝对 URL。", "type": "string" } }, "type": "object" }, "type": "array" }, "state": { "const": "done", "type": "string" }, "status": { "const": 200, "description": "可选的成功标记；若存在，必须与 HTTP 成功状态及 state 字段一致。", "type": "integer" } }, "required": [ "state", "results" ], "type": "object" } } }, "description": "Web API 原生搜索成功响应。" }, "default": { "content": { "application/json": { "schema": {} } }, "description": "Error response; upstream passthrough responses may use provider formats" } }, "summary": "Oxylabs Web API 搜索", "tags": [ "oxylabs" ], "x-aisa-capabilities": { "idempotency": "Idempotency-Key", "max_price": "X-AISA-Max-Price-USD", "mpp": false, "mpp_methods": [], "quote": { "header": "X-AISA-Cost-Mode", "value": "quote" }, "x402": false }, "x-aisa-catalog-id": "oxylabs", "x-aisa-category": "search", "x-aisa-docs-url": "https://aisa.one/docs/api-reference/oxylabs/post_oxylabs_apis_v1_oxylabs_search", "x-aisa-pricing": { "cost_contract": "request_formula", "customer_pricing": "fixed_success", "default_request_estimate_usd": 0.00145, "estimate_source": "profile_seed", "evidence_source": "request_snapshot" }, "x-aisa-query-policy": { "ignore_undeclared": false, "request_wins": false }, "x-aisa-response-passthrough": true, "x-aisa-response-source": { "content_hash": "sha256:e157536e0833bc351dfa22e6c9e9653c945b9f5a0a5b4ec8cbfe1681364379af", "kind": "upstream_success_contract", "source": { "content_hash": "sha256:fd8ca6efca5942d8097385a25e1f63d625e14ae862a0797980fce6548de615ef", "converter": "reviewed-oxylabs-web-response@1", "fetched_at": "2026-11-02T16:37:40.287037+00:00", "kind": "manual", "owner": "AIsa-team/docs", "path_space": "public", "policy_revision": "sha256:eddd97f201ad0aafee57a813b266312dfd6334f35a31bc903c5180282f790ad2", "refresh_policy": "manual", "response_only": true, "review_evidence": "Official Web API output dictionary and response example. Scrape additionally accepts the state:done envelope observed in authenticated native runtime smoke; no Classic schema or request/pricing authority is reused.", "review_period_days": 30, "source_pages": [ { "raw_content_hash": "sha256:cb1eee328327c05d434b0425d884dfd8a4af33349057b4cf6e853f126d057e51", "url": "https://developers.oxylabs.io/products/web-api/search" } ], "upstream_origin_sha256": "f1f392fb4bb48552e1f54f161e1d716169387496d2a59837c542c9c2414747f9", "upstream_path_sha256": "07fdf377db11ab7691b360afc8ee5e6542c27b6e2bd904c7049d460f79b5a517", "url": "https://developers.oxylabs.io/products/web-api/search" } }, "x-aisa-response-upstream-origin-sha256": "f1f392fb4bb48552e1f54f161e1d716169387496d2a59837c542c9c2414747f9", "x-aisa-response-upstream-path-sha256": "07fdf377db11ab7691b360afc8ee5e6542c27b6e2bd904c7049d460f79b5a517", "x-aisa-revision": { "customer_pricing_ref": "3a475683a008", "plan_policy_version": "e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb", "profile_ref": "584af7e615d1" }, "x-aisa-runtime-operation": { "method": "POST", "operation_id": "post_oxylabs_apis_v1_oxylabs_search", "path": "/apis/v1/oxylabs/search" }, "x-aisa-status": "enabled", "x-aisa-validation": "runtime", "x-codeSamples": [ { "label": "Reference example", "lang": "text", "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n --url https://api.aisa.one/apis/v1/oxylabs/search \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"max_results\": 10,\n \"query\": \"nike\"\n}'" } ] } } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://api.aisa.one" } ] }