# pdfEndpoint API Documentation
> Complete HTML to PDF conversion REST API - LLM-optimized format
## Overview
**pdfEndpoint** is a REST API that converts HTML or URLs to PDF files. The service uses a browser farm to render HTML to PDF, allowing you to test layouts locally using your browser's print-to-PDF function before sending requests to the API. PDFs can be downloaded directly or uploaded to your S3 bucket with webhook notifications.
**Base URL:** `https://api.pdfendpoint.com/v1/`
**Website:** https://pdfendpoint.com
**Documentation:** https://pdfendpoint.com/docs
## Getting Started
### Setup Guide
1. **Sign Up** - Create an account at pdfendpoint.com to receive your API key for authentication
2. **Test the API** - Make a simple request using tools like Postman or cURL to verify functionality
3. **Integrate** - Add the API key to your application requests with the necessary parameters
### Quick Start Example
```json
POST https://api.pdfendpoint.com/v1/convert
{
"html": "Getting StartedWohoo this works
You rock :) and thank you for trying pdfEndpoint
"
}
```
## Authentication
Authentication is performed via HTTP Bearer Auth Token in the header.
**Header Format:**
- Key: `Authorization`
- Value: `Bearer `
Manage API keys on the Dashboard at https://pdfendpoint.com/app/tokens after signing up.
## Endpoints
### PDF Conversion Endpoint
**POST** `https://api.pdfendpoint.com/v1/convert`
- Main endpoint for creating PDFs and returning results
### Health Endpoint
**GET** `https://api.pdfendpoint.com/health`
- Returns current system status
### Usage Endpoint
**GET** `https://api.pdfendpoint.com/v1/usage`
- Returns current API usage tied to billing cycle
### Delete PDF Endpoint
**DELETE** `https://api.pdfendpoint.com/v1/remove/:task_id`
- Delete a specific PDF by task_id (obtained from convert or list endpoint)
### List PDFs Endpoint
**GET** `https://api.pdfendpoint.com/v1/list`
- Lists created PDFs from latest to oldest
- **Query Parameters:**
- `from` - Start date (YYYY-MM-DD)
- `to` - End date (YYYY-MM-DD)
- `limit` - Number of PDFs to return (max 100)
- `page` - Page number
## Pricing & Billing
### Request Pricing
- Only successful requests count as conversions
- Failed conversions are not charged
- Use `sandbox=true` to add watermarks without counting toward monthly limit
### Monthly Conversion Limit
- Every account has a monthly conversion limit
- Check current usage on your account page
- Email notifications at 75% and 100% of limit
### Additional Conversions
- Paid plans support additional conversions beyond monthly limit
- Charged at fixed rate per conversion
## Rate Limits
**Limits:**
- Paid accounts: **240 requests per minute**
- Free accounts: **30 requests per minute**
- Contact support@pdfendpoint.com for higher limits
**Response Headers:**
- `X-RateLimit-Limit` - Max requests per minute
- `X-RateLimit-Remaining` - Requests remaining in current window
- `X-RateLimit-Reset` - UTC epoch seconds when window resets
- `X-Monthly-Limit` - Max monthly requests
- `X-Monthly-Used` - Requests used this month
**Error:** HTTP 429 when rate limit exceeded
## Error Codes
Failed requests return an error response with a `code` for lookup.
**Example Error Response:**
```json
{
"request_id": "ad67fee1-df63-4453-9dcf-020f457a6178",
"success": false,
"billed": false,
"billed_units": 0,
"error": {
"code": "PE-A003",
"status": 403,
"message": "Provided token is invalid or expired",
"description": "Make sure you have copied the token correctly from the dashboard.",
"link": null,
"support_email": "support@pdfendpoint.com"
}
}
```
Contact support@pdfendpoint.com with `request_id` for assistance.
## Sandbox Mode
Use sandbox mode for development/testing without charges.
**Parameter:** `sandbox=true`
- Adds watermark to PDFs
- Does not count toward monthly conversion limit
- Useful for testing and development
## Data Source
Choose how to pass data to the API:
### URL Parameter
- Use when HTML is hosted on a publicly accessible server
- Must be valid HTTPS URL
- Must be publicly accessible (basic HTTP auth supported)
- No redirects supported
**Example:**
```json
{
"url": "https://de.wikipedia.org/wiki/Portable_Document_Format"
}
```
### HTML Parameter
- Use when HTML code is ready on backend/client
- Faster (no need to fetch from server)
- Must include `html`, `head`, `title`, and `body` tags
- Must be properly encoded (UTF-8)
- Mutually exclusive with `url` parameter
**Example:**
```json
{
"html": "PDF EndpointHello World
"
}
```
### Liquid Templates
**parse_liquid** (boolean, default: false)
- Parse Liquid templates in HTML before conversion
- Use double curly braces `{{ }}` as placeholders
**liquid_data** (JSON object)
- Data to replace Liquid template placeholders
- Keys match template variables
**Example:**
```json
{
"html": "PDF Endpoint{{title}}
",
"parse_liquid": true,
"liquid_data": "{\"title\": \"Hello, Liquid World!\"}"
}
```
## Inject CSS & JS
### CSS Parameter
- Inject custom CSS into HTML before conversion
- Change styling or hide elements with CSS selectors
- Injected as `