# DocRaptor

DocRaptor is a document generation service that converts HTML or XML content into PDF or Excel files. Use it in your workflows to programmatically generate invoices, reports, contracts, or any formatted document — and get back a download link instantly.

{% hint style="info" %}
You can try DocRaptor without an account using the public test key `YOUR_API_KEY_HERE`. Documents generated with this key are always watermarked (a "TEST" stamp overlaid on every page). To generate production documents without a watermark, you need a DocRaptor account and a real API key from [docraptor.com](https://docraptor.com).
{% endhint %}

<figure><img src="https://3697023207-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2FMw7VnjKFRlpo0Vtj097G%2Fdocraptor.gif?alt=media&#x26;token=4f3d9142-3ed7-4df7-8f1f-0014dea86628" alt=""><figcaption></figcaption></figure>

### Test mode and quota

You can start building and testing your workflow without a DocRaptor account. Use the public test key `YOUR_API_KEY_HERE` in your connection — no sign-up required. Documents generated this way are always watermarked (a "TEST" stamp overlaid on every page) and, for Excel files, are limited to a small number of rows, but are otherwise fully functional for development purposes.

Once you are happy with your workflow and ready to go to production, create a DocRaptor account, replace the test key with your real API key, and switch **Test mode** to `Off`. From that point your documents will be clean and unbranded, and each run will consume your DocRaptor plan quota.

### Setting Up the Connection

1. In Stack AI, navigate to the **Connections** page.
2. Click **Add Connection** and select **DocRaptor**.
3. Enter your API key:
   * To test without an account, use `YOUR_API_KEY_HERE`
   * For production use, log in at [docraptor.com/login](https://docraptor.com/login) and copy your API key from the dashboard
4. Click **Save**.

<figure><img src="https://3697023207-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2F6d4oOOwohcGGgH6lo2y6%2Fimage.png?alt=media&#x26;token=7962f104-1d41-4a19-be59-673ead6c1165" alt="" width="375"><figcaption></figcaption></figure>

### Available Actions

#### Create Document

Converts HTML or XML content into a PDF or Excel file and returns a download URL.

**Inputs:**

| Parameter        | Type   | Required | Description                                                                                                                                                                   |
| ---------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Test mode        | Select | Yes      | `On` generates a free document (does not count against your key quota) with a "TEST" watermark on every page; `Off` generates a clean production document and uses your quota |
| Document content | Text   | Yes      | The HTML (for PDF) or XML (for Excel) content to convert                                                                                                                      |
| File type        | Select | Yes      | Output format: `pdf`, `xls`, or `xlsx`                                                                                                                                        |
| File Name        | Text   | No       | Optional name for the document, used in DocRaptor logs and as the filename                                                                                                    |

**Outputs:**

| Field                      | Type     | Description                                   |
| -------------------------- | -------- | --------------------------------------------- |
| `download_url`             | String   | Pre-signed URL to download the generated file |
| `expiration_date`          | DateTime | When the download URL expires                 |
| `file_metadata.filename`   | String   | Name of the generated file                    |
| `file_metadata.mime_type`  | String   | MIME type of the file                         |
| `file_metadata.bytes`      | Integer  | File size in bytes                            |
| `file_metadata.created_at` | DateTime | When the file was created                     |

{% hint style="info" %}
Keep **Test mode** set to `On` while building your workflow. Switch to `Off` only when you are ready to generate production documents — production runs consume your DocRaptor quota.
{% endhint %}

<figure><img src="https://3697023207-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2FGZd4DvOrgA1qP3j5Z7Zg%2FScreenshot%202026-03-25%20at%203.13.17%E2%80%AFPM.png?alt=media&#x26;token=32b06825-deac-434a-bbeb-8e7da578daf0" alt="" width="375"><figcaption></figcaption></figure>

### Structuring your HTML for PDF output

In a typical Stack AI workflow, an LLM node generates the HTML that gets passed to DocRaptor. To get a well-structured PDF with headers, footers, and logos, include the formatting requirements directly in your prompt to the model. For example:

> *"Generate an HTML invoice for the following data. Include a `<header>` with the company logo at `https://your-cdn.com/logo.png` and the invoice number, a `<footer>` with the company address, and a `<table>` with a `<thead>` for the line items. Use inline CSS with `position: running(header)` and `position: running(footer)` so they repeat on every page. All image URLs must be absolute."*

DocRaptor uses the **Prince XML** engine to render HTML into PDF. It supports standard HTML and CSS, plus a few Prince-specific CSS properties that control page layout. The key concept is **running elements** — HTML elements that are pinned to the top or bottom margin of every page, which is how you get repeating headers and footers.

#### Page layout with `@page`

Use the CSS `@page` rule to define the paper size and margins. Set the top and bottom margins large enough to accommodate your header and footer, then place your running elements in those margin boxes:

```css
@page {
  size: A4;
  margin-top: 8cm;    /* space reserved for the header */
  margin-bottom: 3cm; /* space reserved for the footer */

  @top-left { content: element(header); }
  @bottom-left { content: element(footer); }
}
```

#### Repeating header with logo

Mark any HTML element as a running header by setting `position: running(header)` in CSS. Everything inside it — logo, company name, invoice number — will repeat on every page:

```html
<header>
  <img src="https://your-cdn.com/logo.png" alt="Company Logo" />
  <h1>Your Company</h1>
  <p>Invoice #100 — 25 March 2026</p>
</header>
```

```css
header {
  position: running(header);
  height: 8cm;
}
```

#### Repeating footer

Same pattern for the footer:

```html
<footer>
  <span>yourcompany.com</span>
  <span>123 Main Street, New York, NY</span>
</footer>
```

```css
footer {
  position: running(footer);
  height: 3cm;
}
```

#### Repeating table headers across pages

If your content includes a table that spans multiple pages, use `<thead>` — Prince will automatically repeat it at the top of each page:

```html
<table>
  <thead>
    <tr>
      <th>Description</th>
      <th>Qty</th>
      <th>Total</th>
    </tr>
  </thead>
  <tbody>
    <!-- rows -->
  </tbody>
</table>
```

{% hint style="info" %}
When passing HTML to the **Create Document** node, make sure any images or fonts are referenced via absolute URLs (e.g. `https://...`). DocRaptor fetches these remotely at render time — relative paths will not resolve.
{% endhint %}

### Examples

Connect an LLM node to generate HTML content, then pass the output into the DocRaptor **Create Document** node to produce a formatted PDF. The `download_url` output can be passed to a subsequent node to send the file via email or post it to Slack.

<figure><img src="https://3697023207-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFSlso1Kjob5CLDrh0dVn%2Fuploads%2FH6V8u90pRxs1lbmtFW5p%2FScreenshot%202026-03-25%20at%203.16.58%E2%80%AFPM.png?alt=media&#x26;token=e752924a-3b4e-465c-83d9-561a9d00d218" alt=""><figcaption></figcaption></figure>