API Overview

The Browser7 REST API provides direct HTTP access to render web pages with geo-targeting, CAPTCHA solving, and wait actions. Use the REST API when you need maximum flexibility or when an SDK is not available for your language.

Base URL

All API requests are made to:

https://api.browser7.com/v1

Regional Endpoints (Advanced)

The default endpoint api.browser7.com uses geo-DNS to automatically route requests to the nearest data center for optimal performance. For advanced use cases, you can explicitly target specific regions. See Data Centers for details.

API Versioning

The current API version is v1, included in the base URL path. Future versions will be released at new paths (e.g., /v2) while maintaining backward compatibility with existing versions.

Request Format

All POST and PUT requests must:

• Use Content-Type: application/json
• Include your API key in the Authorization header
• Send valid JSON in the request body

Example request:

curl -X POST https://api.browser7.com/v1/renders \
  -H "Authorization: Bearer b7_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Response Format

All API responses return JSON with appropriate HTTP status codes:

Success Response (2xx):

{
  "renderId": "ren_abc123xyz"
}

Error Response (4xx/5xx):

{
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked"
}

HTTP Status Codes

Status Code	Meaning
200 OK	Request succeeded
201 Created	Resource created successfully
400 Bad Request	Invalid request parameters
401 Unauthorized	Invalid or missing API key
402 Payment Required	Insufficient account balance
404 Not Found	Resource not found
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server error
503 Service Unavailable	Service temporarily unavailable

Rate Limits

See Rate Limits for details on rate limiting and best practices.

API Endpoints

Endpoint	Method	Description
/renders	POST	Create a new render job
/renders/:id	GET	Get render status and result
/account/balance	GET	Get current account balance

Data Compression

The API automatically compresses large response data to reduce bandwidth:

• HTML content: Gzipped and base64-encoded
• Fetch responses: Gzipped and base64-encoded JSON

SDKs automatically handle decompression. If using the API directly, you'll need to:

1. Base64 decode the string
2. Gunzip the resulting buffer
3. Parse as UTF-8 text (HTML) or JSON (fetch responses)

Example in Node.js:

const zlib = require('zlib');
const { promisify } = require('util');
const gunzip = promisify(zlib.gunzip);

// Decompress HTML
const buffer = Buffer.from(response.html, 'base64');
const decompressed = await gunzip(buffer);
const html = decompressed.toString('utf-8');

Polling Pattern

Browser7 uses an asynchronous rendering model:

1. Create render - POST to /renders returns immediately with renderId
2. Wait - Wait 2-3 seconds before first poll
3. Poll status - GET /renders/:id to check status
4. Repeat - Continue polling until status is completed or failed
5. Respect retry-after - Use the retryAfter field for optimal polling interval

The SDKs handle this pattern automatically via the render() method.

Next Steps

• Authentication - Learn how to authenticate API requests
• Create Render - Start a new render job
• Get Render - Retrieve render results
• Error Handling - Handle API errors gracefully