We are in official beta.

Quick Start

Your first DocButterfly call, end to end. Get a key, convert an HTML document to PDF, and read what it cost you — in about five minutes.

Jump to: Your First Call Skip the code, run one now Base URL & hosts Power Automate / Logic Apps

Building in Power Automate or Logic Apps? You can skip the curl entirely: import our custom connector and every DocButterfly action becomes a native, typed step with the key held on the connection. The rest of this page still applies — same key, same endpoints, same response headers.

The API lives on https://api.docbutterfly.com. Every endpoint hangs off /api/… on that host. If you are seeing 404 on a request you are sure is correct, you are almost certainly calling docbutterfly.com — that is this website, and it serves no API. A wrong key answers 401, never 404. Base URL & hosts.

1. Get an API key

Sign in and open Portal → API Key. Your key looks like df_… and is shown in full when it is created or regenerated. If your account keeps a retrievable copy of the key, the page also offers Show key later; otherwise the only way to recover a lost key is to regenerate it, which immediately invalidates the old one. Which mode you are in is explained in Security Best Practices.

The key is a credential. It authenticates every call and spends your tokens. Keep it server-side — never in a browser bundle, a mobile app, a public repository, or a URL.

2. Make your first call

Every endpoint takes the key in an X-API-Key header and returns JSON.

https://api.docbutterfly.com

That host, and nothing else. docbutterfly.com is this website and serves no API — a request there answers 404 however good your key is. Base URL & hosts has the whole story, including the other host that still works.

cURL

curl -i -X POST "https://api.docbutterfly.com/api/ConvertHtmlToPdf" \
  -H "X-API-Key: $DOCBUTTERFLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello</h1>", "returnBase64": true}'

The response carries the document plus what the call cost. Three headers on a billed response tell you where you stand without a second request:

Header	Meaning
`X-Tokens-Used`	What this call actually cost, after settlement.
`X-Tokens-Remaining`	What is left in your balance afterwards (the literal word `unlimited` on an unmetered account).
`X-Correlation-Id`	The id this request is logged under. Quote it when you ask us about a call.

Prefer to send the key as Authorization: Bearer df_…? That works too. A key in the query string does not — that route was removed deliberately, because full request URLs end up in diagnostic logs.

3. Know the cost before you commit

You never have to guess. POST /api/quote prices a job — including a stacked pipeline — before you run it, and it is free and unmetered. It refuses operation names it does not recognize rather than quoting a default, so a typo cannot come back as a cheap answer for an expensive call.

Pre-quote a two-step job

curl -X POST "https://api.docbutterfly.com/api/quote" \
  -H "X-API-Key: $DOCBUTTERFLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operations": ["ConvertHtmlToPdf", "WatermarkPdf"], "mode": "pipeline"}'

The answer includes tokens, the holdTokens the platform will actually reserve, your balance, and whether the job is affordable. See Usage & Billing for how reservations, refunds and the monthly allowance work.

4. Where to go next

Try it without writing code

The API Testbed runs any endpoint from the browser.

Use it from Power Automate or Logic Apps

Import the custom connector and every action is a native step — no HTTP action to configure by hand.

Chain several operations

Build a pipeline once and trigger it with one HTTPS request — see Webhooks & Integrations.

Generate documents from a template

The Template Generator turns a layout plus data into a finished document.

Read the full endpoint reference

Every operation, its parameters and its token cost, in the API Reference.

Something not behaving? Troubleshooting covers the status codes you are most likely to hit first.