# rendoc — Complete AI Reference

> PDF generation API and MCP server. Create documents from HTML templates and JSON data.

## Product Overview

rendoc is a cloud-hosted PDF generation service. You send HTML markup (with Handlebars-style {{variables}}) and JSON data, and receive a downloadable PDF. rendoc handles rendering, fonts, page layout, and storage.

Two rendering engines are available:
- react-pdf: Fast, lightweight. Best for structured documents (invoices, receipts, tables).
- chromium: Full CSS support. Best for complex layouts, custom fonts, advanced styling.

Base URL: https://rendoc.dev/api/v1
OpenAPI spec: https://rendoc.dev/openapi.yaml

## Authentication

All API requests require a Bearer token in the Authorization header.

```
Authorization: Bearer rd_live_your_key_here
```

API keys are created from the dashboard at https://rendoc.dev/dashboard/api-keys.
Key format: `rd_live_` prefix followed by 64 hex characters.
Keys are shown once at creation and stored as SHA-256 hashes on the server.

### Scopes

Each API key has permission scopes:

| Scope             | Description                       | Default |
|-------------------|-----------------------------------|---------|
| documents:write   | Generate and manage documents     | Yes     |
| documents:read    | View and download documents       | Yes     |
| templates:read    | List and view templates           | Yes     |
| templates:write   | Create, update, delete templates  | No      |
| usage:read        | View usage statistics             | No      |

## API Endpoints

### POST /api/v1/documents/generate

Generate a PDF. Provide either `template_id` (saved template) or `template` (inline), plus `data`.

Request:
```json
{
  "template_id": "tpl_abc123",
  "data": {
    "company_name": "Acme Corp",
    "invoice_number": "INV-2026-001",
    "items": [
      { "description": "API integration", "quantity": 1, "unit_price": 500 }
    ]
  },
  "options": {
    "filename": "invoice-2026-001.pdf",
    "metadata": { "customer_id": "cust_xyz" }
  }
}
```

Or with inline template:
```json
{
  "template": {
    "markup": "<h1>Invoice #{{invoice_number}}</h1><p>Bill to: {{client_name}}</p>",
    "paper_size": "A4",
    "orientation": "portrait"
  },
  "data": {
    "invoice_number": "INV-001",
    "client_name": "Acme Corp"
  }
}
```

Response (200):
```json
{
  "success": true,
  "data": {
    "id": "doc_k7m2n9p4",
    "status": "completed",
    "download_url": "https://rendoc.dev/dl/doc_k7m2n9p4",
    "file_name": "invoice-2026-001.pdf",
    "file_size": 48210,
    "page_count": 1,
    "created_at": "2026-03-24T10:30:00Z",
    "expires_at": "2026-03-31T10:30:00Z"
  }
}
```

### GET /api/v1/documents/{id}

Retrieve document metadata. Set `Accept: application/pdf` header to download the PDF binary directly.

### GET /api/v1/templates

List templates. Optional query parameter: `category` (INVOICE, RECEIPT, CONTRACT, REPORT, LETTER, CERTIFICATE, RESUME, PROPOSAL, CUSTOM).

Response (200):
```json
{
  "success": true,
  "data": {
    "templates": [
      {
        "id": "tpl_abc123",
        "name": "Standard Invoice",
        "slug": "standard-invoice",
        "category": "INVOICE",
        "paper_size": "A4",
        "orientation": "PORTRAIT",
        "is_public": true,
        "version": 1,
        "created_at": "2026-01-15T08:00:00Z"
      }
    ]
  }
}
```

### POST /api/v1/templates

Create a reusable template.

Required fields: name, slug, markup.
Optional: description, category (default: CUSTOM), styles, schema, sample_data, paper_size (default: A4), orientation (default: PORTRAIT), is_public (default: false).

Markup max: 500,000 characters. Styles max: 100,000 characters.

### GET /api/v1/templates/{id}

Get full template details including markup, schema, and sample data.

### PUT /api/v1/templates/{id}

Partial update. Only provided fields change. Version auto-increments.

### DELETE /api/v1/templates/{id}

Permanently delete a template.

### GET /api/v1/api-keys

List all API keys (session auth required, not API key auth).

### POST /api/v1/api-keys

Create new API key. Required: name (1-50 chars). Optional: scopes, expires_in_days.
The full key is returned only in this response.

### DELETE /api/v1/api-keys/{id}

Permanently revoke and delete an API key.

### GET /api/v1/usage

Get usage statistics. Optional query params: year, month. Defaults to current period.

Response includes: plan, period, usage (documents, limit, percentage, pages, bytes), daily breakdown, per-key breakdown.

## Template System

Templates use Handlebars-style variable syntax:
- `{{variable}}` — Simple variable replacement
- `{{object.property}}` — Nested property access
- `{{items}}` — Array data (renders as table rows)

### Template Categories

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

### Paper Sizes

| Size   | Width (pt) | Height (pt) | Use Case                    |
|--------|-----------|-------------|------------------------------|
| A4     | 595.28    | 841.89      | Standard international docs  |
| LETTER | 612       | 792         | US standard documents        |
| LEGAL  | 612       | 1008        | US legal documents           |
| A3     | 841.89    | 1190.55     | Large format, posters        |
| A5     | 419.53    | 595.28      | Booklets, flyers             |

