# DocFast API Documentation

## Authentication

All conversion and template endpoints require an API key. Pass it in the `Authorization` header:

    Authorization: Bearer df_free_your_api_key_here

Get a free API key instantly — no credit card required:

    curl -X POST https://docfast.dev/v1/signup/free \
      -H "Content-Type: application/json" \
      -d '{"email": "you@example.com"}'

Free tier: 100 PDFs/month. Pro ($9/mo): 10,000 PDFs/month. Upgrade anytime at docfast.dev.

## Convert HTML to PDF

POST /v1/convert/html

Convert raw HTML (with optional CSS) to a PDF document.

### Request Body

Field | Type | Description
--- | --- | ---
`html` required | string | HTML content to convert
`css` | string | Additional CSS to inject
`format` | string | Page size: `A4` (default), `Letter`, `Legal`, `A3`
`landscape` | boolean | Landscape orientation (default: false)
`margin` | object | `{top, right, bottom, left}` in CSS units (default: 20mm each)

### Example

    curl -X POST https://docfast.dev/v1/convert/html \
      -H "Authorization: Bearer YOUR_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "html": "<h1>Hello World</h1><p>Generated by DocFast.</p>",
        "css": "h1 { color: navy; }",
        "format": "A4"
      }' \
      -o output.pdf

### Response

`200 OK` — Returns the PDF as `application/pdf` binary stream.

200 PDF generated 400 Missing `html` field 401 Invalid/missing API key 429 Rate limited

## Convert Markdown to PDF

POST /v1/convert/markdown

Convert Markdown to a styled PDF with syntax highlighting for code blocks.

### Request Body

Field | Type | Description
--- | --- | ---
`markdown` required | string | Markdown content
`css` | string | Additional CSS to inject
`format` | string | Page size (default: A4)
`landscape` | boolean | Landscape orientation
`margin` | object | Custom margins

### Example

    curl -X POST https://docfast.dev/v1/convert/markdown \
      -H "Authorization: Bearer YOUR_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "markdown": "# Monthly Report\n\n## Summary\n\nRevenue increased by **15%** this quarter.\n\n| Metric | Value |\n|--------|-------|\n| Users  | 1,234 |\n| MRR    | $5,670 |"
      }' \
      -o report.pdf

### Response

`200 OK` — Returns `application/pdf`.

200 PDF generated 400 Missing `markdown` field 401 Invalid/missing API key

## Convert URL to PDF

POST /v1/convert/url

Navigate to a URL and convert the rendered page to PDF. Supports JavaScript-rendered pages.

### Request Body

Field | Type | Description
--- | --- | ---
`url` required | string | URL to convert (must start with http:// or https://)
`waitUntil` | string | `load` (default), `domcontentloaded`, `networkidle0`, `networkidle2`
`format` | string | Page size (default: A4)
`landscape` | boolean | Landscape orientation
`margin` | object | Custom margins

### Example

    curl -X POST https://docfast.dev/v1/convert/url \
      -H "Authorization: Bearer YOUR_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "url": "https://example.com",
        "waitUntil": "networkidle0",
        "format": "Letter"
      }' \
      -o page.pdf

### Response

`200 OK` — Returns `application/pdf`.

200 PDF generated 400 Missing or invalid URL 401 Invalid/missing API key

## List Templates

GET /v1/templates

List all available document templates with their field definitions.

### Example

    curl https://docfast.dev/v1/templates \
      -H "Authorization: Bearer YOUR_KEY"

