# BimboConverter API
> High-performance HTML/URL to PDF conversion service built on Node.js, Fastify, and Puppeteer. Converts raw HTML markup or any public URL into a pixel-perfect PDF document. Single POST endpoint, returns binary PDF.
- **Base URL:** [https://bimboconverter.com](https://bimboconverter.com)
- **Docs:** [https://bimboconverter.com/docs.html](https://bimboconverter.com/docs.html)
---
## Endpoints
### POST /render/document
Renders a PDF document. Returns `application/pdf` binary on success.
**Minimal request body:**
```json
{
"input": {
"markup": "Hello
"
}
}
```
Or using an external URL:
```json
{
"input": {
"pageUrl": "https://example.com"
}
}
```
> IMPORTANT: Provide exactly one of `markup` or `pageUrl`. Providing both returns 400.
---
### GET /status/health
Public health check. No authentication required. Returns JSON with server uptime, browser pool status, and queue metrics.
Endpoint URL: [https://bimboconverter.com/status/health](https://bimboconverter.com/status/health)
---
## Full Request Schema: POST /render/document
### `input` (Required)
| Field | Type | Description |
|-----------|--------|--------------------------------------------|
| `markup` | string | Raw HTML string to render |
| `pageUrl` | string | Any publicly accessible URL to render |
### `output` (Optional) — PDF formatting
| Field | Type | Default | Description |
|--------------------|---------|---------|----------------------------------------------------------|
| `paperSize` | enum | `"A4"` | `"Letter"`, `"Legal"`, `"A0"`–`"A6"`, `"Tabloid"`, `"Ledger"` |
| `zoom` | number | `1` | Scale factor, range 0.1–2.0 |
| `renderBackground` | boolean | `false` | Print CSS background colors and images |
| `horizontal` | boolean | `false` | Landscape orientation |
| `pages` | string | all | Page ranges to print, e.g. `"1-3, 5"` |
| `paperWidth` | string | — | Custom width, e.g. `"8.5in"`, `"210mm"` |
| `paperHeight` | string | — | Custom height |
| `spacing` | object | none | Margins: `{ top, right, bottom, left }` — any CSS units |
| `cssPagePriority` | boolean | `false` | Let CSS `@page` size override output options |
| `showHeaderFooter` | boolean | `false` | Enable header and footer templates |
| `headerMarkup` | string | — | HTML for page header. Use ``, `` |
| `footerMarkup` | string | — | HTML for page footer. Use ``, `` |
### `readyCheck` (Optional) — wait strategy before capture
| 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 |
| `mustBeHidden` | boolean | For `element`: wait until element is hidden (e.g. a loading spinner) |
| `evalCode` | string | For `expression`: JS expression returning `true` when ready |
| `checkInterval`| mixed | For `expression`: `number` (ms) or `"raf"` or `"mutation"` |
| `limitMs` | number | Max wait time in ms (e.g., 5000) |
| `durationMs` | number | For `delay`: fixed wait time in ms |
### `styleAssets` (Optional) — array of CSS to inject
| Field | Type | Description |
|-----------|--------|------------------------------------|
| `url` | string | URL of external stylesheet |
| `content` | string | Inline CSS string |
### `scriptAssets` (Optional) — array of JS to inject
| Field | Type | Description |
|-----------|--------|------------------------------------|
| `url` | string | URL of external JS file |
| `content` | string | Inline JS string |
| `type` | string | Set to `"module"` for ES modules |
### `sessionCookies` (Optional) — array for auth bypass
| Field | Type | Required | Description |
|------------|---------|----------|------------------------------------|
| `name` | string | ✓ | Cookie name |
| `value` | string | ✓ | Cookie value |
| `url` | string | | URL to which cookie is applied |
| `domain` | string | | Host the cookie applies to |
| `path` | string | | Cookie path |
| `expires` | number | | Unix timestamp |
| `httpOnly` | boolean | | |
| `secure` | boolean | | |
| `sameSite` | enum | | `"Strict"` or `"Lax"` |
### `extraHeaders` (Optional) — object
Key-value pairs of HTTP headers added to every request Chromium makes when loading the page.
```json
{ "Authorization": "Bearer token123" }
```
---
## HTTP Response Codes
| Code | Meaning |
|------|------------------------------------------------------------|
| 200 | PDF binary returned. Header `X-Render-Time-Ms` = duration |
| 400 | Validation error — check request body |
| 422 | Render error — Puppeteer failed (bad HTML, navigation etc.)|
| 503 | Queue full — server is overloaded, retry later |
| 504 | Render timeout — exceeded maximum render time |
---
## Code Examples
### cURL — HTML to PDF
```bash
curl -X POST https://bimboconverter.com/render/document \
-H "Content-Type: application/json" \
-d '{
"input": { "markup": "Invoice #1024
" },
"output": { "paperSize": "A4", "renderBackground": true }
}' \
--output invoice.pdf
```
### Node.js — URL with ready checks
```js
const res = await fetch('https://bimboconverter.com/render/document', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
input: { pageUrl: 'https://my-app.com/reports/monthly' },
readyCheck: { strategy: 'navigation', event: 'networkidle2', limitMs: 15000 },
output: { paperSize: 'A4', horizontal: true, renderBackground: true }
})
});
const pdf = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('report.pdf', pdf);
```
---
## Tips for AI Code Generation
- Always save the response as binary (`arrayBuffer`, `response.content`, `--output file.pdf`).
- The response `Content-Type` is `application/pdf` — do not parse as JSON.
- `readyCheck.strategy: "networkidle2"` is the safest choice for any page using JavaScript.
- `renderBackground: true` is usually needed for invoices and styled documents.
- Use `showHeaderFooter: true` with `headerMarkup` / `footerMarkup` for paginated reports.
- On 503, implement backoff and retry later.