### Orientations

- PORTRAIT (default): Taller than wide
- LANDSCAPE: Width and height swapped

Default margins: 40pt on all sides.

## Webhook Events

Configure webhooks from the dashboard. Events are sent as POST requests with JSON payload.

| Event               | Description                                  |
|---------------------|----------------------------------------------|
| document.completed  | PDF generation finished successfully         |
| document.failed     | PDF generation failed                        |
| usage.threshold     | Monthly usage reached 80% or 100% of quota   |

## MCP Server Setup

The rendoc MCP server lets AI agents generate PDFs directly.

### Claude Code / Claude Desktop

Add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "rendoc": {
      "command": "npx",
      "args": ["-y", "@rendoc/mcp-server"],
      "env": { "RENDOC_API_KEY": "rd_live_your_key_here" }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "rendoc": {
      "command": "npx",
      "args": ["-y", "@rendoc/mcp-server"],
      "env": { "RENDOC_API_KEY": "rd_live_your_key_here" }
    }
  }
}
```

### MCP Tools

| Tool                | Description                                        |
|---------------------|----------------------------------------------------|
| generate_document   | Generate a PDF from template + data                |
| list_templates      | Browse templates with optional category filter     |
| get_document        | Get details and download URL for a document        |
| get_usage           | Check current API usage and remaining quota        |
| preview_template    | Inspect template markup, schema, and sample data   |

## SDK Usage

### JavaScript / TypeScript (npm)

```bash
npm install @rendoc/sdk
```

```typescript
import { Rendoc } from "@rendoc/sdk";

const client = new Rendoc({ apiKey: process.env.RENDOC_API_KEY });

// Generate from inline template
const doc = await client.documents.generate({
  markup: "<h1>Hello {{name}}</h1>",
  data: { name: "World" },
  paperSize: "A4",
});

// Generate from saved template
const doc2 = await client.documents.generate({
  templateId: "tpl_abc123",
  data: { company: "Acme Corp", total: 5500 },
});

console.log(doc.downloadUrl);
```

### Python (pip)

```bash
pip install rendoc
```

```python
import os
from rendoc import Rendoc

client = Rendoc(api_key=os.environ["RENDOC_API_KEY"])

doc = client.documents.generate(
    markup="<h1>Hello {{name}}</h1>",
    data={"name": "World"},
    paper_size="A4",
)

print(doc.download_url)
```

### cURL

```bash
# Generate a document
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>Invoice #{{number}}</h1><p>Total: ${{total}}</p>",
      "paper_size": "A4"
    },
    "data": { "number": "INV-001", "total": "1250.00" }
  }'

# Get document metadata
curl https://rendoc.dev/api/v1/documents/doc_abc123 \
  -H "Authorization: Bearer rd_live_your_key_here"

# Download PDF binary
curl https://rendoc.dev/api/v1/documents/doc_abc123 \
  -H "Authorization: Bearer rd_live_your_key_here" \
  -H "Accept: application/pdf" \
  -o output.pdf

# List templates
curl https://rendoc.dev/api/v1/templates?category=INVOICE \
  -H "Authorization: Bearer rd_live_your_key_here"
```

## Rate Limits and Quotas

Rate limits are per API key using a sliding window algorithm.

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

### Rate Limit Headers

Every response includes:
- `X-RateLimit-Limit` — Max requests in current window
- `X-RateLimit-Remaining` — Remaining requests in current window
- `X-RateLimit-Reset` — Unix timestamp (seconds) when window resets

## Error Handling

All errors follow a consistent JSON format:

```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": {},
    "doc_url": "https://rendoc.dev/docs/errors#error-code"
  }
}
```

### Error Codes

| Code                  | HTTP | Description                              | Action                          |
|-----------------------|------|------------------------------------------|---------------------------------|
| VALIDATION_ERROR      | 400  | Invalid request body                     | Check required fields and types |
| AUTH_REQUIRED         | 401  | Missing or invalid Authorization header  | Verify API key is correct       |
| FORBIDDEN             | 403  | API key lacks required scope             | Create key with needed scopes   |
| NOT_FOUND             | 404  | Resource not found                       | Verify ID exists and is yours   |
| RATE_LIMITED          | 429  | Too many requests per minute             | Wait for X-RateLimit-Reset      |
| USAGE_LIMIT_EXCEEDED  | 429  | Monthly document quota reached           | Upgrade plan or wait for reset  |
| INTERNAL_ERROR        | 500  | Unexpected server error                  | Retry with backoff, then contact support |

### USAGE_LIMIT_EXCEEDED Response

```json
{
  "error": {
    "code": "USAGE_LIMIT_EXCEEDED",
    "message": "Monthly document limit reached (100). Upgrade your plan.",
    "details": {
      "current_usage": 100,
      "limit": 100,
      "reset_at": "2026-04-01T00:00:00.000Z"
    }
  }
}
```

## Links

- Website: https://rendoc.dev
- Documentation: https://rendoc.dev/docs
- OpenAPI Spec: https://rendoc.dev/openapi.yaml
- 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
- AI Plugin: https://rendoc.dev/.well-known/ai-plugin.json
- MCP Manifest: https://rendoc.dev/.well-known/mcp.json
- Sign up: https://rendoc.dev/register
- Contact: info@rendoc.dev