BimboConverter API Documentation

Introduction

BimboConverter is a high-performance HTML to PDF rendering API built on Headless Chromium. It runs a smart worker pool to handle concurrent rendering requests efficiently

The API is hosted on RapidAPI. All requests must include your X-RapidAPI-Key and X-RapidAPI-Host headers.

Base URL

https://bimboconverter.com

Response Format

A successful render returns Content-Type: application/pdf binary data. Errors are returned as application/json.

Authentication

All API requests are authenticated via RapidAPI. Include the following headers in every request:

Header	Value	Description
`X-RapidAPI-Key`	Required	Your unique API key from the RapidAPI dashboard.
`X-RapidAPI-Host`	Required	Always `bimboconverter.p.rapidapi.com`
`Content-Type`	Required	Always `application/json`

You can find your API key in the RapidAPI Dashboard after subscribing to a plan.

AI Ready (llms.txt)

BimboConverter is designed to be fully compatible with AI coding assistants like GitHub Copilot, Cursor, and Claude.

We provide a machine-readable llms.txt file containing the full API reference, parameter schemas, and best practices.

URL

https://bimboconverter.com/llms.txt

To use it, simply add the URL to your AI's context (e.g., using @https://bimboconverter.com/llms.txt in Cursor), or download the file and place it in your project's workspace rules.

View llms.txt

Quick Start

Make your first PDF in under 60 seconds. Replace YOUR_API_KEY with your key from RapidAPI.

shell

curl -X POST \
  'https://bimboconverter.com/render/document' \
  -H 'Content-Type: application/json' \
  -H 'X-RapidAPI-Key: YOUR_API_KEY' \
  -H 'X-RapidAPI-Host: bimboconverter.p.rapidapi.com' \
  -d '{
    "input": { "markup": "<h1>Hello World</h1>" },
    "output": { "paperSize": "A4" }
  }' \
  --output output.pdf

javascript

const fs = require('fs');

const response = await fetch('https://bimboconverter.com/render/document', {
  method: 'POST',
  headers: {
    'Content-Type':     'application/json',
    'X-RapidAPI-Key':   'YOUR_API_KEY',
    'X-RapidAPI-Host':  'bimboconverter.p.rapidapi.com',
  },
  body: JSON.stringify({
    input:  { markup: '<h1>Hello World</h1>' },
    output: { paperSize: 'A4', renderBackground: true },
  }),
});

const buffer = Buffer.from(await response.arrayBuffer());
fs.writeFileSync('output.pdf', buffer);
console.log(`Saved! Size: ${buffer.length} bytes`);

python

import requests

url     = "https://bimboconverter.com/render/document"
headers = {
    "Content-Type":    "application/json",
    "X-RapidAPI-Key":  "YOUR_API_KEY",
    "X-RapidAPI-Host": "bimboconverter.p.rapidapi.com",
}
payload = {
    "input":  {"markup": "<h1>Hello World</h1>"},
    "output": {"paperSize": "A4", "renderBackground": True},
}

response = requests.post(url, json=payload, headers=headers)

with open("output.pdf", "wb") as f:
    f.write(response.content)
    print(f"Saved! Size: {len(response.content)} bytes")

php

<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => "https://bimboconverter.com/render/document",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "Content-Type: application/json",
        "X-RapidAPI-Key: YOUR_API_KEY",
        "X-RapidAPI-Host: bimboconverter.p.rapidapi.com",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "input"  => ["markup" => "<h1>Hello World</h1>"],
        "output" => ["paperSize" => "A4"],
    ]),
]);
$pdf = curl_exec($ch);
curl_close($ch);
file_put_contents("output.pdf", $pdf);

POST /render/document

The primary endpoint. Renders HTML markup or an external URL into a PDF document. Returns application/pdf binary on success.

Request

Property	Type	Required	Description
`input`	object	Required	Source of the document. Must contain `markup` or `pageUrl`.
`output`	object	Optional	PDF paper and formatting settings.
`readyCheck`	object	Optional	Wait strategy before capturing the PDF.
`styleAssets`	array	Optional	CSS stylesheets to inject into the page.
`scriptAssets`	array	Optional	JavaScript files or inline code to inject.
`sessionCookies`	array	Optional	Cookies to set before loading the page.
`extraHeaders`	object	Optional	Custom HTTP headers for the page request.

Responses

200

OKBinary PDF. Check X-Render-Time-Ms header for render duration.

400

Bad RequestInvalid parameters. Missing required fields or wrong types.

