# rendoc

> PDF generation API. Turn HTML templates into pixel-perfect PDFs with a single API call.

## What is rendoc?

rendoc is a cloud API for generating PDF documents from HTML templates and dynamic data. It handles fonts, paper sizes, layouts, and edge cases so you don't have to run headless browsers or manage PDF infrastructure. Also available as an MCP server for direct AI agent integration.

## Base URL

https://rendoc.dev/api/v1

## Authentication

All API requests require a Bearer token: `Authorization: Bearer <api-key>`
API keys use the format `rd_live_` followed by 64 hex characters.
Get your API key at https://rendoc.dev/dashboard/api-keys

### Scopes
- documents:write — Generate and manage documents (default)
- documents:read — View and download documents (default)
- templates:read — List and view templates (default)
- templates:write — Create, update, and delete templates
- usage:read — View usage statistics

## Quick Start

### cURL
```bash
curl -X POST https://rendoc.dev/api/v1/documents/generate \
  -H "Authorization: Bearer rd_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "markup": "<h1>Hello {{name}}</h1>",
      "paper_size": "A4"
    },
    "data": { "name": "World" }
  }'
```

### JavaScript/TypeScript
```bash
npm install @rendoc/sdk
```
```typescript
import { Rendoc } from "@rendoc/sdk";
const client = new Rendoc({ apiKey: "your-api-key" });
const doc = await client.documents.generate({
  markup: "<h1>Hello {{name}}</h1>",
  data: { name: "World" },
});
console.log(doc.downloadUrl);
```

### Python
```bash
pip install rendoc
```
```python
from rendoc import Rendoc
client = Rendoc(api_key="your-api-key")
doc = client.documents.generate(
    markup="<h1>Hello {{name}}</h1>",
    data={"name": "World"},
)
print(doc.download_url)
```

### MCP Server (for AI assistants)
```json
{
  "mcpServers": {
    "rendoc": {
      "command": "npx",
      "args": ["-y", "@rendoc/mcp-server"],
      "env": { "RENDOC_API_KEY": "your-api-key" }
    }
  }
}
```

## API Endpoints

- POST /api/v1/documents/generate — Generate a PDF from HTML markup or a saved template
- GET  /api/v1/documents/{id} — Get document details and download URL
- GET  /api/v1/templates — List available templates (filter by category)
- POST /api/v1/templates — Create a reusable template
- GET  /api/v1/templates/{id} — Get template details
- PUT  /api/v1/templates/{id} — Update a template
- DELETE /api/v1/templates/{id} — Delete a template
- GET  /api/v1/api-keys — List API keys
- POST /api/v1/api-keys — Create an API key
- DELETE /api/v1/api-keys/{id} — Revoke an API key
- GET  /api/v1/usage — Get monthly usage statistics

## Template Categories

INVOICE, RECEIPT, CONTRACT, REPORT, LETTER, CERTIFICATE, RESUME, PROPOSAL, CUSTOM

## Paper Sizes and Orientations

Sizes: A4 (595x842pt), LETTER (612x792pt), LEGAL (612x1008pt), A3 (842x1191pt), A5 (420x595pt)
Orientations: PORTRAIT (default), LANDSCAPE (width and height swapped)
Default margins: 40pt on all sides

## Rendering Engines

- react-pdf: Fast, lightweight. Good for structured documents (invoices, receipts, reports).
- chromium: Full CSS support. Best for complex layouts, custom fonts, advanced styling.

## Rate Limits (per API key, sliding window)

| Plan              | Requests/min | Documents/month | File retention |
|-------------------|-------------|-----------------|----------------|
| Free              | 10          | 100             | 7 days         |
| Starter ($19/mo)  | 60          | 1,000           | 30 days        |
| Pro ($49/mo)      | 200         | 10,000          | 90 days        |
| Scale ($199/mo)   | 1,000       | 100,000         | 365 days       |

### Rate Limit Headers
- X-RateLimit-Limit — Max requests in current window
- X-RateLimit-Remaining — Remaining requests
- X-RateLimit-Reset — Unix timestamp when window resets

## Error Codes

| Code                  | HTTP | Description                          |
|-----------------------|------|--------------------------------------|
| VALIDATION_ERROR      | 400  | Invalid request body                 |
| AUTH_REQUIRED         | 401  | Missing or invalid auth header       |
| FORBIDDEN             | 403  | API key lacks required scope         |
| NOT_FOUND             | 404  | Resource not found                   |
| RATE_LIMITED          | 429  | Too many requests per minute         |
| USAGE_LIMIT_EXCEEDED  | 429  | Monthly document quota reached       |
| INTERNAL_ERROR        | 500  | Unexpected server error              |

Error response format:
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": { "issues": [...] },
    "doc_url": "https://rendoc.dev/docs/errors#validation-error"
  }
}
```

## Webhook Events

rendoc can send webhook notifications for document lifecycle events:
- document.completed — PDF generation finished successfully
- document.failed — PDF generation failed
- usage.threshold — Monthly usage reached 80% or 100% of quota

## OpenAPI Specification

Full OpenAPI 3.1 spec available at: https://rendoc.dev/openapi.yaml

## Links

- Website: https://rendoc.dev
- Documentation: https://rendoc.dev/docs
- SDK (npm): https://www.npmjs.com/package/@rendoc/sdk
- SDK (PyPI): https://pypi.org/project/rendoc/
- MCP Server: https://www.npmjs.com/package/@rendoc/mcp-server
- OpenAPI Spec: https://rendoc.dev/openapi.yaml
- AI Plugin: https://rendoc.dev/.well-known/ai-plugin.json
- MCP Manifest: https://rendoc.dev/.well-known/mcp.json
- LLMs Full Reference: https://rendoc.dev/llms-full.txt