Routes
Gotenberg serves every route below on port 3000, under --api-root-path: / by default. Each has its own page.
Chromium
| Method | Route | What it does |
|---|---|---|
POST | /forms/chromium/convert/url | Prints a web page to PDF. |
POST | /forms/chromium/convert/html | Prints an HTML file, with the assets beside it, to PDF. |
POST | /forms/chromium/convert/markdown | Prints Markdown files, laid out by an HTML template, to PDF. |
POST | /forms/chromium/screenshot/url | Captures a web page as an image. |
POST | /forms/chromium/screenshot/html | Captures an HTML file as an image. |
POST | /forms/chromium/screenshot/markdown | Captures Markdown files, laid out by an HTML template, as an image. |
LibreOffice
| Method | Route | What it does |
|---|---|---|
POST | /forms/libreoffice/convert | Converts office documents, such as Word, Excel and PowerPoint files, to PDF. |
PDF
| Method | Route | What it does |
|---|---|---|
POST | /forms/pdf/pipe | Runs a list of stages on PDFs. |
POST | /forms/pdf/{op} | Runs one stage, its options as form fields: /forms/pdf/merge, /forms/pdf/rotate, and so on. |
POST | /forms/pdf/info | Reads the page count, the PDF version, and whether a PDF is encrypted, tagged, linearized, signed or holds form fields. |
POST | /forms/pdf/metadata | Reads the metadata: title, author, dates. |
POST | /forms/pdf/bookmarks | Reads the bookmarks. |
POST | /forms/pdf/attachments | Lists the embedded files. |
POST | /forms/pdf/form | Lists the form's fields: name, type, value, pages, and the values each takes. |
POST | /forms/pdf/validate | Checks PDFs against PDF/A, PDF/UA or Factur-X, and lists the violations. |
System
| Method | Route | What it does |
|---|---|---|
GET | / | Answers a short note: Gotenberg has no UI. |
GET, HEAD | /health | Reports whether Gotenberg and its engines are up. |
GET | /version | Answers the version of Gotenberg. |
GET | /debug | Answers the modules, engine versions and flags, once --api-enable-debug-route is on. |
Fields every route takes
The POST routes take multipart/form-data. Besides their own fields, they all take:
| Field | Takes |
|---|---|
files | The files to process, one upload each. |
archives | ZIP files, which Gotenberg unpacks as if you had uploaded their entries under files. |
downloadFrom | URLs Gotenberg downloads first, as if you had uploaded the files. |
The Chromium conversion routes, the LibreOffice route and /forms/pdf/pipe also take stages, which run on the PDFs they make or receive. The screenshot routes, the single-stage routes and the read routes answer 400 to it.
How requests work shows each one. The headers work on every route, except where they say otherwise.
What works where
Which route takes which feature. A field name in code is a form field of the route. A stage name, such as stamp-text, goes in the route's stages field, or, on a single-stage route, is the route itself: /forms/pdf/stamp-text.
Conversion routes
| Feature | Chromium PDF | Screenshots | LibreOffice |
|---|---|---|---|
| Input | A URL, HTML or Markdown | The same | Office documents, over a hundred formats |
files, archives, downloadFrom | Yes | Yes | Yes |
stages | Yes, on the printed PDF | No | Yes, on the exported PDFs |
| Webhooks | Yes | Yes | Yes |
Gotenberg-Output-Filename | Yes | Yes | Yes |
| Paper size, orientation | paperSize, landscape, paperWidth, paperHeight | width, height | paperSize, landscape, paperWidth, paperHeight |
| Margins | marginTop and the others | No | The document's own |
| Headers, footers, page numbers | header.html, footer.html | No | The document's own |
Waits, cookies, failOn checks | Yes | Yes | No |
| Pick pages | nativePages, or select | No | nativePages, or select |
| Watermark | The stamp stages | No | nativeWatermarkText, or the stamp stages |
| Bookmarks | nativeBookmarks, off by default, or set-bookmarks | No | nativeBookmarks, on by default, or set-bookmarks |
| Metadata | The page's <title>, or set-metadata | No | The document's properties, or set-metadata |
| PDF/A | remediate | No | nativePdfa, or remediate |
| Tagged PDF, PDF/UA | nativeTaggedPdf, remediate | No | nativeTaggedPdf, nativePdfua, remediate |
| Password-protected input | No | No | password |
| Encrypt, sign, timestamp | The stages, last | No | The stages, last |
| Forms | No | No | exportFormFields, then set-form |
| Images of the pages | render, after the PDF | The route itself | render, after the PDF |
| Smaller images, lower quality | No | quality, for JPEG | nativeQuality, nativeReduceImageResolution |
PDF routes
| Feature | /forms/pdf/pipe | Single-stage routes | Read routes |
|---|---|---|---|
| Input | PDFs | PDFs | PDFs |
files, archives, downloadFrom | Yes | Yes | Yes |
stages | Yes, required | No: the stage's options are fields | No |
| Webhooks | Yes | Yes | No |
Gotenberg-Output-Filename | Yes | Yes | No |
| Pick pages | select, delete, insert, split | /forms/pdf/select and the others | No |
| Watermark | The stamp stages | /forms/pdf/stamp-text and the others | No |
| Bookmarks | set-bookmarks; merge keeps them | /forms/pdf/set-bookmarks | /forms/pdf/bookmarks |
| Metadata | set-metadata | /forms/pdf/set-metadata | /forms/pdf/metadata |
| PDF/A, PDF/UA | remediate; autotag for tags | /forms/pdf/remediate | /forms/pdf/validate |
| Password-protected input | A decrypt stage first | /forms/pdf/decrypt only | password |
| Encrypt, sign, timestamp | The stages | /forms/pdf/encrypt and the others | No |
| Forms | set-form, flatten-form | /forms/pdf/set-form and the other | /forms/pdf/form |
| Images of the pages | render | /forms/pdf/render | No |
| Smaller files | optimize, which keeps the quality | /forms/pdf/optimize | No |
Two ways to the same result
A field whose name starts with native asks the engine to do the work while it makes the PDF. A stage does it afterwards, the same way on every route. How Gotenberg works says which to pick.
An uploaded PDF on a conversion
A conversion's stages see only the PDFs the conversion makes. To bring in a PDF you upload, name it in a stage that reads a file, such as insert or stamp-pdf. On the LibreOffice route, a PDF no stage names goes through LibreOffice like any document.