422

Render ErrorChromium failed to render. URL unreachable, timeout exceeded, or page crashed.

503

Queue FullAll workers are busy and the queue is full. Retry after a short delay.

GET /status/health

Public health check endpoint. No authentication required. Returns server and pool metrics.

Response

{
  "status": "ok",
  "uptime": 3600,
  "pool": {
    "total":  4,
    "free":   3,
    "busy":   1,
    "queued": 0
  },
  "queue": {
    "pending":      0,
    "maxQueueSize": 50
  }
}

Parameter: `input`

Defines the source document. Provide exactly one of markup or pageUrl.

Field	Type	Description
`markup`	string	Raw HTML string. Min length: 1 character.
`pageUrl`	string (uri)	Any publicly accessible URL. Must start with `https://` or `http://`.

Parameter: `output`

Controls paper format, orientation, margins, and rendering options.

Field	Type	Default	Description
`paperSize`	enum	`A4`	Letter, Legal, Tabloid, Ledger, A0–A6
`zoom`	number	`1`	Scale factor from 0.1 to 2.0
`renderBackground`	boolean	`false`	Print CSS background graphics and colors
`horizontal`	boolean	`false`	Landscape mode
`pages`	string	all	Page ranges to print, e.g. `"1-5, 8"`
`paperWidth`	string	—	Custom width, e.g. `"8.5in"`, `"210mm"`
`paperHeight`	string	—	Custom height
`spacing`	object	none	Margins: `{ top, right, bottom, left }`. Accepts units: px, mm, cm, in
`cssPagePriority`	boolean	`false`	Let CSS `@page` size override the options
`showHeaderFooter`	boolean	`false`	Display header and footer templates
`headerMarkup`	string	—	HTML for page header. Use `.pageNumber`, `.totalPages`, `.date` class spans
`footerMarkup`	string	—	HTML for page footer (same classes as header)

Example: Full output config

{
  "output": {
    "paperSize":        "A4",
    "zoom":             1.0,
    "renderBackground": true,
    "horizontal":       false,
    "pages":            "1-3, 5",
    "spacing": {
      "top":    "20mm",
      "right":  "15mm",
      "bottom": "20mm",
      "left":   "15mm"
    },
    "showHeaderFooter": true,
    "headerMarkup": "<div style='font-size:10px'>My Report</div>",
    "footerMarkup": "<div style='font-size:10px;text-align:right'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></div>"
  }
}

Parameter: `readyCheck`

Defines when Chromium considers the page ready to capture. Useful for SPA pages, lazy-loaded images, or charts rendered by JavaScript.

Field	Type	Description
`strategy`	enum	Required. One of: `navigation`, `element`, `expression`, `delay`
`event`	enum	For `navigation`: `load` \| `domcontentloaded` \| `networkidle0` \| `networkidle2`
`cssQuery`	string	For `element`: CSS selector to wait for, e.g. `"#chart-loaded"`
`mustBeVisible`	boolean	For `element`: wait until element is visible (not hidden)
`mustBeHidden`	boolean	For `element`: wait until element is hidden (e.g. a loading spinner)
`evalCode`	string	For `expression`: JS expression that returns `true` when ready, e.g. `"window.chartsLoaded === true"`
`checkInterval`	number \| string	For `expression`: polling interval in ms, or `"raf"`, `"mutation"`
`limitMs`	number	Maximum wait time in ms (0–30000). Defaults to 10000.
`durationMs`	number	For `delay`: fixed wait time in ms.

Strategy Examples

Wait for network to go quiet (best for SPAs)

{ "strategy": "navigation", "event": "networkidle2", "limitMs": 15000 }

Wait for a specific element to appear

{ "strategy": "element", "cssQuery": "#chart-container.ready", "limitMs": 10000 }

Wait for a JS expression

{ "strategy": "expression", "evalCode": "window.__pdfReady === true", "limitMs": 10000 }

Fixed delay

{ "strategy": "delay", "durationMs": 2000 }

Parameters: `styleAssets` / `scriptAssets`

Inject CSS or JavaScript into the page before the PDF is captured. Useful for adding print-only styles or polyfills.

Field	Type	Description
`url`	string (uri)	URL of an external CSS/JS file to inject.
`content`	string	Inline CSS or JS code to inject directly.
`type`	string	(scriptAssets only) Set to `"module"` for ES6 modules.

Example

