API Documentation (v2)

Convert endpoint

POST /v2/convert takes a web page address, some HTML or some Markdown and gives you back a PDF, a Word (docx) file, Markdown, HTML, JSON or plain text. By default you get the answer in the same request, within 27 seconds. For slow pages and large documents you can run it in the background instead.

Send your key in the Authorization header as Bearer YOUR_API_KEY. The X-API-Key header works too. No key yet? Get a free one on your API key page: 100 documents a month, no card needed.

The full description is in the OpenAPI file. AI agents can read llms-full.txt.

What you send

Send exactly one of url, html or markdown. The body can be JSON or a form, and the same names work in the query string.

What you can choose

What you get back

The answer

A good request answers 200 with status set to success.

{
  "status": "success",
  "output": "pdf",
  "file_url": "https://storage.printfriendly.com/data-production/pdf_1760380000000_a1b2c3Letter.pdf",
  "expires_at": "2026-10-15T12:00:00.000Z",
  "size_bytes": 184233,
  "document": {
    "title": "Eclipse",
    "url": "https://en.wikipedia.org/wiki/Eclipse",
    "site": "en.wikipedia.org",
    "excerpt": "An eclipse is an astronomical event that occurs when an astronomical object is temporarily obscured...",
    "image": "https://upload.wikimedia.org/wikipedia/commons/thumb/eclipse.jpg",
    "word_count": 6120
  },
  "usage": { "used_this_period": 3, "included": 100, "plan": "free" }
}

• file_url links stay valid for 48 hours. Download the file before then.
• document describes the article. For json output it also holds the content.
• usage shows how many documents this key has used this period, and how many it includes.
• Only a successful conversion counts toward your plan, one per request, whatever the format. A failed request costs nothing.

Background jobs

Add async: true to any convert request and it is queued instead of run while you wait. You get a 202 straight away and read the result when it is ready. Use it for slow pages and large documents, or whenever your own request should not have to wait. The same input, options and outputs work, and a job counts toward your plan just like a normal request.

What you add

Start a job

The 202 answer names the job and says where to look at it. expires_at is when the job and its result are deleted, 48 hours after you start it.

{
  "status": "queued",
  "job_id": "5b1f6a52-0c0e-4d8e-9d8f-3f0a6a7d1c21",
  "status_url": "https://api.printfriendly.com/v2/jobs/5b1f6a52-0c0e-4d8e-9d8f-3f0a6a7d1c21",
  "expires_at": "2026-10-15T12:00:00.000Z"
}

Check a job

GET /v2/jobs/{id}, with the same key. A job can only be read by the key that started it. For any other key, and once the 48 hours are up, the answer is 404 with job_not_found.

queued and processing are not final: look again in a couple of seconds (the answer carries Retry-After while a job is unfinished). succeeded and failed never change. Checking has its own limit, 120 a minute on the free plan and 600 on paid plans, apart from the limit on starting work.

{
  "status": "succeeded",
  "job_id": "5b1f6a52-0c0e-4d8e-9d8f-3f0a6a7d1c21",
  "created_at": "2026-10-13T12:00:00.000Z",
  "finished_at": "2026-10-13T12:00:07.412Z",
  "result": {
    "status": "success",
    "output": "pdf",
    "file_url": "https://storage.printfriendly.com/data-production/pdf_1760380000000_a1b2c3Letter.pdf",
    "expires_at": "2026-10-15T12:00:00.000Z",
    "size_bytes": 184233,
    "document": {
      "title": "Eclipse",
      "url": "https://en.wikipedia.org/wiki/Eclipse",
      "site": "en.wikipedia.org",
      "excerpt": "An eclipse is an astronomical event that occurs when an astronomical object is temporarily obscured...",
      "image": "https://upload.wikimedia.org/wikipedia/commons/thumb/eclipse.jpg",
      "word_count": 6120
    },
    "usage": {
      "used_this_period": 3,
      "included": 100,
      "plan": "free"
    }
  }
}

{
  "status": "failed",
  "job_id": "5b1f6a52-0c0e-4d8e-9d8f-3f0a6a7d1c21",
  "created_at": "2026-10-13T12:00:00.000Z",
  "finished_at": "2026-10-13T12:00:04.118Z",
  "error": {
    "code": "fetch_failed",
    "message": "Print technology timed-out while trying to connect to this page",
    "retryable": true
  }
}

Limits and counting