### Response

    {
      "templates": [
        {
          "id": "invoice",
          "name": "Invoice",
          "description": "Professional invoice with line items, taxes, and payment details",
          "fields": [
            {"name": "invoiceNumber", "type": "string", "required": true},
            {"name": "date", "type": "string", "required": true},
            {"name": "from", "type": "object", "required": true, "description": "Sender: {name, address?, email?, phone?, vatId?}"},
            {"name": "to", "type": "object", "required": true, "description": "Recipient: {name, address?, email?, vatId?}"},
            {"name": "items", "type": "array", "required": true, "description": "Line items: [{description, quantity, unitPrice, taxRate?}]"},
            {"name": "currency", "type": "string", "required": false},
            {"name": "notes", "type": "string", "required": false},
            {"name": "paymentDetails", "type": "string", "required": false}
          ]
        },
        {
          "id": "receipt",
          "name": "Receipt",
          "description": "Simple receipt for payments received",
          "fields": [ ... ]
        }
      ]
    }

## Render Template

POST /v1/templates/:id/render

Render a template with your data and get a PDF. No HTML needed — just pass structured data.

### Path Parameters

Param | Description
--- | ---
`:id` | Template ID (`invoice` or `receipt`)

### Request Body

Field | Type | Description
--- | --- | ---
`data` required | object | Template data (see field definitions from `/v1/templates`)

### Invoice Example

    curl -X POST https://docfast.dev/v1/templates/invoice/render \
      -H "Authorization: Bearer YOUR_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "data": {
          "invoiceNumber": "INV-2026-001",
          "date": "2026-02-14",
          "dueDate": "2026-03-14",
          "from": {
            "name": "Acme Corp",
            "address": "123 Main St, Vienna",
            "email": "billing@acme.com",
            "vatId": "ATU12345678"
          },
          "to": {
            "name": "Client Inc",
            "address": "456 Oak Ave, Berlin",
            "email": "accounts@client.com"
          },
          "items": [
            {"description": "Web Development", "quantity": 40, "unitPrice": 95, "taxRate": 20},
            {"description": "Hosting (monthly)", "quantity": 1, "unitPrice": 29}
          ],
          "currency": "€",
          "notes": "Payment due within 30 days.",
          "paymentDetails": "IBAN: AT12 3456 7890 1234 5678"
        }
      }' \
      -o invoice.pdf

### Response

`200 OK` — Returns `application/pdf`.

200 PDF generated 400 Missing `data` field 404 Template not found 401 Invalid/missing API key

## Sign Up (Get API Key)

POST /v1/signup/free

Get a free API key instantly. No authentication required.

### Request Body

Field | Type | Description
--- | --- | ---
`email` required | string | Your email address

### Example

    curl -X POST https://docfast.dev/v1/signup/free \
      -H "Content-Type: application/json" \
      -d '{"email": "dev@example.com"}'

### Response

    {
      "message": "Welcome to DocFast! 🚀",
      "apiKey": "df_free_abc123...",
      "tier": "free",
      "limit": "100 PDFs/month",
      "docs": "https://docfast.dev/#endpoints"
    }

Save your API key immediately — it won't be shown again.

## Error Handling

All errors return JSON with an `error` field:

    {
      "error": "Missing 'html' field"
    }

### Status Codes

Code | Meaning
--- | ---
`200` | Success — PDF returned as binary stream
`400` | Bad request — missing or invalid parameters
`401` | Unauthorized — missing or invalid API key
`404` | Not found — invalid endpoint or template ID
`429` | Rate limited — too many requests (100/min)
`500` | Server error — PDF generation failed

### Common Mistakes

    # ❌ Missing Authorization header
    curl -X POST https://docfast.dev/v1/convert/html \
      -d '{"html": "test"}'
    # → {"error": "Missing API key. Use: Authorization: Bearer <key>"}

    # ❌ Wrong Content-Type
    curl -X POST https://docfast.dev/v1/convert/html \
      -H "Authorization: Bearer YOUR_KEY" \
      -d '{"html": "test"}'
    # → Make sure to include -H "Content-Type: application/json"

    # ✅ Correct request
    curl -X POST https://docfast.dev/v1/convert/html \
      -H "Authorization: Bearer YOUR_KEY" \
      -H "Content-Type: application/json" \
      -d '{"html": "<h1>Hello</h1>"}' \
      -o output.pdf