{
  "styleAssets": [
    { "content": "@media print { .no-print { display: none; } }" },
    { "url": "https://example.com/print-override.css" }
  ],
  "scriptAssets": [
    { "content": "window.__pdfMode = true;" }
  ]
}

Parameter: `sessionCookies`

Set session cookies before loading the page. Useful to render pages behind authentication.

Field	Type	Required	Description
`name`	string	Required	Cookie name
`value`	string	Required	Cookie value
`url`	string	Optional	URL to which cookie is applied
`domain`	string	Optional	Host to which the cookie is sent
`path`	string	Optional	Cookie path, defaults to `/`
`expires`	number	Optional	Unix timestamp. Omit for session cookie.
`httpOnly`	boolean	Optional	Forbid JS access to the cookie
`secure`	boolean	Optional	HTTPS-only cookie
`sameSite`	enum	Optional	`"Strict"` or `"Lax"`

Parameter: `extraHeaders`

Pass custom HTTP headers with every request Chromium makes when loading the page. Ideal for Bearer token authentication.

These headers are added to every request on the page, including third-party resources. Avoid sending secrets to untrusted external domains.

Example

{
  "extraHeaders": {
    "Authorization": "Bearer eyJhbGci...",
    "X-Custom-Header": "my-value"
  }
}

Error Codes

All errors return application/json with a consistent shape:

Error shape

{ "error": "ERROR_CODE", "message": "Human-readable description" }

HTTP	Code	Cause
400	`VALIDATION_ERROR`	Missing required field or wrong type
400	`VALIDATION_CONFLICT`	Both `markup` and `pageUrl` provided
403	`FORBIDDEN`	Invalid or missing RapidAPI key
422	`RENDER_TIMEOUT`	Page did not load within the allowed time
422	`RENDER_ERROR`	Chromium crashed or page returned an error
503	`QUEUE_FULL`	All workers busy, queue capacity exceeded. Retry later.
500	`INTERNAL_ERROR`	Unexpected server-side error

Code Examples

Invoice with header/footer

json

{
  "input": { "markup": "<html>...your invoice HTML...</html>" },
  "output": {
    "paperSize":        "A4",
    "renderBackground": true,
    "spacing":          { "top": "25mm", "bottom": "20mm" },
    "showHeaderFooter": true,
    "headerMarkup": "<div style='font-size:9px;padding:0 20px;width:100%;text-align:right;color:#999'>Confidential</div>",
    "footerMarkup": "<div style='font-size:9px;padding:0 20px;width:100%;display:flex;justify-content:space-between'><span>© Acme Corp</span><span>Page <span class='pageNumber'></span> / <span class='totalPages'></span></span></div>"
  }
}

Render a JS-heavy dashboard URL

json

{
  "input": { "pageUrl": "https://your-app.com/report/monthly" },
  "readyCheck": {
    "strategy": "element",
    "cssQuery": "#charts-rendered",
    "mustBeVisible": true,
    "limitMs": 20000
  },
  "sessionCookies": [
    { "name": "session_id", "value": "abc123xyz", "domain": "your-app.com" }
  ],
  "output": { "paperSize": "A4", "horizontal": true, "renderBackground": true }
}

Landscape report with custom styles

json

{
  "input": { "markup": "<html>...</html>" },
  "output": {
    "horizontal":       true,
    "paperSize":        "A3",
    "renderBackground": true,
    "zoom":             0.85
  },
  "styleAssets": [
    { "content": "body { font-size: 11px; } table { page-break-inside: avoid; }" }
  ]
}

Rate Limits

Limits are enforced per subscription tier on RapidAPI:

Plan	Renders / month	Max Concurrent	Features
Free	50	1	HTML markup only
Pro	1,000	3	Markup + URL, all paper sizes
Business	10,000	10	All features, priority queue

If the queue is full, the server returns 503. Implement exponential backoff and retry logic in your client for robustness.

Introduction

Base URL

Response Format

Authentication

AI Ready (llms.txt)

Quick Start

POST /render/document

Request

Responses

GET /status/health

Parameter: input

Parameter: output

Parameter: readyCheck

Strategy Examples

Parameters: styleAssets / scriptAssets

Parameter: sessionCookies

Parameter: extraHeaders

Error Codes

Code Examples

Invoice with header/footer

Render a JS-heavy dashboard URL

Landscape report with custom styles

Rate Limits

Parameter: `input`

Parameter: `output`

Parameter: `readyCheck`

Parameters: `styleAssets` / `scriptAssets`

Parameter: `sessionCookies`

Parameter: `extraHeaders`