• A job counts once, when it succeeds. The free plan's monthly limit and the per-minute request limit are checked when you start the job. The free limit is checked again when the job runs, so jobs queued together cannot take a free key past its month.
• A key can have 3 unfinished jobs on the free plan and 20 on paid plans. Past that, starting another answers 429 with Retry-After until one finishes. The service as a whole also limits how many jobs can wait, and answers the same way.
• A job has up to 55 seconds to convert, where a normal request has 27. If the server running a job is replaced, the job is picked up again, so it is not lost. If it still cannot finish, it fails with retryable set to true.

Webhooks

Add webhook_url and we POST the finished job to it, so you do not have to keep checking. It must be an https address on a public host. An address that points at a private or internal network is refused with 400.

• The body is JSON: the same object GET /v2/jobs/{id} returns, with status set to succeeded or failed.
• Each delivery has an X-PrintFriendly-Signature header: sha256= followed by the hex HMAC-SHA256 of the raw request body, keyed with your API key. Compute it over the bytes you received, compare in constant time, and ignore a request that does not match.
• Answer with any 2xx to confirm. Anything else, or no answer within 10 seconds, is tried again three times, after 2, 10 and 60 seconds. Redirects are not followed.
• Delivery is best effort and never delays the job: the result is saved first and stays at status_url for 48 hours. If a webhook does not arrive, check the job. A retry can arrive after a slow success, so use job_id to ignore repeats.

POST /your/webhook HTTP/1.1
Content-Type: application/json
User-Agent: PrintFriendly-Webhooks/1.0
X-PrintFriendly-Job-Id: 5b1f6a52-0c0e-4d8e-9d8f-3f0a6a7d1c21
X-PrintFriendly-Signature: sha256=0a5f0f7c3d1e9b6a2c8e4f7d1b3a5c9e0f2d4b6a8c1e3f5a7b9d0c2e4f6a8b1c

{"status":"succeeded","job_id":"5b1f6a52-0c0e-4d8e-9d8f-3f0a6a7d1c21", ... }

# 1. Start the job. The answer is 202 with a job_id.
curl -X POST https://api.printfriendly.com/v2/convert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://en.wikipedia.org/wiki/Eclipse", "output": "docx", "async": true}'

# 2. Check on it with the job_id from step 1. Repeat until status is succeeded or failed.
curl https://api.printfriendly.com/v2/jobs/5b1f6a52-0c0e-4d8e-9d8f-3f0a6a7d1c21 \
  -H "Authorization: Bearer YOUR_API_KEY"

import time
import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
start = requests.post(
    "https://api.printfriendly.com/v2/convert",
    headers=headers,
    json={"url": "https://en.wikipedia.org/wiki/Eclipse", "output": "docx", "async": True},
)
status_url = start.json()["status_url"]

while True:
    time.sleep(2)
    job = requests.get(status_url, headers=headers).json()
    if job["status"] in ("succeeded", "failed"):
        break

if job["status"] == "succeeded":
    print(job["result"]["file_url"])
else:
    print(job["error"]["code"], job["error"]["retryable"])

const headers = {
  Authorization: "Bearer YOUR_API_KEY",
  "Content-Type": "application/json",
};

const start = await fetch("https://api.printfriendly.com/v2/convert", {
  method: "POST",
  headers,
  body: JSON.stringify({
    url: "https://en.wikipedia.org/wiki/Eclipse",
    output: "docx",
    async: true,
  }),
});
const { status_url } = await start.json();

let job;
do {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  job = await (await fetch(status_url, { headers })).json();
} while (job.status === "queued" || job.status === "processing");

if (job.status === "succeeded") console.log(job.result.file_url);
else console.error(job.error.code, job.error.retryable);

import hashlib
import hmac

def is_from_printfriendly(raw_body: bytes, signature_header: str, api_key: str) -> bool:
    expected = "sha256=" + hmac.new(api_key.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

const { createHmac, timingSafeEqual } = require("node:crypto");

// rawBody is the request body exactly as it arrived (a Buffer or a string), not parsed JSON.
function isFromPrintFriendly(rawBody, signatureHeader, apiKey) {
  const expected = "sha256=" + createHmac("sha256", apiKey).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

module.exports = { isFromPrintFriendly };

Copy and paste

Replace YOUR_API_KEY with your key.

curl -X POST https://api.printfriendly.com/v2/convert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://en.wikipedia.org/wiki/Eclipse", "output": "pdf"}'

import requests

response = requests.post(
    "https://api.printfriendly.com/v2/convert",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"url": "https://en.wikipedia.org/wiki/Eclipse", "output": "pdf"},
)
print(response.json()["file_url"])

const response = await fetch("https://api.printfriendly.com/v2/convert", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://en.wikipedia.org/wiki/Eclipse",
    output: "pdf",
  }),
});
const { file_url } = await response.json();
console.log(file_url);

curl -X POST https://api.printfriendly.com/v2/convert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://en.wikipedia.org/wiki/Eclipse", "output": "markdown"}'

import requests

response = requests.post(
    "https://api.printfriendly.com/v2/convert",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"url": "https://en.wikipedia.org/wiki/Eclipse", "output": "markdown"},
)
print(response.json()["content"])

const response = await fetch("https://api.printfriendly.com/v2/convert", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://en.wikipedia.org/wiki/Eclipse",
    output: "markdown",
  }),
});
const { content } = await response.json();
console.log(content);

curl -X POST https://api.printfriendly.com/v2/convert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://en.wikipedia.org/wiki/Eclipse", "output": "json"}'

import requests

response = requests.post(
    "https://api.printfriendly.com/v2/convert",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"url": "https://en.wikipedia.org/wiki/Eclipse", "output": "json"},
)
document = response.json()["document"]
print(document["title"], document["word_count"])
print(document["content_markdown"][:500])

const response = await fetch("https://api.printfriendly.com/v2/convert", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://en.wikipedia.org/wiki/Eclipse",
    output: "json",
  }),
});
const { document } = await response.json();
console.log(document.title, document.word_count);
console.log(document.content_markdown.slice(0, 500));

curl -X POST https://api.printfriendly.com/v2/convert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"markdown": "# Notes\n\n- First point\n- Second point", "title": "Meeting notes", "output": "docx"}'

import requests

response = requests.post(
    "https://api.printfriendly.com/v2/convert",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "markdown": "# Notes\n\n- First point\n- Second point",
        "title": "Meeting notes",
        "output": "docx",
    },
)
print(response.json()["file_url"])

const response = await fetch("https://api.printfriendly.com/v2/convert", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    markdown: "# Notes\n\n- First point\n- Second point",
    title: "Meeting notes",
    output: "docx",
  }),
});
const { file_url } = await response.json();
console.log(file_url);

If something goes wrong

Failures work exactly as described under Errors below: look at error.code and error.retryable, not the message. Two things are specific to this endpoint. A bad parameter is a 400 naming it in error.errors. An html body over 50 MB is refused with 413 before it is read, and one with more than 2 MB of markup is a 400; both are html_too_large.

Limits and quotas

Free plan

• Every account can create a free key on its API key page. No credit card is needed.
• It includes 100 documents per calendar month (UTC). The count resets on the 1st.
• It is a hard cap. Past it, requests answer 402 with quota_exceeded until the month turns over or you upgrade.
• PDFs made with a free key carry the line “Made with the PrintFriendly API (printfriendly.com/api)” at the foot of every page, and HTML carries it once at the end. Markdown, JSON, text and Word files have none, and paid plans never do.
• When you subscribe to a paid plan the same key keeps working. It just stops being a free key.
• It works the other way too. You can downgrade to the free plan from your API key page at any time: the paid plan runs to the end of the period you have paid for, then the same key becomes a free key again. A paid plan that ends for any other reason lands there as well.

Paid plans

• Each plan has a monthly quota of PDF, HTML and text documents. Usage resets at the start of every billing period.
• What happens past the quota is up to you, with the overage switch on your API key page. With overage on, documents past your quota keep working and are billed at your plan's overage rate on your next invoice. See API pricing for rates. With overage off, requests stop at the quota.
• With overage on you can also set a monthly cap in dollars. Requests stop once the extra documents reach it.
• A stopped request answers 402 with quota_exceeded until the next billing period starts, or until you turn on overage, raise the cap or upgrade. error.upgrade_url links to your API key page.
• A new subscription starts with overage off, so it never bills past its quota until you turn overage on.
• We email you at 80% and 100% of your quota, and when your cap is reached, once each per billing period.
• If your plan ends while overage is on, extra documents from its last period are billed on a closing invoice.
• You can see your usage for the current period on your API key page.

What counts

• Only successful documents count. Requests that fail (an invalid key, invalid parameters, or a page we can't reach or render) are never counted, and neither are requests refused for rate limiting.
• If a request times out, the document may still finish on our side, and it counts if it does.

Rate limits, time and size

• Requests per minute, per key: 10 on the free plan, 120 on paid plans. Over the limit you get 429 with a Retry-After header.
• Requests are synchronous with a 27 second ceiling. A document that is not ready by then answers 422 with render_timeout.
• The html parameter can be up to 50 MB.

Use of the API is governed by the Acceptable Use Policy, and keys used in breach of it are revoked.