API Reference

Base URL: https://api.renderapi.dev

Authentication

All API requests require an API key passed in the x-api-key header.

x-api-key: rapi_live_YOUR_KEY_HERE

Keys prefixed with rapi_test_ are for testing — renders won't count against your quota and won't be billed. Use rapi_live_ keys in production.

Manage your API keys in the Dashboard.

Quick Start

Take a screenshot of any URL in one request:

# Returns JSON with a URL to the rendered image
curl -X POST https://api.renderapi.dev/v1/screenshot \
  -H "Content-Type: application/json" \
  -H "x-api-key: rapi_live_YOUR_KEY" \
  -d '{"url": "https://example.com"}'

Response:

{
  "id": "render_a1b2c3d4e5f6",
  "status": "completed",
  "url": "https://cdn.renderapi.dev/renders/render_a1b2c3d4e5f6.png",
  "width": 1280,
  "height": 800,
  "file_size_bytes": 284592,
  "duration_ms": 743,
  "created_at": "2025-03-18T12:00:00.000Z",
  "expires_at": "2025-03-19T12:00:00.000Z"
}

Screenshots

Capture a screenshot from a URL or raw HTML. The GET endpoint accepts the same parameters as query strings for easy browser testing.

Parameters

GET Example

# Quick test in a browser or curl
curl "https://api.renderapi.dev/v1/screenshot?url=https://example.com&format=png" \
  -H "x-api-key: rapi_live_YOUR_KEY"

Binary Response

Add response_type=binary to the GET endpoint to receive the raw image bytes instead of JSON:

curl "https://api.renderapi.dev/v1/screenshot?url=https://example.com&response_type=binary" \
  -H "x-api-key: rapi_live_YOUR_KEY" \
  -o screenshot.png

PDFs

Generate a PDF from a URL or raw HTML.

Parameters

Example: Invoice PDF

curl -X POST https://api.renderapi.dev/v1/pdf \
  -H "Content-Type: application/json" \
  -H "x-api-key: rapi_live_YOUR_KEY" \
  -d '{
    "html": "<h1>Invoice #1042</h1><table>...</table>",
    "format": "A4",
    "margin": {"top": "25mm", "bottom": "25mm", "left": "20mm", "right": "20mm"},
    "footer_html": "<div style=\"font-size:10px;text-align:center;width:100%\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div>"
  }'

Templates

Create reusable HTML templates with Handlebars syntax. Pass dynamic data at render time.

Create a Template

curl -X POST https://api.renderapi.dev/v1/templates \
  -H "Content-Type: application/json" \
  -H "x-api-key: rapi_live_YOUR_KEY" \
  -d '{
    "name": "OG Image",
    "html": "<div style=\"width:1200px;height:630px;background:#1a1a2e;color:#fff;display:flex;align-items:center;justify-content:center;font-size:48px\">{{title}}</div>",
    "sample_data": {"title": "My Blog Post"},
    "default_output": "png"
  }'

Render with Data

curl -X POST https://api.renderapi.dev/v1/template/TEMPLATE_ID/render \
  -H "Content-Type: application/json" \
  -H "x-api-key: rapi_live_YOUR_KEY" \
  -d '{"data": {"title": "How to Build an API"}, "output": "png"}'

Usage

Get your current billing period usage.

{
  "period_start": "2025-03-01T00:00:00.000Z",
  "period_end": "2025-03-31T23:59:59.999Z",
  "renders_used": 1847,
  "screenshots": 1502,
  "pdfs": 345,
  "renders_included": 5000,
  "overage_renders": 0,
  "plan": "starter"
}

Renders

Look up the status and details of a specific render by its ID.

Billing

Use /billing/checkout with {"plan": "starter"} to get a Stripe Checkout URL. Use /billing/portal to open the Stripe Customer Portal for subscription management.

Errors

All errors return a JSON object with error and message fields.

Rate Limits

Requests are rate-limited per API key. Current limits by plan:

When rate limited, you'll receive a 429 response with a Retry-After header.

Webhooks

Add a webhook_url to any render request. When the render completes (or fails), we'll POST the result to your URL.

// Webhook payload
{
  "event": "render.completed",  // or "render.failed"
  "render_id": "render_a1b2c3d4e5f6",
  "data": {
    "id": "render_a1b2c3d4e5f6",
    "status": "completed",
    "url": "https://cdn.renderapi.dev/renders/render_a1b2c3d4e5f6.png",
    ...
  },
  "timestamp": "2025-03-18T12:00:00.000Z"
}