Skip to content

Latest commit

 

History

History
266 lines (205 loc) · 6.29 KB

API.md

File metadata and controls

266 lines (205 loc) · 6.29 KB

API Reference

Complete API documentation for Open Browser Rendering.

Base URL

http://localhost:3000

Authentication

All endpoints (except / and /health) require Bearer token authentication.

Header:

Authorization: Bearer YOUR_API_KEY

Endpoints

1. Root Endpoint

Get API information.

Endpoint: GET /

Authentication: Not required

Response:

{
  "name": "Open Browser Rendering",
  "version": "1.0.0",
  "description": "Open-source alternative to Cloudflare Browser Rendering API",
  "endpoints": {
    "screenshot": "POST /screenshot",
    "pdf": "POST /pdf",
    "evaluate": "POST /evaluate",
    "health": "GET /health"
  },
  "documentation": "https://github.com/devmode-id/OpenBrowserRendering"
}

2. Screenshot Endpoint

Capture a screenshot of a web page.

Endpoint: POST /screenshot

Authentication: Required

Request Body:

Field Type Required Default Description
url string Yes - URL to capture
viewport object No {width: 1280, height: 720} Viewport dimensions
viewport.width number No 1280 Viewport width in pixels
viewport.height number No 720 Viewport height in pixels
screenshotOptions object No {} Screenshot options
screenshotOptions.fullPage boolean No false Capture full page
screenshotOptions.type string No "png" Image type: "png" or "jpeg"
screenshotOptions.quality number No - JPEG quality (1-100)
gotoOptions object No {} Navigation options
gotoOptions.waitUntil string No "networkidle" Wait condition: "load", "domcontentloaded", "networkidle"
gotoOptions.timeout number No 30000 Navigation timeout in ms

Example Request:

{
  "url": "https://example.com",
  "viewport": {
    "width": 1920,
    "height": 1080
  },
  "screenshotOptions": {
    "fullPage": true,
    "type": "png"
  },
  "gotoOptions": {
    "waitUntil": "networkidle",
    "timeout": 30000
  }
}

Response:

  • Content-Type: image/png or image/jpeg
  • Body: Binary image data

Error Responses:

Status Description
400 Invalid request body
401 Unauthorized (invalid API key)
429 Too many concurrent requests
500 Server error

3. PDF Endpoint

Generate a PDF from a web page.

Endpoint: POST /pdf

Authentication: Required

Request Body:

Field Type Required Default Description
url string Yes - URL to convert
format string No "A4" Paper format: "Letter", "Legal", "Tabloid", "Ledger", "A0"-"A6"
printBackground boolean No true Print background graphics
gotoOptions object No {} Navigation options
gotoOptions.waitUntil string No "networkidle" Wait condition
gotoOptions.timeout number No 30000 Navigation timeout in ms

Example Request:

{
  "url": "https://example.com",
  "format": "A4",
  "printBackground": true,
  "gotoOptions": {
    "waitUntil": "networkidle",
    "timeout": 30000
  }
}

Response:

  • Content-Type: application/pdf
  • Body: Binary PDF data

Error Responses:

Status Description
400 Invalid request body
401 Unauthorized (invalid API key)
429 Too many concurrent requests
500 Server error

4. Evaluate Endpoint

Execute JavaScript in a page context.

Endpoint: POST /evaluate

Authentication: Required

Request Body:

Field Type Required Default Description
url string Yes - URL to navigate to
script string Yes - JavaScript code to execute
gotoOptions object No {} Navigation options
gotoOptions.waitUntil string No "networkidle" Wait condition
gotoOptions.timeout number No 30000 Navigation timeout in ms

Example Request:

{
  "url": "https://example.com",
  "script": "document.title",
  "gotoOptions": {
    "waitUntil": "networkidle",
    "timeout": 30000
  }
}

Response:

{
  "result": "Example Domain"
}

Complex Script Example:

{
  "url": "https://example.com",
  "script": "({ title: document.title, links: document.querySelectorAll('a').length })"
}

Response:

{
  "result": {
    "title": "Example Domain",
    "links": 5
  }
}

Error Responses:

Status Description
400 Invalid request body
401 Unauthorized (invalid API key)
429 Too many concurrent requests
500 Server error or script execution error

5. Health Check Endpoint

Check service health and status.

Endpoint: GET /health

Authentication: Not required

Response:

{
  "status": "ok",
  "active": 0,
  "maxConcurrency": 2,
  "browserEngine": "chromium",
  "uptime": 123.456
}

Fields:

Field Type Description
status string Service status: "ok"
active number Current active rendering requests
maxConcurrency number Maximum concurrent requests allowed
browserEngine string Browser engine in use
uptime number Server uptime in seconds

Rate Limiting

The API implements concurrency-based rate limiting. When the maximum number of concurrent requests is reached, additional requests will receive a 429 Too Many Concurrent Requests error.

Configure MAX_CONCURRENCY in your .env file based on your server resources.

Error Handling

All error responses follow this format:

{
  "error": "Error message description"
}

Best Practices

  1. Set appropriate timeouts - Adjust gotoOptions.timeout based on expected page load time
  2. Use networkidle for dynamic content - For JavaScript-heavy sites, use waitUntil: "networkidle"
  3. Optimize viewport size - Use smaller viewports when possible to reduce memory usage
  4. Handle errors gracefully - Implement retry logic for transient failures
  5. Monitor concurrency - Check /health endpoint to monitor active requests

Examples

See EXAMPLES.md for complete code examples in various programming languages.