{
  "openapi": "3.1.0",
  "info": {
    "title": "200ok - x402 Web Unlocker API",
    "description": "Simulate user behavior, automatically handle CAPTCHAs and residential proxy, and achieve unblocked large-scale data crawling with x402 micropayments. Pay $0.01 per successful request in USDC on Base network.",
    "version": "1.0.0",
    "contact": {
      "name": "200ok Support",
      "url": "https://200ok.xyz"
    },
    "x-guidance": "x402-payable Web Unlocker API for AI agents. Access protected web content with automatic payment via x402 protocol. POST /unlock with JSON body: { url (required), type?, js_render?, wait?, wait_for?, country?, block_resources?, clean_content?, headers?, cookies? }. Response: { success, html?, screenshot?, url, timestamp }. Price: $0.01 USDC on Base network (eip155:8453). Only charged on HTTP 200. Payment via PAYMENT-SIGNATURE header. See https://docs.x402.org for payment setup."
  },
  "x-discovery": {
    "ownershipProofs": []
  },
  "servers": [
    {
      "url": "https://web-unlocker.200ok.xyz",
      "description": "Web Unlocker API"
    }
  ],
  "paths": {
    "/unlock": {
      "post": {
        "summary": "Unlock a protected website",
        "description": "Bypass web protections (CAPTCHA, Cloudflare, anti-bot) and retrieve clean HTML content or screenshots from any website. The API handles JavaScript rendering, proxy rotation, and browser fingerprint simulation automatically.\n\n## How It Works\n\n1. Send a POST request with the target URL\n2. Receive a 402 Payment Required response with x402 payment details\n3. Include the x402 payment header with your request\n4. Get the unlocked content in your specified format\n\n## Pricing\n\n- **Cost**: $0.01 USDC per successful request\n- **Billing**: Only charged when the API returns HTTP 200 status code\n- **Network**: Base (EIP-155:8453)\n- **Asset**: USDC",
        "operationId": "unlockWebsite",
        "security": [{"x402": []}],
        "x-paid": true,
        "x-auth-mode": "apiKey",
        "x-payment-info": {
          "protocols": ["x402"],
          "pricingMode": "fixed",
          "price": "0.01",
          "currency": "USDC",
          "network": "eip155:8453",
          "x402Version": 2
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "title": "Target URL",
                    "description": "The URL of the website to unlock. Must be a valid HTTP/HTTPS URL. The API will navigate to this URL and retrieve the content after bypassing any protections.",
                    "example": "https://example.com",
                    "minLength": 1,
                    "maxLength": 2048
                  },
                  "type": {
                    "type": "string",
                    "title": "Output Format",
                    "description": "Specifies the format of the returned content. Use 'html' for raw HTML content, 'png' for a full-page screenshot, or 'both' to receive both HTML and screenshot in the response.",
                    "enum": ["html", "png", "both"],
                    "default": "html",
                    "example": "html"
                  },
                  "js_render": {
                    "type": "boolean",
                    "title": "JavaScript Rendering",
                    "description": "Enable JavaScript rendering to handle dynamically loaded content and Single-Page Applications (SPAs). When enabled, the API uses a headless browser to fully render the page including all JavaScript-executed DOM modifications. Recommended for modern websites that load content asynchronously.",
                    "default": true,
                    "example": true
                  },
                  "wait": {
                    "type": "integer",
                    "title": "Wait Time (milliseconds)",
                    "description": "Additional time to wait after the page loads before capturing the content. Useful for pages with delayed content loading or animations. The wait time is specified in milliseconds. Maximum value: 100000 (100 seconds). This wait occurs after the initial page load but before any wait_for selector check.",
                    "default": 0,
                    "example": 5000,
                    "minimum": 0,
                    "maximum": 100000
                  },
                  "wait_for": {
                    "type": "string",
                    "title": "Wait for CSS Selector",
                    "description": "A CSS selector to wait for before considering the page loaded. The API will wait up to 30 seconds for this element to appear in the DOM. If both 'wait' and 'wait_for' are specified, 'wait_for' takes precedence (the fixed 'wait' time is ignored). Useful for ensuring specific content has loaded.",
                    "example": ".content",
                    "minLength": 1,
                    "maxLength": 256
                  },
                  "block_resources": {
                    "type": "string",
                    "title": "Block Resources",
                    "description": "Comma-separated list of resource types to block during page load. Blocking unnecessary resources can significantly improve response time and reduce bandwidth. Common values: 'image', 'script', 'stylesheet', 'font', 'media'. Use this to optimize for speed when you only need specific content types.",
                    "example": "image,stylesheet",
                    "default": ""
                  },
                  "country": {
                    "type": "string",
                    "title": "Proxy Country",
                    "description": "Two-letter ISO country code to specify the geographic location of the proxy server. Use this to access geo-restricted content or test how websites appear in different regions. When not specified, the API uses the optimal proxy location for speed. Examples: 'us' (United States), 'de' (Germany), 'jp' (Japan).",
                    "example": "us",
                    "default": "",
                    "pattern": "^[a-z]{2}$"
                  },
                  "clean_content": {
                    "type": "string",
                    "title": "Clean Content",
                    "description": "Comma-separated list of content types to remove from the response. Use 'js' to remove JavaScript code, 'css' to remove stylesheets, or 'js,css' to remove both. This reduces response size and is useful when you only need the raw HTML structure without executable code.",
                    "example": "js,css",
                    "default": ""
                  },
                  "headers": {
                    "type": "array",
                    "title": "Custom Request Headers",
                    "description": "Custom HTTP headers to send with the request. Each header is an object with 'name' and 'value' properties. Use this to set custom User-Agent strings, authentication tokens, or other request metadata. Multiple headers should be included as separate objects in the array.",
                    "example": [
                      {"name": "User-Agent", "value": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"},
                      {"name": "Accept-Language", "value": "en-US,en;q=0.9"}
                    ],
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {"type": "string", "description": "Header name"},
                        "value": {"type": "string", "description": "Header value"}
                      },
                      "required": ["name", "value"]
                    }
                  },
                  "cookies": {
                    "type": "array",
                    "title": "Custom Cookies",
                    "description": "Cookies to send with the request. Each cookie is an object with 'name' and 'value' properties. Use this to maintain session state, bypass login walls, or access authenticated content. Multiple cookies are sent as separate cookie headers automatically.",
                    "example": [
                      {"name": "session_id", "value": "abc123xyz"},
                      {"name": "user_pref", "value": "dark_mode"}
                    ],
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {"type": "string", "description": "Cookie name"},
                        "value": {"type": "string", "description": "Cookie value"}
                      },
                      "required": ["name", "value"]
                    }
                  }
                }
              },
              "examples": {
                "basic": {
                  "summary": "Basic Request",
                  "description": "Simple request with just the URL",
                  "value": {
                    "url": "https://example.com"
                  }
                },
                "full_render": {
                  "summary": "Full JavaScript Rendering",
                  "description": "Request with JavaScript rendering and wait time for dynamic content",
                  "value": {
                    "url": "https://example.com",
                    "js_render": true,
                    "wait": 5000,
                    "type": "html"
                  }
                },
                "screenshot": {
                  "summary": "Screenshot Capture",
                  "description": "Capture a full-page screenshot with specific proxy location",
                  "value": {
                    "url": "https://example.com",
                    "type": "png",
                    "js_render": true,
                    "country": "us"
                  }
                },
                "advanced": {
                  "summary": "Advanced Configuration",
                  "description": "Full-featured request with all parameters",
                  "value": {
                    "url": "https://example.com",
                    "type": "html",
                    "js_render": true,
                    "wait": 3000,
                    "wait_for": ".main-content",
                    "block_resources": "image,font",
                    "country": "us",
                    "clean_content": "js",
                    "headers": [
                      {"name": "Accept-Language", "value": "en-US"}
                    ],
                    "cookies": [
                      {"name": "consent", "value": "accepted"}
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success - Content retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "description": "Indicates if the request was successful",
                      "example": true
                    },
                    "html": {
                      "type": "string",
                      "description": "The unlocked HTML content of the page (present when type is 'html' or 'both')"
                    },
                    "screenshot": {
                      "type": "string",
                      "description": "Base64-encoded PNG screenshot of the page (present when type is 'png' or 'both')"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri",
                      "description": "The final URL after any redirects",
                      "example": "https://example.com"
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time",
                      "description": "ISO 8601 timestamp of when the content was retrieved",
                      "example": "2026-03-29T12:00:00Z"
                    },
                    "status_code": {
                      "type": "integer",
                      "description": "HTTP status code of the final response",
                      "example": 200
                    },
                    "load_time": {
                      "type": "number",
                      "description": "Time taken to load the page in milliseconds",
                      "example": 2340
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Invalid parameters provided",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {"type": "boolean", "example": false},
                    "error": {"type": "string", "example": "Invalid URL format"},
                    "code": {"type": "string", "example": "INVALID_URL"}
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment Required - x402 payment header required. The response includes payment details in the x402 field.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {"type": "boolean", "example": false},
                    "error": {"type": "string", "example": "Payment required"},
                    "x402": {
                      "type": "object",
                      "properties": {
                        "price": {"type": "string", "example": "0.01"},
                        "currency": {"type": "string", "example": "USDC"},
                        "network": {"type": "string", "example": "eip155:8453"},
                        "recipient": {"type": "string", "description": "Payment recipient address"},
                        "payment_payload": {"type": "string", "description": "Payment details for x402"}
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {"type": "boolean", "example": false},
                    "error": {"type": "string", "example": "Invalid payment signature"}
                  }
                }
              }
            }
          },
          "408": {
            "description": "Request Timeout - Page took too long to load",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {"type": "boolean", "example": false},
                    "error": {"type": "string", "example": "Page load timeout exceeded"}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests - Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {"type": "boolean", "example": false},
                    "error": {"type": "string", "example": "Rate limit exceeded"},
                    "retry_after": {"type": "integer", "description": "Seconds to wait before retrying"}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error - Server-side failure",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {"type": "boolean", "example": false},
                    "error": {"type": "string", "example": "Internal server error"}
                  }
                }
              }
            }
          },
          "504": {
            "description": "Gateway Timeout - Target server did not respond",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {"type": "boolean", "example": false},
                    "error": {"type": "string", "example": "Target server timeout"}
                  }
                }
              }
            }
          }
        }
      },
      "x-extensions": {
        "bazaar": {
          "schema": {
            "properties": {
              "output": {
                "properties": {
                  "example": {
                    "success": true,
                    "url": "https://example.com",
                    "html": "<!DOCTYPE html>...",
                    "screenshot": "data:image/png;base64,...",
                    "timestamp": "2026-03-29T12:00:00Z"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "summary": "Health check",
        "description": "Check if the Web Unlocker API service is healthy and operational. Returns the current status and version information. This endpoint is free and does not require payment.",
        "operationId": "healthCheck",
        "security": [],
        "x-paid": false,
        "x-auth-mode": "none",
        "responses": {
          "200": {
            "description": "Service healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "description": "Health status of the service",
                      "example": "ok"
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Current server timestamp",
                      "example": "2026-03-29T12:00:00Z"
                    },
                    "version": {
                      "type": "string",
                      "description": "API version",
                      "example": "1.0.0"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {"type": "string", "example": "error"},
                    "error": {"type": "string", "example": "Service temporarily unavailable"}
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "name": "PAYMENT-SIGNATURE",
        "in": "header",
        "description": "x402 payment signature header for micropayments on Base network"
      }
    }
  },
  "tags": [
    {
      "name": "Web Unlocker",
      "description": "Bypass web protections and retrieve website content"
    },
    {
      "name": "Health",
      "description": "Service health monitoring"
    }
  ]
}