{ "openapi": "3.0.1", "info": { "title": "Brightdata API", "description": "Integrate Bright Data APIs to your pipeline and secure high-end scraping precision", "version": "1.0.0" }, "servers": [ { "url": "https://api.brightdata.com" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/request": { "get": { "description": "", "parameters": [ { "in": "query", "name": "zone", "description": "Zone identifier that defines your Bright Data product configuration. Find your zones at: https://brightdata.com/cp/zones", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "url", "description": "Complete target URL to scrape. Must include protocol (http/https). Example: `https://geo.brdtest.com/mygeo.json`", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "format", "description": "Format for requesting a raw HTML via proxy is `raw`.\n\nFormat for request a JSON response is `json`.", "required": true, "schema": { "type": "string", "enum": [ "raw", "json" ] } }, { "in": "query", "name": "method", "description": "Method for requesting an HTML via proxy is `GET`.", "required": false, "schema": { "type": "string", "default": "GET" } }, { "in": "query", "name": "country", "description": "Country code of proxy which request is relayed through.", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "data_format", "description": "Additional response format: `markdown` converts HTML to markdown, `screenshot` returns PNG image of the page", "required": false, "schema": { "type": "string", "enum": [ "markdown", "screenshot" ] } }, { "in": "query", "name": "render", "description": "Set to `true` to force JavaScript rendering using a browser. Because this flag forces browser use, it can significantly increase response time, so use it only when a page requires JavaScript to load its content.", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Missing zone parameter" } } }, "post": { "description": "", "parameters": [ { "in": "query", "name": "async", "description": "Set this to `true` for asynchronous", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostBody" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessfulUnlockerResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTP401" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTP400" } } } } }, "x-codeSamples": [ { "lang": "shell", "label": "cURL", "source": "curl --request POST \\\n --url https://api.brightdata.com/request \\\n --header \"Authorization: Bearer YOUR_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"zone\": \"web_unlocker1\",\n \"url\": \"https://geo.brdtest.com/welcome.txt\",\n \"format\": \"raw\"\n }' " }, { "lang": "python", "label": "Python", "source": "import requests\n\nurl = \"https://api.brightdata.com/request\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_API_KEY\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"zone\": \"web_unlocker1\",\n \"url\": \"https://geo.brdtest.com/welcome.txt\",\n \"format\": \"raw\",\n}\n\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.text)" }, { "lang": "py", "label": "Python SDK", "source": "# Install: pip install brightdata-sdk\nfrom brightdata import BrightDataClient\n\nasync with BrightDataClient(api_key=\"YOUR_API_KEY\") as client:\n # Returns HTML by default\n result = await client.scrape_url(\"https://geo.brdtest.com/welcome.txt\")\n\n # Or transform to markdown and route through a US proxy\n md = await client.scrape_url(\n \"https://geo.brdtest.com/welcome.txt\",\n data_format=\"markdown\",\n country=\"us\",\n )\n\n print(result.data)" }, { "lang": "javascript", "label": "JavaScript", "source": "const response = await fetch(\"https://api.brightdata.com/request\", {\n method: \"POST\",\n headers: {\n \"Authorization\": \"Bearer YOUR_API_KEY\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n zone: \"web_unlocker1\",\n url: \"https://geo.brdtest.com/welcome.txt\",\n format: \"raw\",\n }),\n});\n\nconst data = await response.text();\nconsole.log(data);" }, { "lang": "js", "label": "JavaScript SDK", "source": "// Install: npm install @brightdata/sdk\nimport { bdclient } from '@brightdata/sdk';\n\nconst client = new bdclient({ apiKey: 'YOUR_API_KEY' });\n\n// Returns HTML by default\nconst html = await client.scrapeUrl('https://geo.brdtest.com/welcome.txt');\n\n// Or transform to markdown and route through a US proxy\nconst md = await client.scrapeUrl('https://geo.brdtest.com/welcome.txt', {\n dataFormat: 'markdown',\n country: 'us',\n});\n\nawait client.close();" }, { "lang": "php", "label": "PHP", "source": " \"web_unlocker1\",\n \"url\" => \"https://geo.brdtest.com/welcome.txt\",\n \"format\" => \"raw\",\n]));\n\n$response = curl_exec($ch);\ncurl_close($ch);\necho $response;" }, { "lang": "go", "label": "Go", "source": "package main\n\nimport (\n\t\"bytes\"\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n)\n\nfunc main() {\n\tpayload := []byte(`{\"zone\":\"web_unlocker1\",\"url\":\"https://geo.brdtest.com/welcome.txt\",\"format\":\"raw\"}`)\n\n\treq, _ := http.NewRequest(\"POST\", \"https://api.brightdata.com/request\", bytes.NewBuffer(payload))\n\treq.Header.Set(\"Authorization\", \"Bearer YOUR_API_KEY\")\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\n\tbody, _ := io.ReadAll(res.Body)\n\tfmt.Println(string(body))\n}" }, { "lang": "java", "label": "Java", "source": "import java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\n\npublic class UnlockerRequest {\n public static void main(String[] args) throws Exception {\n String body = \"{\\\"zone\\\":\\\"web_unlocker1\\\",\\\"url\\\":\\\"https://geo.brdtest.com/welcome.txt\\\",\\\"format\\\":\\\"raw\\\"}\";\n\n HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.brightdata.com/request\"))\n .header(\"Authorization\", \"Bearer YOUR_API_KEY\")\n .header(\"Content-Type\", \"application/json\")\n .POST(HttpRequest.BodyPublishers.ofString(body))\n .build();\n\n HttpResponse response = HttpClient.newHttpClient()\n .send(request, HttpResponse.BodyHandlers.ofString());\n\n System.out.println(response.body());\n }\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require 'net/http'\nrequire 'json'\nrequire 'uri'\n\nuri = URI.parse(\"https://api.brightdata.com/request\")\nrequest = Net::HTTP::Post.new(uri)\nrequest[\"Authorization\"] = \"Bearer YOUR_API_KEY\"\nrequest[\"Content-Type\"] = \"application/json\"\nrequest.body = {\n zone: \"web_unlocker1\",\n url: \"https://geo.brdtest.com/welcome.txt\",\n format: \"raw\"\n}.to_json\n\nresponse = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|\n http.request(request)\nend\n\nputs response.body" } ] } }, "/response": { "get": { "description": "", "parameters": [ { "in": "query", "name": "response_id", "description": "Response ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTP200" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTP401" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTP400" } } } } } } } }, "components": { "schemas": { "PostBody": { "required": [ "zone", "url", "format" ], "type": "object", "properties": { "zone": { "description": "Zone identifier that defines your Bright Data product configuration. Each zone contains targeting rules, output preferences, and access permissions. \n Manage zones at: https://brightdata.com/cp/zones", "type": "string", "example": "web_unlocker1" }, "url": { "description": "Complete target URL to scrape. Must include protocol (http/https), be publicly accessible.", "type": "string", "example": "https://geo.brdtest.com/welcome.txt" }, "format": { "description": "Response format: `raw` returns HTML content as string, `json` returns structured data.", "type": "string", "enum": [ "raw", "json" ], "example": "json" }, "method": { "description": "Method for requesting an HTML via proxy is `GET`.", "type": "string", "default": "GET", "example": "GET" }, "country": { "description": "Two-letter ISO 3166-1 country code for proxy location (e.g., `us`, `gb`, `de`, `ca`, `au`). If not specified, system auto-selects optimal location based on your zone configuration. \n List of country codes: https://docs.brightdata.com/general/faqs#where-can-i-see-the-list-of-country-codes", "type": "string", "example": "us" }, "data_format": { "description": "Additional response format transformation: `markdown` converts HTML content to clean markdown format, `screenshot` captures a PNG image of the rendered page.", "type": "string", "enum": [ "markdown", "screenshot" ], "example": "markdown" }, "render": { "description": "Set to `true` to force JavaScript rendering using a browser. Because this flag forces browser use, it can significantly increase response time, so use it only when a page requires JavaScript to load its content.", "type": "string", "enum": [ "true", "false" ], "example": "true" }, "debug": { "description": "Set to `true` to return the `x-brd-debug` response header, which reports the request ID, traffic counters, billing status, destination IP and peer details for this request. See [Debugging Web Unlocker API](https://docs.brightdata.com/scraping-automation/web-unlocker/features#debugging-web-unlocker-api).", "type": "boolean", "default": false, "example": true } } }, "HTTP200": { "type": "object", "example": { "status": "OK" } }, "HTTP401": { "type": "object", "example": { "error": "User authentication is required" } }, "HTTP400": { "type": "object", "example": { "error": "Bad Request" } }, "SuccessfulUnlockerResponse": { "type": "object", "example": { "status_code": 200, "headers": { "access-control-allow-origin": "*", "cache-control": "no-store", "content-type": "text/plain; charset=utf-8", "date": "Sun, 18 May 2025 20:01:18 GMT", "server": "nginx", "connection": "close", "transfer-encoding": "chunked" }, "body": "\nWelcome to Bright Data! Here are your proxy details\nCountry: US\nLatitude: 37.751\nLongitude: -97.822\nTimezone: America/Chicago\nASN number: 20473\nASN Organization name: AS-VULTR\nIP version: IPv4\n\nCommon usage examples:\n\n[USERNAME]-country-us:[PASSWORD] // US based Proxy\n[USERNAME]-country-us-state-ny:[PASSWORD] // US proxy from NY\n[USERNAME]-asn-56386:[PASSWORD] // proxy from ASN 56386\n[USERNAME]-ip-1.1.1.1.1:[PASSWORD] // proxy from dedicated pool\n\nTo get a simple JSON response, use https://geo.brdtest.com/mygeo.json .\n\nMore examples on https://docs.brightdata.com/api-reference/introduction\n\n" } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Use your Bright Data API Key as a Bearer token in the Authorization header.\n\n**How to authenticate:**\n1. Obtain your API Key from the Bright Data account settings at https://brightdata.com/cp/setting/users\n2. Include the API Key in the Authorization header of your requests\n3. Format: `Authorization: Bearer YOUR_API_KEY`\n\n**Example:**\n```\nAuthorization: Bearer b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd6a7ec8f3f251f07df\n```\n\nLearn how to get your Bright Data API key: https://docs.brightdata.com/api-reference/authentication", "bearerFormat": "API Key" } } } }