openapi: 3.1.0
info:
  title: Bright Data Web Unlocker API
  description: |
    Web Unlocker is a single-endpoint unblocking service. Submit any target URL and Bright Data
    handles residential proxy selection, JavaScript rendering, CAPTCHA solving, fingerprint
    management, and anti-bot evasion, returning the fully rendered response. Supports both
    synchronous (one-shot) and asynchronous (submit + poll) modes.

    Authentication uses a Bearer API token. Successful requests only — failed unlocks are not billed.
  version: '1.0'
  contact:
    name: Bright Data
    url: https://docs.brightdata.com
servers:
  - url: https://api.brightdata.com
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Unlock
    description: Submit and retrieve unlock requests.
paths:
  /request:
    post:
      summary: Unlock a URL (Synchronous)
      description: |
        Submit a URL for synchronous unblocking. Bright Data returns the rendered response (HTML,
        JSON, or raw bytes) once the page is unlocked. Use the asynchronous endpoints for long-running
        targets or batch flows.
      operationId: unlockSync
      tags: [Unlock]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url, zone]
              properties:
                url: { type: string, format: uri }
                zone: { type: string, description: Web Unlocker zone name. }
                country: { type: string, description: ISO 3166-1 alpha-2 country code. }
                format: { type: string, enum: [raw, json] }
                method: { type: string, enum: [GET, POST] }
                data: { type: string }
      responses:
        "200":
          description: Unlocked response.
          content:
            application/json: { schema: { type: object, additionalProperties: true } }
            text/html: { schema: { type: string } }
  /unblocker/req:
    post:
      summary: Submit Asynchronous Unlock Request
      operationId: unlockAsync
      tags: [Unlock]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url, zone]
              properties:
                url: { type: string, format: uri }
                zone: { type: string }
                country: { type: string }
                response_id: { type: string, description: Optional caller-provided correlation id. }
                callback_url: { type: string, format: uri, description: Webhook for completion. }
                format: { type: string, enum: [raw, json] }
      responses:
        "200":
          description: Submitted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response_id: { type: string }
  /unblocker/get_result:
    get:
      summary: Get Asynchronous Unlock Result
      operationId: getUnlockResult
      tags: [Unlock]
      parameters:
        - { name: response_id, in: query, required: true, schema: { type: string } }
      responses:
        "200":
          description: Result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, enum: [pending, ready, failed] }
                  result: { type: object, additionalProperties: true }
                  status_code: { type: integer }
        "202":
          description: Not yet ready.
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer