API reference

POST /v1/pdf#

HTML to PDF

Prints a whole HTML document. With data, the HTML is a template ({{ … }}, {% for %}, {% if %}) filled first.

Parameters

Idempotency-Key header · string

A key of yours (a UUID) that makes the request safe to repeat: within 24 hours the same key and body get the first result back, with nothing printed or charged twice. Another body under the same key is 422 idempotency_key_reused.

Accept header · "application/pdf" | "application/json"

application/pdf (the default): the PDF itself. application/json: the PDF's link and facts (Pdf), the file kept 24 hours.

Body

html string

The whole HTML document, with its <style>. Images and fonts by https URL or data: URI. Up to 15 MB.

url string

Instead of html: the page's public http(s) address (ports 80/443). It is fetched anonymously (redirects followed, each checked; 20 s, 15 MB) and printed from where it was found (its relative addresses resolve there).

data object

When given, html is a template filled with these values first.

filename string

The PDF's file name (else the document's <title>).

options Options

engine string

Pin the print to an engine version (GET /v1/engines): the current one, or a previous one, kept printing until three newer engines have shipped and 30 days at most. Without it, the current engine.

Needs a key with the print scope (scopes).

Responses

200

The PDF.

• X-Page-Count Pages printed (and counted to the plan).
• Content-Disposition The file's name: filename, else the document's <title>.
• X-ReflowPDF-Mark free-allowance-used when a Free account's pages without the mark are used up for the month.
• ReflowPDF-Missing-Variables The template's variables the data did not give (comma-separated, URL-encoded); printed empty.
• ReflowPDF-Missing-Glyphs The characters no font had a glyph for (UTF-8, percent-encoded): printed as empty boxes; add a font that covers them.
• ReflowPDF-Missing-Fonts The font families the document named that no face answered (each percent-encoded, comma-separated): their text took the next family of its list.
• ReflowPDF-Skipped-Resources The addresses the print went without (space-separated; as many as 2 KB holds, then +N for the rest; the JSON response lists them all).
• Idempotent-Replayed true when this is the answer of an earlier request with the same Idempotency-Key.
• ReflowPDF-Engine The engine version that printed it (GET /v1/engines).
• ReflowPDF-Scripts With options.javascript: what the document's scripts did: the scripts object of the JSON response, as percent-encoded JSON (run, errors, error_count, skipped, modules, stopped, console).

201

With Accept: application/json: the PDF's link and facts.

400

The request is not valid: the problem names the field (invalid_request); or a template that does not read: an expression, a tag or a filter it cannot parse (template_error).

401

No API key, or one not valid.

403

A claim of the Pro and Max plans (PDF/A, PDF/X, PDF/UA-2) on another plan (plan_required); a key without the scope the route asks for (insufficient_scope), or used from an address it is not kept to (ip_not_allowed).

410

The answer of an Idempotency-Key is no longer kept: a PDF or images an hour, a link 24 hours (file_expired).

413

The body is over 15 MB, the document over the print's size, or a result over the 1 GB a file stored for a link may be (result_too_large).

415

The body is not JSON.

422

Not possible for this document (a claim it cannot keep, a page it does not have), a PDF that cannot be read (invalid_pdf) or is encrypted without its password (pdf_encrypted), the layout did not settle, the Idempotency-Key was used with another request, or the page of url could not be fetched (document_unreachable: not public, not HTML, over 15 MB or 20 s, or it answered an error), or the engine named prints here no more (engine_unavailable).

429

Too many requests of this account at once, or in the last minutes, or jobs not finished (rate_limited); or the files it stores for links fill its plan's space: Free 256 MB, Pro and Max 2 GB (storage_quota).

500

Our error (internal_error): give the request_id to support.

502

The engine failed on our side (render_failed): tried again, it may print.

503

The engine is busy (engine_busy), the print took over its time limit (90 s for a request, 3 minutes for a job: render_timeout), or files cannot be stored for links right now (storage_full). See Retry-After.

curl -X POST https://api.reflowpdf.com/v1/pdf \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "html": "<!doctype html><html><head><title>Hello</title><style>@page { size: A4; margin: 20mm } h1 { font: 700 28pt Georgia }</style></head><body><h1>Hello, PDF</h1></body></html>"
}
JSON

{
  "id": "Hq8vR2cT9xKmL4pW",
  "object": "pdf",
  "url": "https://api.reflowpdf.com/v1/files/Hq8vR2cT9xKmL4pW/Hello.pdf",
  "expires_at": "2026-11-03T10:22:31.000Z",
  "filename": "Hello.pdf",
  "pages": 1,
  "bytes": 9612,
  "mark": null,
  "missing_variables": [],
  "skipped_resources": []
}

POST /v1/pdf/merge#

Merge PDFs

The parts' pages one after another in a new PDF. Each part is a PDF (stored for a link, in base64 or at an address) or a document printed first, all its pages or some (pages). Pages keep their content, links and form fields; the parts' outlines, tags and standard claims (PDF/A, PDF/UA) do not carry over — the result claims none.

Parameters

Idempotency-Key header · string

A key of yours (a UUID) that makes the request safe to repeat: within 24 hours the same key and body get the first result back, with nothing printed or charged twice. Another body under the same key is 422 idempotency_key_reused.

Accept header · "application/pdf" | "application/json"

application/pdf (the default): the PDF itself. application/json: the PDF's link and facts (Pdf), the file kept 24 hours.

Body

parts array of PdfPart required

The PDFs, in order: up to 50.

filename string

The merged PDF's file name (merged.pdf when omitted).

Needs a key with the print scope (scopes).

Responses

200

The merged PDF.

• X-Page-Count Its pages.

201

With Accept: application/json: the PDF's link and facts.

400

The request is not valid: the problem names the field (invalid_request); or a template that does not read: an expression, a tag or a filter it cannot parse (template_error).

401

No API key, or one not valid.

403

A claim of the Pro and Max plans (PDF/A, PDF/X, PDF/UA-2) on another plan (plan_required); a key without the scope the route asks for (insufficient_scope), or used from an address it is not kept to (ip_not_allowed).

404

A part names a file stored for a link that is not there, or expired (file_not_found); or a template that is not (template_not_found).

410

The answer of an Idempotency-Key is no longer kept: a PDF or images an hour, a link 24 hours (file_expired).

413

The body is over 15 MB, the document over the print's size, or a result over the 1 GB a file stored for a link may be (result_too_large).

415

The body is not JSON.

422

Not possible for this document (a claim it cannot keep, a page it does not have), a PDF that cannot be read (invalid_pdf) or is encrypted without its password (pdf_encrypted), the layout did not settle, the Idempotency-Key was used with another request, or the page of url could not be fetched (document_unreachable: not public, not HTML, over 15 MB or 20 s, or it answered an error), or the engine named prints here no more (engine_unavailable).

429

Too many requests of this account at once, or in the last minutes, or jobs not finished (rate_limited); or the files it stores for links fill its plan's space: Free 256 MB, Pro and Max 2 GB (storage_quota).

500

Our error (internal_error): give the request_id to support.

502

The engine failed on our side (render_failed): tried again, it may print.

503

The engine is busy (engine_busy), the print took over its time limit (90 s for a request, 3 minutes for a job: render_timeout), or files cannot be stored for links right now (storage_full). See Retry-After.

curl -X POST https://api.reflowpdf.com/v1/pdf/merge \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "filename": "Invoice with terms",
  "parts": [
    {
      "template_id": "invoice"
    },
    {
      "pdf_url": "https://example.com/terms.pdf",
      "pages": "1-2"
    }
  ]
}
JSON

{
  "id": "Hq8vR2cT9xKmL4pW",
  "object": "pdf",
  "url": "https://api.reflowpdf.com/v1/files/Hq8vR2cT9xKmL4pW/Invoice%20with%20terms.pdf",
  "expires_at": "2026-11-03T10:22:31.000Z",
  "filename": "Invoice with terms.pdf",
  "pages": 4,
  "bytes": 241687,
  "mark": null,
  "missing_variables": [],
  "skipped_resources": []
}

POST /v1/pdf/split#

Split a PDF

A PDF's pages by ranges (each a new file), or every every pages: their links, and a ZIP of them, stored 24 hours.

Parameters

Idempotency-Key header · string

A key of yours (a UUID) that makes the request safe to repeat: within 24 hours the same key and body get the first result back, with nothing printed or charged twice. Another body under the same key is 422 idempotency_key_reused.

Body

file string

A PDF of yours stored for a link: its id from a JSON response (24 hours).

pdf string

A PDF's bytes, in base64 (within the 15 MB of a request).

pdf_url string

A public address of a PDF, fetched (up to 100 MB, 60 s).

html string

Instead of a PDF: a document printed first, then split.

url string

Instead of html: a public page, fetched and printed.

template_id string

Instead of html: a template of the gallery or of your library, by its id.

data object

The template's data (JSON); without it, the template's own sample data.

options Options

password string

The password of an encrypted PDF.

ranges array of string

Each a new file: ["1-2", "3-"].

every integer

A new file every so many pages.

filename string

The files' base name.

Needs a key with the print scope (scopes).

Responses

201

The files.

400

The request is not valid: the problem names the field (invalid_request); or a template that does not read: an expression, a tag or a filter it cannot parse (template_error).

401

No API key, or one not valid.

403

A claim of the Pro and Max plans (PDF/A, PDF/X, PDF/UA-2) on another plan (plan_required); a key without the scope the route asks for (insufficient_scope), or used from an address it is not kept to (ip_not_allowed).

404

A part names a file stored for a link that is not there, or expired (file_not_found); or a template that is not (template_not_found).

413

The body is over 15 MB, the document over the print's size, or a result over the 1 GB a file stored for a link may be (result_too_large).

415

The body is not JSON.

422

Not possible for this document (a claim it cannot keep, a page it does not have), a PDF that cannot be read (invalid_pdf) or is encrypted without its password (pdf_encrypted), the layout did not settle, the Idempotency-Key was used with another request, or the page of url could not be fetched (document_unreachable: not public, not HTML, over 15 MB or 20 s, or it answered an error), or the engine named prints here no more (engine_unavailable).

429

Too many requests of this account at once, or in the last minutes, or jobs not finished (rate_limited); or the files it stores for links fill its plan's space: Free 256 MB, Pro and Max 2 GB (storage_quota).

500

Our error (internal_error): give the request_id to support.

503

The engine is busy (engine_busy), the print took over its time limit (90 s for a request, 3 minutes for a job: render_timeout), or files cannot be stored for links right now (storage_full). See Retry-After.

curl -X POST https://api.reflowpdf.com/v1/pdf/split \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "file": "Hq8vR2cT9xKmL4pW",
  "ranges": [
    "1",
    "2-"
  ]
}
JSON

{
  "id": "spl_N3wq8sHkT2xV9mRp4LcB1a",
  "object": "split",
  "files": [
    {
      "id": "Hq8vR2cT9xKmL4pW",
      "pages": "1",
      "page_count": 1,
      "url": "https://api.reflowpdf.com/v1/files/Hq8vR2cT9xKmL4pW/report-pages-1.pdf",
      "filename": "report-pages-1.pdf",
      "bytes": 48213
    }
  ],
  "archive": null,
  "expires_at": "2026-11-03T10:22:31.000Z"
}

POST /v1/pdf/compress#

Compress a PDF

The PDF written again losslessly: its streams compressed anew, its objects in object streams, resources no page uses removed. It is never larger than it was, unless linearized for fast web view (its hint tables, a few KB). Its images stay as they are.

Parameters

Idempotency-Key header · string

A key of yours (a UUID) that makes the request safe to repeat: within 24 hours the same key and body get the first result back, with nothing printed or charged twice. Another body under the same key is 422 idempotency_key_reused.

Accept header · "application/pdf" | "application/json"

application/pdf (the default): the PDF itself. application/json: the PDF's link and facts (Pdf), the file kept 24 hours.

Body

file string

A PDF of yours stored for a link: its id from a JSON response (24 hours).

pdf string

A PDF's bytes, in base64 (within the 15 MB of a request).

pdf_url string

A public address of a PDF, fetched (up to 100 MB, 60 s).

html string

Instead of a PDF: a document printed first, then compressed.

url string

Instead of html: a public page, fetched and printed.

template_id string

Instead of html: a template of the gallery or of your library, by its id.

data object

The template's data (JSON); without it, the template's own sample data.

options Options

password string

The password of an encrypted PDF.

linearize boolean

Fast web view: its first page shows before the rest has arrived. Default false.

filename string

The compressed file's name.

Needs a key with the print scope (scopes).

Responses

200

The compressed PDF.

• X-Page-Count Its pages.
• ReflowPDF-Bytes-Before Its size before.

201

With Accept: application/json: the PDF's link and facts.

400

The request is not valid: the problem names the field (invalid_request); or a template that does not read: an expression, a tag or a filter it cannot parse (template_error).

401

No API key, or one not valid.

403

A claim of the Pro and Max plans (PDF/A, PDF/X, PDF/UA-2) on another plan (plan_required); a key without the scope the route asks for (insufficient_scope), or used from an address it is not kept to (ip_not_allowed).

404

A part names a file stored for a link that is not there, or expired (file_not_found); or a template that is not (template_not_found).

410

The answer of an Idempotency-Key is no longer kept: a PDF or images an hour, a link 24 hours (file_expired).

413

The body is over 15 MB, the document over the print's size, or a result over the 1 GB a file stored for a link may be (result_too_large).

415

The body is not JSON.

422

Not possible for this document (a claim it cannot keep, a page it does not have), a PDF that cannot be read (invalid_pdf) or is encrypted without its password (pdf_encrypted), the layout did not settle, the Idempotency-Key was used with another request, or the page of url could not be fetched (document_unreachable: not public, not HTML, over 15 MB or 20 s, or it answered an error), or the engine named prints here no more (engine_unavailable).

429

Too many requests of this account at once, or in the last minutes, or jobs not finished (rate_limited); or the files it stores for links fill its plan's space: Free 256 MB, Pro and Max 2 GB (storage_quota).

500

Our error (internal_error): give the request_id to support.

502

The engine failed on our side (render_failed): tried again, it may print.

503

The engine is busy (engine_busy), the print took over its time limit (90 s for a request, 3 minutes for a job: render_timeout), or files cannot be stored for links right now (storage_full). See Retry-After.

curl -X POST https://api.reflowpdf.com/v1/pdf/compress \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "pdf_url": "https://example.com/report.pdf",
  "linearize": true
}
JSON

{
  "id": "Hq8vR2cT9xKmL4pW",
  "object": "pdf",
  "url": "https://api.reflowpdf.com/v1/files/Hq8vR2cT9xKmL4pW/report.pdf",
  "expires_at": "2026-11-03T10:22:31.000Z",
  "filename": "report.pdf",
  "pages": 12,
  "bytes": 812044,
  "mark": null,
  "missing_variables": [],
  "skipped_resources": [],
  "bytes_before": 1290311
}

GET /v1/templates#

List templates

The gallery's templates and your account's own (made in the editor and saved as templates), newest first among yours.

Parameters

q query · string

Words in the name, description or category.

category query · "Finance" | "Sales" | "Business" | "HR & Legal" | "Government" | "Personal" | "Logistics" | "Health" | "Events" | "Marketing" | "Showcase"

Only this category (gallery).

source query · "gallery" | "library"

gallery or library (yours) only.

limit query · integer

Templates per page.

starting_after query · string

The id of the last template of the previous page.

Needs a key with the templates scope (scopes).

Responses

200

A page of templates.

400

The request is not valid: the problem names the field (invalid_request); or a template that does not read: an expression, a tag or a filter it cannot parse (template_error).

401

No API key, or one not valid.

403

A claim of the Pro and Max plans (PDF/A, PDF/X, PDF/UA-2) on another plan (plan_required); a key without the scope the route asks for (insufficient_scope), or used from an address it is not kept to (ip_not_allowed).

429

Too many requests of this account at once, or in the last minutes, or jobs not finished (rate_limited); or the files it stores for links fill its plan's space: Free 256 MB, Pro and Max 2 GB (storage_quota).

curl https://api.reflowpdf.com/v1/templates \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "invoice",
      "object": "template",
      "source": "gallery",
      "name": "B2B Invoice",
      "description": "Professional B2B invoice with line items, VAT breakdown, totals, payment terms and bank details.",
      "category": "Finance",
      "paper": {
        "size": "A4",
        "orientation": "portrait"
      }
    },
    {
      "id": "lib_Kp3xQ9mT2vLa8RcW",
      "object": "template",
      "source": "library",
      "name": "Our invoice",
      "description": null,
      "category": null,
      "updated_at": "2026-10-30T14:02:11.000Z"
    }
  ],
  "has_more": false
}

GET /v1/templates/{id}#

Get a template

A template's source, its sample data and the JSON Schema of its data: the shape to fill.

Parameters

id path · string required

A gallery template's id (invoice) or yours (lib_…).

Needs a key with the templates scope (scopes).

Responses

200

The template.

401

No API key, or one not valid.

403

A claim of the Pro and Max plans (PDF/A, PDF/X, PDF/UA-2) on another plan (plan_required); a key without the scope the route asks for (insufficient_scope), or used from an address it is not kept to (ip_not_allowed).

404

No such template (template_not_found).

429

Too many requests of this account at once, or in the last minutes, or jobs not finished (rate_limited); or the files it stores for links fill its plan's space: Free 256 MB, Pro and Max 2 GB (storage_quota).

curl https://api.reflowpdf.com/v1/templates/invoice \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY"

{
  "id": "donation-receipt",
  "object": "template",
  "source": "gallery",
  "name": "Donation Receipt",
  "description": "Charitable tax-deductible donation receipt with donor and statement.",
  "category": "Finance",
  "paper": {
    "size": "A4",
    "orientation": "portrait"
  },
  "fillable": true,
  "html": "<!doctype html>\n<html lang=\"en\">…<h1>{{ org }}</h1>…",
  "sample_data": {
    "org": "Riverbank Children’s Foundation",
    "receiptNo": "DR-2027-00418",
    "date": "2027-03-30",
    "donor": "Aoife Donnelly",
    "amount": "250.00",
    "currency": "EUR"
  },
  "data_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "org": {
        "type": "string"
      },
      "receiptNo": {
        "type": "string"
      },
      "date": {
        "type": "string",
        "format": "date"
      },
      "donor": {
        "type": "string"
      },
      "amount": {
        "type": "string"
      },
      "currency": {
        "type": "string"
      }
    },
    "required": [
      "org",
      "receiptNo",
      "date",
      "donor",
      "amount",
      "currency"
    ]
  }
}

POST /v1/templates/{id}/pdf#

Fill a template and print it

Fills the template with data (its sample data when none is given) and prints it on its paper. A template of yours designed on the page (not in Code) takes no data: it prints as designed.

Parameters

id path · string required

The template's id: a gallery template's name, or lib_… for one of your library.

Idempotency-Key header · string

A key of yours (a UUID) that makes the request safe to repeat: within 24 hours the same key and body get the first result back, with nothing printed or charged twice. Another body under the same key is 422 idempotency_key_reused.

Accept header · "application/pdf" | "application/json"

application/pdf (the default): the PDF itself. application/json: the PDF's link and facts (Pdf), the file kept 24 hours.

Body

data object

The values the template reads, in the shape of data_schema (its sample data when omitted).

filename string

The file's name: yours, else the document's <title>, else document.

options Options

engine string

Pin the print to an engine version (GET /v1/engines): the current one, or a previous one, kept printing until three newer engines have shipped and 30 days at most. Without it, the current engine.

Needs a key with the print scope (scopes).

Responses

200

The PDF.

• X-Page-Count Pages printed (and counted to the plan).
• Content-Disposition The file's name: filename, else the document's <title>.
• X-ReflowPDF-Mark free-allowance-used when a Free account's pages without the mark are used up for the month.
• ReflowPDF-Missing-Variables The template's variables the data did not give (comma-separated, URL-encoded); printed empty.
• ReflowPDF-Missing-Glyphs The characters no font had a glyph for (UTF-8, percent-encoded): printed as empty boxes; add a font that covers them.
• ReflowPDF-Missing-Fonts The font families the document named that no face answered (each percent-encoded, comma-separated): their text took the next family of its list.
• ReflowPDF-Skipped-Resources The addresses the print went without (space-separated; as many as 2 KB holds, then +N for the rest; the JSON response lists them all).
• Idempotent-Replayed true when this is the answer of an earlier request with the same Idempotency-Key.
• ReflowPDF-Engine The engine version that printed it (GET /v1/engines).
• ReflowPDF-Scripts With options.javascript: what the document's scripts did: the scripts object of the JSON response, as percent-encoded JSON (run, errors, error_count, skipped, modules, stopped, console).

201

With Accept: application/json: the PDF's link and facts.

400

The request is not valid: the problem names the field (invalid_request); or a template that does not read: an expression, a tag or a filter it cannot parse (template_error).

401

No API key, or one not valid.

403

A claim of the Pro and Max plans (PDF/A, PDF/X, PDF/UA-2) on another plan (plan_required); a key without the scope the route asks for (insufficient_scope), or used from an address it is not kept to (ip_not_allowed).

404

No such template (template_not_found).

410

The answer of an Idempotency-Key is no longer kept: a PDF or images an hour, a link 24 hours (file_expired).

413

The body is over 15 MB, the document over the print's size, or a result over the 1 GB a file stored for a link may be (result_too_large).

415

The body is not JSON.

422

Not possible for this document (a claim it cannot keep, a page it does not have), a PDF that cannot be read (invalid_pdf) or is encrypted without its password (pdf_encrypted), the layout did not settle, the Idempotency-Key was used with another request, or the page of url could not be fetched (document_unreachable: not public, not HTML, over 15 MB or 20 s, or it answered an error), or the engine named prints here no more (engine_unavailable).

429

Too many requests of this account at once, or in the last minutes, or jobs not finished (rate_limited); or the files it stores for links fill its plan's space: Free 256 MB, Pro and Max 2 GB (storage_quota).

500

Our error (internal_error): give the request_id to support.

502

The engine failed on our side (render_failed): tried again, it may print.

503

The engine is busy (engine_busy), the print took over its time limit (90 s for a request, 3 minutes for a job: render_timeout), or files cannot be stored for links right now (storage_full). See Retry-After.

curl -X POST https://api.reflowpdf.com/v1/templates/invoice/pdf \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "filename": "INV-1042"
}
JSON

{
  "id": "Hq8vR2cT9xKmL4pW",
  "object": "pdf",
  "url": "https://api.reflowpdf.com/v1/files/Hq8vR2cT9xKmL4pW/INV-1042.pdf",
  "expires_at": "2026-11-03T10:22:31.000Z",
  "filename": "INV-1042.pdf",
  "pages": 2,
  "bytes": 184213,
  "mark": null,
  "missing_variables": [],
  "skipped_resources": []
}

POST /v1/images#

HTML to page images

The document printed, its pages as images made from the PDF itself, on white paper. One page returns the image; several return a ZIP (page-001.png, …); with Accept: application/json, their links (24 hours). Pages count to your plan as the images delivered.

Parameters

Idempotency-Key header · string

A key of yours (a UUID) that makes the request safe to repeat: within 24 hours the same key and body get the first result back, with nothing printed or charged twice. Another body under the same key is 422 idempotency_key_reused.

Accept header · string

application/json: links to the images instead of their bytes.

Body

html string

The whole HTML document.

url string

Instead of html: the page's public http(s) address (ports 80/443). It is fetched anonymously (redirects followed, each checked; 20 s, 15 MB) and printed from where it was found (its relative addresses resolve there).

data object

When given, html is a template filled with these values first.

filename string

The images' base name (else the document's <title>).

options Options

engine string

Pin the print to an engine version (GET /v1/engines): the current one, or a previous one, kept printing until three newer engines have shipped and 30 days at most. Without it, the current engine.

format "png" | "webp"

Both lossless; WebP is usually smaller. Default "png".

pages array of integer | string

The pages, [1, 3] or "1-3,5"; every page when omitted (up to 200).

dpi number

Pixels per inch (72 is one per point). Default 150.

Needs a key with the print scope (scopes).

Responses

200

One page: the image. Several: a ZIP of them (page-001.png, …).

• X-Page-Count Images delivered (and counted to the plan).
• X-Document-Pages The pages of the document.
• X-ReflowPDF-Mark free-allowance-used when a Free account's pages without the mark are used up for the month.
• ReflowPDF-Missing-Variables The template's variables the data did not give (comma-separated, URL-encoded); printed empty.
• ReflowPDF-Missing-Glyphs The characters no font had a glyph for (UTF-8, percent-encoded): printed as empty boxes; add a font that covers them.
• ReflowPDF-Missing-Fonts The font families the document named that no face answered (each percent-encoded, comma-separated): their text took the next family of its list.
• ReflowPDF-Skipped-Resources The addresses the print went without (space-separated; as many as 2 KB holds, then +N for the rest; the JSON response lists them all).
• Idempotent-Replayed true when this is the answer of an earlier request with the same Idempotency-Key.
• ReflowPDF-Engine The engine version that printed it (GET /v1/engines).
• ReflowPDF-Scripts With options.javascript: what the document's scripts did: the scripts object of the JSON response, as percent-encoded JSON (run, errors, error_count, skipped, modules, stopped, console).

201

With Accept: application/json: the images' links.

400

The request is not valid: the problem names the field (invalid_request); or a template that does not read: an expression, a tag or a filter it cannot parse (template_error).

401

No API key, or one not valid.

403

A claim of the Pro and Max plans (PDF/A, PDF/X, PDF/UA-2) on another plan (plan_required); a key without the scope the route asks for (insufficient_scope), or used from an address it is not kept to (ip_not_allowed).

410

The answer of an Idempotency-Key is no longer kept: a PDF or images an hour, a link 24 hours (file_expired).

413

The body is over 15 MB, the document over the print's size, or a result over the 1 GB a file stored for a link may be (result_too_large).

415

The body is not JSON.

422

Not possible for this document (a claim it cannot keep, a page it does not have), a PDF that cannot be read (invalid_pdf) or is encrypted without its password (pdf_encrypted), the layout did not settle, the Idempotency-Key was used with another request, or the page of url could not be fetched (document_unreachable: not public, not HTML, over 15 MB or 20 s, or it answered an error), or the engine named prints here no more (engine_unavailable).

429

Too many requests of this account at once, or in the last minutes, or jobs not finished (rate_limited); or the files it stores for links fill its plan's space: Free 256 MB, Pro and Max 2 GB (storage_quota).

500

Our error (internal_error): give the request_id to support.

502

The engine failed on our side (render_failed): tried again, it may print.

503

The engine is busy (engine_busy), the print took over its time limit (90 s for a request, 3 minutes for a job: render_timeout), or files cannot be stored for links right now (storage_full). See Retry-After.

curl -X POST https://api.reflowpdf.com/v1/images \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "html": "<h1>Hello</h1>",
  "format": "png",
  "pages": [
    1
  ],
  "dpi": 150
}
JSON

{
  "id": "img_9Qm2xT8vLp4rWs1dYbZaKa",
  "object": "images",
  "format": "png",
  "dpi": 150,
  "document_pages": 1,
  "images": [
    {
      "page": 1,
      "url": "https://api.reflowpdf.com/v1/files/Hq8vR2cT9xKmL4pW/document-page-1.png",
      "filename": "document-page-1.png",
      "width": 1241,
      "height": 1754,
      "bytes": 21877
    }
  ],
  "archive": null,
  "expires_at": "2026-11-03T10:22:31.000Z",
  "mark": null,
  "missing_variables": [],
  "skipped_resources": []
}

POST /v1/templates/{id}/images#

Fill a template, its pages as images

Fills the template with data (its sample data when none is given) and returns its pages as images, as POST /v1/images does for HTML.

Parameters

id path · string required

The template's id: a gallery template's name, or lib_… for one of your library.

Idempotency-Key header · string

A key of yours (a UUID) that makes the request safe to repeat: within 24 hours the same key and body get the first result back, with nothing printed or charged twice. Another body under the same key is 422 idempotency_key_reused.

Body

data object

The template's data (JSON); without it, the template's own sample data.

filename string

The file's name: yours, else the document's <title>, else document.

options Options

engine string

Pin the print to an engine version (GET /v1/engines): the current one, or a previous one, kept printing until three newer engines have shipped and 30 days at most. Without it, the current engine.

format "png" | "webp"

png (default) or webp, lossless. Default "png".

pages array of integer | string

Pages to draw: [1, 3] or "1-3,5"; all when left out.

dpi number

Pixels per inch, 18 to 600 (150 by default; 72 is one pixel per point). Default 150.

Needs a key with the print scope (scopes).

Responses

200

One page: the image. Several: a ZIP of them (page-001.png, …).

• X-Page-Count Images delivered (and counted to the plan).
• X-Document-Pages The pages of the document.
• X-ReflowPDF-Mark free-allowance-used when a Free account's pages without the mark are used up for the month.
• ReflowPDF-Missing-Variables The template's variables the data did not give (comma-separated, URL-encoded); printed empty.
• ReflowPDF-Missing-Glyphs The characters no font had a glyph for (UTF-8, percent-encoded): printed as empty boxes; add a font that covers them.
• ReflowPDF-Missing-Fonts The font families the document named that no face answered (each percent-encoded, comma-separated): their text took the next family of its list.
• ReflowPDF-Skipped-Resources The addresses the print went without (space-separated; as many as 2 KB holds, then +N for the rest; the JSON response lists them all).
• Idempotent-Replayed true when this is the answer of an earlier request with the same Idempotency-Key.
• ReflowPDF-Engine The engine version that printed it (GET /v1/engines).
• ReflowPDF-Scripts With options.javascript: what the document's scripts did: the scripts object of the JSON response, as percent-encoded JSON (run, errors, error_count, skipped, modules, stopped, console).

201

With Accept: application/json: the images' links.

400

The request is not valid: the problem names the field (invalid_request); or a template that does not read: an expression, a tag or a filter it cannot parse (template_error).

401

No API key, or one not valid.

403

A claim of the Pro and Max plans (PDF/A, PDF/X, PDF/UA-2) on another plan (plan_required); a key without the scope the route asks for (insufficient_scope), or used from an address it is not kept to (ip_not_allowed).

404

No such template (template_not_found).

410

The answer of an Idempotency-Key is no longer kept: a PDF or images an hour, a link 24 hours (file_expired).

413

The body is over 15 MB, the document over the print's size, or a result over the 1 GB a file stored for a link may be (result_too_large).

415

The body is not JSON.

422

Not possible for this document (a claim it cannot keep, a page it does not have), a PDF that cannot be read (invalid_pdf) or is encrypted without its password (pdf_encrypted), the layout did not settle, the Idempotency-Key was used with another request, or the page of url could not be fetched (document_unreachable: not public, not HTML, over 15 MB or 20 s, or it answered an error), or the engine named prints here no more (engine_unavailable).

429

Too many requests of this account at once, or in the last minutes, or jobs not finished (rate_limited); or the files it stores for links fill its plan's space: Free 256 MB, Pro and Max 2 GB (storage_quota).

500

Our error (internal_error): give the request_id to support.

502

The engine failed on our side (render_failed): tried again, it may print.

503

The engine is busy (engine_busy), the print took over its time limit (90 s for a request, 3 minutes for a job: render_timeout), or files cannot be stored for links right now (storage_full). See Retry-After.

curl -X POST https://api.reflowpdf.com/v1/templates/invoice/images \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "pages": "1",
  "dpi": 150
}
JSON

{
  "id": "img_9Qm2xT8vLp4rWs1dYbZaKa",
  "object": "images",
  "format": "png",
  "dpi": 150,
  "document_pages": 3,
  "images": [
    {
      "page": 1,
      "url": "https://api.reflowpdf.com/v1/files/Hq8vR2cT9xKmL4pW/Invoice%20INV-1042-page-1.png",
      "filename": "Invoice INV-1042-page-1.png",
      "width": 1241,
      "height": 1754,
      "bytes": 182344
    }
  ],
  "archive": null,
  "expires_at": "2026-11-03T10:22:31.000Z",
  "mark": null,
  "missing_variables": [],
  "skipped_resources": []
}

POST /v1/layout#

Where everything lands

The document printed, and where everything landed: every page's box, and every element with an id on each page it is drawn on (a table split across pages is on each). Build an index, place a stamp, check that a block fits, from the engine's own placement. Counted as the print.

Parameters

Idempotency-Key header · string

A key of yours (a UUID) that makes the request safe to repeat: within 24 hours the same key and body get the first result back, with nothing printed or charged twice. Another body under the same key is 422 idempotency_key_reused.

Body

html string

A whole HTML document, its CSS inline or linked.

url string

Instead of html: the page's public http(s) address (ports 80/443). It is fetched anonymously (redirects followed, each checked; 20 s, 15 MB) and printed from where it was found (its relative addresses resolve there).

data object

The template's data (JSON); without it, the template's own sample data.

options Options

engine string

Pin the print to an engine version (GET /v1/engines): the current one, or a previous one, kept printing until three newer engines have shipped and 30 days at most. Without it, the current engine.

Needs a key with the print scope (scopes).

Responses

200

The layout.

400

The request is not valid: the problem names the field (invalid_request); or a template that does not read: an expression, a tag or a filter it cannot parse (template_error).

401

No API key, or one not valid.

403

A claim of the Pro and Max plans (PDF/A, PDF/X, PDF/UA-2) on another plan (plan_required); a key without the scope the route asks for (insufficient_scope), or used from an address it is not kept to (ip_not_allowed).

413

The body is over 15 MB, the document over the print's size, or a result over the 1 GB a file stored for a link may be (result_too_large).

415

The body is not JSON.

422

Not possible for this document (a claim it cannot keep, a page it does not have), a PDF that cannot be read (invalid_pdf) or is encrypted without its password (pdf_encrypted), the layout did not settle, the Idempotency-Key was used with another request, or the page of url could not be fetched (document_unreachable: not public, not HTML, over 15 MB or 20 s, or it answered an error), or the engine named prints here no more (engine_unavailable).

429

Too many requests of this account at once, or in the last minutes, or jobs not finished (rate_limited); or the files it stores for links fill its plan's space: Free 256 MB, Pro and Max 2 GB (storage_quota).

500

Our error (internal_error): give the request_id to support.

502

The engine failed on our side (render_failed): tried again, it may print.

503

The engine is busy (engine_busy), the print took over its time limit (90 s for a request, 3 minutes for a job: render_timeout), or files cannot be stored for links right now (storage_full). See Retry-After.

curl -X POST https://api.reflowpdf.com/v1/layout \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "html": "<h1 id=\"intro\">Intro</h1><p id=\"totals\">…</p>"
}
JSON

{
  "object": "layout",
  "unit": "pt",
  "document_pages": 2,
  "pages": [
    {
      "number": 1,
      "width": 595.28,
      "height": 841.89
    },
    {
      "number": 2,
      "width": 595.28,
      "height": 841.89
    }
  ],
  "elements": [
    {
      "id": "totals",
      "page": 2,
      "x": 56.69,
      "y": 120.5,
      "width": 481.89,
      "height": 64
    }
  ],
  "missing_variables": [],
  "skipped_resources": []
}

POST /v1/templates/{id}/layout#

Fill a template, where everything lands

Fills the template with data (its sample data when none is given), prints it, and returns where everything landed, as POST /v1/layout does for HTML.

Parameters

id path · string required

The template's id: a gallery template's name, or lib_… for one of your library.

Idempotency-Key header · string

A key of yours (a UUID) that makes the request safe to repeat: within 24 hours the same key and body get the first result back, with nothing printed or charged twice. Another body under the same key is 422 idempotency_key_reused.

Body

data object

The template's data (JSON); without it, the template's own sample data.

options Options

engine string

Pin the print to an engine version (GET /v1/engines): the current one, or a previous one, kept printing until three newer engines have shipped and 30 days at most. Without it, the current engine.

Needs a key with the print scope (scopes).

Responses

200

The layout.

400

The request is not valid: the problem names the field (invalid_request); or a template that does not read: an expression, a tag or a filter it cannot parse (template_error).

401

No API key, or one not valid.

403

A claim of the Pro and Max plans (PDF/A, PDF/X, PDF/UA-2) on another plan (plan_required); a key without the scope the route asks for (insufficient_scope), or used from an address it is not kept to (ip_not_allowed).

404

No such template (template_not_found).

413

The body is over 15 MB, the document over the print's size, or a result over the 1 GB a file stored for a link may be (result_too_large).

422

Not possible for this document (a claim it cannot keep, a page it does not have), a PDF that cannot be read (invalid_pdf) or is encrypted without its password (pdf_encrypted), the layout did not settle, the Idempotency-Key was used with another request, or the page of url could not be fetched (document_unreachable: not public, not HTML, over 15 MB or 20 s, or it answered an error), or the engine named prints here no more (engine_unavailable).

429

Too many requests of this account at once, or in the last minutes, or jobs not finished (rate_limited); or the files it stores for links fill its plan's space: Free 256 MB, Pro and Max 2 GB (storage_quota).

503

The engine is busy (engine_busy), the print took over its time limit (90 s for a request, 3 minutes for a job: render_timeout), or files cannot be stored for links right now (storage_full). See Retry-After.

curl -X POST https://api.reflowpdf.com/v1/templates/invoice/layout \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY"

{
  "object": "layout",
  "unit": "pt",
  "document_pages": 2,
  "pages": [
    {
      "number": 1,
      "width": 595.28,
      "height": 841.89
    },
    {
      "number": 2,
      "width": 595.28,
      "height": 841.89
    }
  ],
  "elements": [
    {
      "id": "totals",
      "page": 2,
      "x": 56.69,
      "y": 120.5,
      "width": 481.89,
      "height": 64
    }
  ],
  "missing_variables": [],
  "skipped_resources": []
}

GET /v1/output-intents#

List print conditions

The print conditions PDF/X can claim here (options.pdf_x.output_intent). Your own printer's profile goes with the request instead (options.pdf_x.profile).

Needs a key with the print scope (scopes).

Responses

200

The print conditions.

401

No API key, or one not valid.

403

A claim of the Pro and Max plans (PDF/A, PDF/X, PDF/UA-2) on another plan (plan_required); a key without the scope the route asks for (insufficient_scope), or used from an address it is not kept to (ip_not_allowed).

curl https://api.reflowpdf.com/v1/output-intents \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "FOGRA39",
      "object": "output_intent",
      "info": "ISO Coated v2 (ECI)",
      "color_space": "CMYK"
    }
  ],
  "has_more": true
}

GET /v1/output-intents/{id}/profile#

Download a print condition's profile

The ICC profile of a print condition, as its publisher made it (ETag: its SHA-256), for an API key or a licensed @reflowpdf/engine (its license's token), from any page (CORS): the engine fetches the one a document names.

Parameters

id path · string required

A print condition, as GET /v1/output-intents lists it: FOGRA39.

An API key with the print scope, or a licensed engine's token.

Responses

200

The profile.

401

Neither an API key nor a license's token.

404

No such print condition.

curl https://api.reflowpdf.com/v1/output-intents/FOGRA39/profile \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY" \
  -o FOGRA39.icc

GET /v1/fonts/{family}#

A family of the font catalogue

ReflowPDF's catalogue, the Google Fonts the API and the editor print with, for a licensed @reflowpdf/engine or an API key: a family's faces, each with its header (its OpenType header tables, cmap and hmtx, as a small sfnt) and where its bytes are. The engine asks for the families its document names that no face of its own answers, and fetches the faces its text draws with.

Parameters

family path · string required

A family of the catalogue, as font-family names it: Inter, Noto Sans JP.

An API key with the print scope, or a licensed engine's token.

Responses

200

The family.

401

Neither an API key nor a license's token.

404

No such family in the catalogue.

curl https://api.reflowpdf.com/v1/fonts/Inter \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY"

{
  "object": "font_family",
  "family": "string",
  "header_format": 1,
  "faces": [
    {
      "id": "string",
      "weight": 1,
      "style": "normal",
      "sha256": "string",
      "bytes": 1,
      "header": "string",
      "url": "https://api.reflowpdf.com/v1/files/…"
    }
  ]
}

GET /v1/fonts/files/{id}#

A face of the font catalogue

A face's bytes (TrueType or WOFF2, ETag: its SHA-256), as its foundry publishes it; its licence (SIL OFL 1.1, Apache 2.0 or the Ubuntu Font Licence) is in its own name table.

Parameters

id path · string required

A face's id, from its family's faces.

An API key with the print scope, or a licensed engine's token.

Responses

200

The face.

401

Neither an API key nor a license's token.

404

No such face.

curl https://api.reflowpdf.com/v1/fonts/files/aff10562c603409a49b7ef65 \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY" \
  -o font.woff2

POST /v1/jobs#

Print asynchronously

The same print as POST /v1/pdf or POST /v1/templates/{id}/pdf, done in the background: answers 202 at once; poll GET /v1/jobs/{id} or receive the job.succeeded / job.failed webhook.

Parameters

Idempotency-Key header · string

A key of yours (a UUID) that makes the request safe to repeat: within 24 hours the same key and body get the first result back, with nothing printed or charged twice. Another body under the same key is 422 idempotency_key_reused.

Body

html string

The document to print (or url, or template_id).

url string

Instead of html: the page's public http(s) address (ports 80/443). It is fetched anonymously (redirects followed, each checked; 20 s, 15 MB) and printed from where it was found (its relative addresses resolve there).

template_id string

Instead of html: a template of the gallery or of your library, by its id.

data object

The template's data (JSON); without it, the template's own sample data.

filename string

The file's name: yours, else the document's <title>, else document.

options Options

engine string

Pin the print to an engine version (GET /v1/engines): the current one, or a previous one, kept printing until three newer engines have shipped and 30 days at most. Without it, the current engine.

webhook_url string

An https URL that receives job.succeeded / job.failed.

metadata object

Your own keys, returned with the job and its webhook.

upload object

Into your own storage: the job PUTs its file to this signed address once printed: an S3 presigned URL, a Google Cloud Storage signed URL, an Azure Blob SAS, R2, any https endpoint that takes a PUT. No credential of your storage is given to us.

output object

What the job delivers: a PDF (the default), its pages as images, or the layout.

Needs a key with the print scope (scopes).

Responses

202

The job, queued.

• Location The job's address.

400

The request is not valid: the problem names the field (invalid_request); or a template that does not read: an expression, a tag or a filter it cannot parse (template_error).

401

No API key, or one not valid.

403

A claim of the Pro and Max plans (PDF/A, PDF/X, PDF/UA-2) on another plan (plan_required); a key without the scope the route asks for (insufficient_scope), or used from an address it is not kept to (ip_not_allowed).

404

No such template (template_not_found).

409

A request with this Idempotency-Key is still being done.

415

The body is not JSON.

422

Not possible for this document (a claim it cannot keep, a page it does not have), a PDF that cannot be read (invalid_pdf) or is encrypted without its password (pdf_encrypted), the layout did not settle, the Idempotency-Key was used with another request, or the page of url could not be fetched (document_unreachable: not public, not HTML, over 15 MB or 20 s, or it answered an error), or the engine named prints here no more (engine_unavailable).

429

Too many requests of this account at once, or in the last minutes, or jobs not finished (rate_limited); or the files it stores for links fill its plan's space: Free 256 MB, Pro and Max 2 GB (storage_quota).

curl -X POST https://api.reflowpdf.com/v1/jobs \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "template_id": "invoice",
  "webhook_url": "https://example.com/hooks/reflowpdf",
  "metadata": {
    "order": "42"
  }
}
JSON

{
  "id": "job_Qm9xT2nV8cLp4rWs1dYbZa",
  "object": "job",
  "status": "queued",
  "created_at": "2026-11-02T10:22:30.114Z",
  "started_at": null,
  "finished_at": null,
  "template_id": "invoice",
  "webhook_url": "https://example.com/hooks/reflowpdf",
  "metadata": {
    "order": "42"
  },
  "result": null,
  "error": null
}

GET /v1/jobs#

List jobs

The account's jobs of the last 24 hours, newest first.

Parameters

status query · "queued" | "running" | "succeeded" | "failed"

Only the jobs in this state.

limit query · integer

How many to a page (1–100).

starting_after query · string

The last job id of the previous page.

Needs a key with the print scope (scopes).

Responses

200

A page of jobs.

400

The request is not valid: the problem names the field (invalid_request); or a template that does not read: an expression, a tag or a filter it cannot parse (template_error).

401

No API key, or one not valid.

403

A claim of the Pro and Max plans (PDF/A, PDF/X, PDF/UA-2) on another plan (plan_required); a key without the scope the route asks for (insufficient_scope), or used from an address it is not kept to (ip_not_allowed).

curl https://api.reflowpdf.com/v1/jobs \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "job_Qm9xT2nV8cLp4rWs1dYbZa",
      "object": "job",
      "status": "succeeded",
      "created_at": "2026-11-02T10:22:30.114Z",
      "started_at": "2026-11-02T10:22:30.120Z",
      "finished_at": "2026-11-02T10:22:31.402Z",
      "template_id": "invoice",
      "webhook_url": "https://example.com/hooks/reflowpdf",
      "metadata": {
        "order": "42"
      },
      "result": {
        "id": "Hq8vR2cT9xKmL4pW",
        "object": "pdf",
        "url": "https://api.reflowpdf.com/v1/files/Hq8vR2cT9xKmL4pW/Invoice%20INV-1042.pdf",
        "expires_at": "2026-11-03T10:22:31.000Z",
        "filename": "Invoice INV-1042.pdf",
        "pages": 2,
        "bytes": 184213,
        "mark": null,
        "missing_variables": [],
        "skipped_resources": []
      },
      "error": null
    }
  ],
  "has_more": true
}

GET /v1/jobs/{id}#

Get a job

A job of this account from the last 24 hours: its status, and when it is done its result (the PDF's link and facts, the images or the layout) or its error.

Parameters

id path · string required

The job's id (job_…).

Needs a key with the print scope (scopes).

Responses

200

The job.

401

No API key, or one not valid.

403

A claim of the Pro and Max plans (PDF/A, PDF/X, PDF/UA-2) on another plan (plan_required); a key without the scope the route asks for (insufficient_scope), or used from an address it is not kept to (ip_not_allowed).

404

No such job in this account, or it is over 24 hours old.

curl https://api.reflowpdf.com/v1/jobs/job_Qm9xT2nV8cLp4rWs1dYbZa \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY"

{
  "id": "job_Qm9xT2nV8cLp4rWs1dYbZa",
  "object": "job",
  "status": "succeeded",
  "created_at": "2026-11-02T10:22:30.114Z",
  "started_at": "2026-11-02T10:22:30.120Z",
  "finished_at": "2026-11-02T10:22:31.402Z",
  "template_id": "invoice",
  "webhook_url": "https://example.com/hooks/reflowpdf",
  "metadata": {
    "order": "42"
  },
  "result": {
    "id": "Hq8vR2cT9xKmL4pW",
    "object": "pdf",
    "url": "https://api.reflowpdf.com/v1/files/Hq8vR2cT9xKmL4pW/Invoice%20INV-1042.pdf",
    "expires_at": "2026-11-03T10:22:31.000Z",
    "filename": "Invoice INV-1042.pdf",
    "pages": 2,
    "bytes": 184213,
    "mark": null,
    "missing_variables": [],
    "skipped_resources": []
  },
  "error": null
}

POST /v1/jobs/{id}/webhook#

Deliver a job's webhook again

Send a finished job's event to its webhook_url again now, after your receiver was down or lost it. The response is the job, its webhook saying how the delivery went.

Parameters

id path · string required

The job's id (job_…).

Needs a key with the print scope (scopes).

Responses

200

The job after the delivery.

401

No API key, or one not valid.

403

A claim of the Pro and Max plans (PDF/A, PDF/X, PDF/UA-2) on another plan (plan_required); a key without the scope the route asks for (insufficient_scope), or used from an address it is not kept to (ip_not_allowed).

404

No such job in this account, or it is over 24 hours old.

409

The job has no webhook (no_webhook), is not finished (job_not_finished), or an attempt to deliver its event is under way (delivery_in_progress).

429

Too many requests of this account at once, or in the last minutes, or jobs not finished (rate_limited); or the files it stores for links fill its plan's space: Free 256 MB, Pro and Max 2 GB (storage_quota).

curl -X POST https://api.reflowpdf.com/v1/jobs/job_Qm9xT2nV8cLp4rWs1dYbZa/webhook \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY"

{
  "id": "job_Qm9xT2nV8cLp4rWs1dYbZa",
  "object": "job",
  "status": "succeeded",
  "created_at": "2026-11-02T10:22:30.114Z",
  "started_at": "2026-11-02T10:22:30.120Z",
  "finished_at": "2026-11-02T10:22:31.402Z",
  "template_id": "invoice",
  "webhook_url": "https://example.com/hooks/reflowpdf",
  "metadata": {
    "order": "42"
  },
  "result": {
    "id": "Hq8vR2cT9xKmL4pW",
    "object": "pdf",
    "url": "https://api.reflowpdf.com/v1/files/Hq8vR2cT9xKmL4pW/Invoice%20INV-1042.pdf",
    "expires_at": "2026-11-03T10:22:31.000Z",
    "filename": "Invoice INV-1042.pdf",
    "pages": 2,
    "bytes": 184213,
    "mark": null,
    "missing_variables": [],
    "skipped_resources": []
  },
  "error": null
}

GET /v1/webhook-secret#

Get the webhook secret

The secret with which your account's webhooks are signed (ReflowPDF-Signature). For 24 hours after a rotation, deliveries are signed with the previous secret too (a second v1).

Needs a key with the account scope (scopes).

Responses

200

The secret.

401

No API key, or one not valid.

403

A claim of the Pro and Max plans (PDF/A, PDF/X, PDF/UA-2) on another plan (plan_required); a key without the scope the route asks for (insufficient_scope), or used from an address it is not kept to (ip_not_allowed).

curl https://api.reflowpdf.com/v1/webhook-secret \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY"

{
  "object": "webhook_secret",
  "secret": "whsec_3vK9…",
  "rotated_at": null,
  "previous_expires_at": null
}

POST /v1/webhook-secret/rotate#

Rotate the webhook secret

A new secret now. For 24 hours deliveries carry a signature with each (the new and the previous) while your receivers move to the new one.

Needs a key with the account scope (scopes).

Responses

200

The new secret.

401

No API key, or one not valid.

403

A claim of the Pro and Max plans (PDF/A, PDF/X, PDF/UA-2) on another plan (plan_required); a key without the scope the route asks for (insufficient_scope), or used from an address it is not kept to (ip_not_allowed).

curl -X POST https://api.reflowpdf.com/v1/webhook-secret/rotate \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY"

{
  "object": "webhook_secret",
  "secret": "whsec_3vK9…",
  "rotated_at": null,
  "previous_expires_at": null
}

GET /v1/usage#

Get usage

The account's plan and this period: pages printed without the mark and what is left, AI pages, the files stored for links, and the rate of prints (also on every response as RateLimit-*).

Needs a key with the account scope (scopes).

Responses

200

The usage.

401

No API key, or one not valid.

403

A claim of the Pro and Max plans (PDF/A, PDF/X, PDF/UA-2) on another plan (plan_required); a key without the scope the route asks for (insufficient_scope), or used from an address it is not kept to (ip_not_allowed).

curl https://api.reflowpdf.com/v1/usage \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY"

{
  "object": "usage",
  "plan": "free",
  "status": null,
  "period_resets_at": "2026-12-01T00:00:00+00:00",
  "pages_printed": 12,
  "pages_without_mark": {
    "limit": 50,
    "used": 12,
    "remaining": 38
  },
  "api_pages": null,
  "ai_pages": {
    "quota": 10,
    "used": 0,
    "top_up": 0,
    "remaining": 10
  },
  "files": {
    "bytes": 1048576,
    "limit_bytes": 268435456
  },
  "rate": {
    "limit": 300,
    "remaining": 298,
    "reset": 431,
    "window": 600,
    "concurrent": 2,
    "active": 0
  }
}

GET /v1/engines#

List engine versions

The engine versions a print may be pinned to (engine): the current one, and the previous ones, each kept printing until three newer engines have shipped, 30 days at most. Public, from any page.

Public: no key needed, from any page.

Responses

200

The versions.

curl https://api.reflowpdf.com/v1/engines

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "engine",
      "version": "af4ba3e3b",
      "status": "current",
      "available_until": null
    },
    {
      "object": "engine",
      "version": "866470307",
      "status": "previous",
      "superseded_at": "2026-11-01T06:13:22.000Z",
      "available_until": "2026-12-01T06:13:22.000Z"
    }
  ]
}

GET /v1/status#

The status of the service

What was measured every minute: each part of the service (the API, printing, the editor, the MCP server, the docs) now, its last 90 days day by day, and its incidents: two minutes or more of failed checks in a row. Public, from any page. The page: https://api.reflowpdf.com/docs/status/.

Public: no key needed, from any page.

Responses

200

The status.

curl https://api.reflowpdf.com/v1/status

{
  "object": "status",
  "checked_at": "2026-11-01T10:22:31.000Z",
  "interval_seconds": 1,
  "status": "operational",
  "components": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "status": "operational",
      "uptime_90d": null,
      "latency_ms_24h": {
        "p50": 1,
        "p95": 1
      },
      "days": [
        {
          "date": "string",
          "measured": 1,
          "up": 1,
          "uptime": null
        }
      ]
    }
  ],
  "incidents": [
    {
      "component": "string",
      "name": "string",
      "started_at": "2026-11-01T10:22:31.000Z",
      "ended_at": "2026-11-01T10:22:31.000Z",
      "minutes": 1,
      "error": "string",
      "no_data_after": "2026-11-01T10:22:31.000Z"
    }
  ]
}

GET /v1/engine/license#

Get an engine license token

The signed token of an engine license, which @reflowpdf/engine checks offline (setLicense). By the license's key alone (public, written into your page; the engine package asks for it itself) the token is valid on the license's sites. With the API key of the license's owner it is also valid where there is no page (Node, Deno, Bun, a desktop app). A token lasts until the paid period ends and a week's grace, 42 days at most: ask again when it nears its end. Allowed from any origin (CORS).

Parameters

key query · string required

The license's key (rpdfl_…), given with the license.

Public: no key needed, from any page.

Responses

200

The token.

401

No API key, or one not valid.

402

The license is not paid for, or its subscription has ended.

404

No license has this key.

curl "https://api.reflowpdf.com/v1/engine/license?key=rpdfl_…" \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY"

{
  "object": "engine_license_token",
  "token": "rpdfl1.eyJ2IjoxLCJraWQiOiJrMSIsImlkIjoibGljXzh…",
  "license": "lic_8Jq2vX0mT4nR7pW1sYc3Ka",
  "licensee": "Northwind Studio Ltd",
  "domains": [
    "northwind.studio",
    "*.northwind.studio"
  ],
  "server": false,
  "expires_at": "2026-12-09T10:00:00.000Z"
}

GET /v1/files/{id}/{filename}#

Download a file

A PDF, an image or a ZIP of images stored for a link (Accept: application/json, a job, an Idempotency-Key). Its address is its key: keep it private; it works for 24 hours, unless its account deletes it.

Parameters

id path · string required

The file's id, from its link.

filename path · string required

The file's name, as its link gives it.

Needs a key with the print scope (scopes).

Responses

200

The file.

404

No such file of this account, or it expired (a file is kept 24 hours).

curl https://api.reflowpdf.com/v1/files/Hq8vR2cT9xKmL4pW/Q3%20report.pdf \
  -o "Q3 report.pdf"

DELETE /v1/files/{id}#

Delete a file

Delete a file of your account before its 24 hours: its link stops working, and its space counts no more.

Parameters

id path · string required

The file's id, from its link.

Needs a key with the print scope (scopes).

Responses

200

Deleted.

401

No API key, or one not valid.

403

A claim of the Pro and Max plans (PDF/A, PDF/X, PDF/UA-2) on another plan (plan_required); a key without the scope the route asks for (insufficient_scope), or used from an address it is not kept to (ip_not_allowed).

404

No such file of this account, or it expired (a file is kept 24 hours).

curl -X DELETE https://api.reflowpdf.com/v1/files/Hq8vR2cT9xKmL4pW \
  -H "Authorization: Bearer $REFLOWPDF_API_KEY"

{
  "id": "string",
  "object": "file",
  "deleted": true
}