Skip to main content
Version: 9.x

Routes

Gotenberg serves every route below on port 3000, under --api-root-path: / by default. Each has its own page.

Chromium​

MethodRouteWhat it does
POST/forms/chromium/convert/urlPrints a web page to PDF.
POST/forms/chromium/convert/htmlPrints an HTML file, with the assets beside it, to PDF.
POST/forms/chromium/convert/markdownPrints Markdown files, laid out by an HTML template, to PDF.
POST/forms/chromium/screenshot/urlCaptures a web page as an image.
POST/forms/chromium/screenshot/htmlCaptures an HTML file as an image.
POST/forms/chromium/screenshot/markdownCaptures Markdown files, laid out by an HTML template, as an image.

LibreOffice​

MethodRouteWhat it does
POST/forms/libreoffice/convertConverts office documents, such as Word, Excel and PowerPoint files, to PDF.

PDF​

MethodRouteWhat it does
POST/forms/pdf/pipeRuns 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/infoReads the page count, the PDF version, and whether a PDF is encrypted, tagged, linearized, signed or holds form fields.
POST/forms/pdf/metadataReads the metadata: title, author, dates.
POST/forms/pdf/bookmarksReads the bookmarks.
POST/forms/pdf/attachmentsLists the embedded files.
POST/forms/pdf/formLists the form's fields: name, type, value, pages, and the values each takes.
POST/forms/pdf/validateChecks PDFs against PDF/A, PDF/UA or Factur-X, and lists the violations.

System​

MethodRouteWhat it does
GET/Answers a short note: Gotenberg has no UI.
GET, HEAD/healthReports whether Gotenberg and its engines are up.
GET/versionAnswers the version of Gotenberg.
GET/debugAnswers 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:

FieldTakes
filesThe files to process, one upload each.
archivesZIP files, which Gotenberg unpacks as if you had uploaded their entries under files.
downloadFromURLs 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​

FeatureChromium PDFScreenshotsLibreOffice
InputA URL, HTML or MarkdownThe sameOffice documents, over a hundred formats
files, archives, downloadFromYesYesYes
stagesYes, on the printed PDFNoYes, on the exported PDFs
WebhooksYesYesYes
Gotenberg-Output-FilenameYesYesYes
Paper size, orientationpaperSize, landscape, paperWidth, paperHeightwidth, heightpaperSize, landscape, paperWidth, paperHeight
MarginsmarginTop and the othersNoThe document's own
Headers, footers, page numbersheader.html, footer.htmlNoThe document's own
Waits, cookies, failOn checksYesYesNo
Pick pagesnativePages, or selectNonativePages, or select
WatermarkThe stamp stagesNonativeWatermarkText, or the stamp stages
BookmarksnativeBookmarks, off by default, or set-bookmarksNonativeBookmarks, on by default, or set-bookmarks
MetadataThe page's <title>, or set-metadataNoThe document's properties, or set-metadata
PDF/AremediateNonativePdfa, or remediate
Tagged PDF, PDF/UAnativeTaggedPdf, remediateNonativeTaggedPdf, nativePdfua, remediate
Password-protected inputNoNopassword
Encrypt, sign, timestampThe stages, lastNoThe stages, last
FormsNoNoexportFormFields, then set-form
Images of the pagesrender, after the PDFThe route itselfrender, after the PDF
Smaller images, lower qualityNoquality, for JPEGnativeQuality, nativeReduceImageResolution

PDF routes​

Feature/forms/pdf/pipeSingle-stage routesRead routes
InputPDFsPDFsPDFs
files, archives, downloadFromYesYesYes
stagesYes, requiredNo: the stage's options are fieldsNo
WebhooksYesYesNo
Gotenberg-Output-FilenameYesYesNo
Pick pagesselect, delete, insert, split/forms/pdf/select and the othersNo
WatermarkThe stamp stages/forms/pdf/stamp-text and the othersNo
Bookmarksset-bookmarks; merge keeps them/forms/pdf/set-bookmarks/forms/pdf/bookmarks
Metadataset-metadata/forms/pdf/set-metadata/forms/pdf/metadata
PDF/A, PDF/UAremediate; autotag for tags/forms/pdf/remediate/forms/pdf/validate
Password-protected inputA decrypt stage first/forms/pdf/decrypt onlypassword
Encrypt, sign, timestampThe stages/forms/pdf/encrypt and the othersNo
Formsset-form, flatten-form/forms/pdf/set-form and the other/forms/pdf/form
Images of the pagesrender/forms/pdf/renderNo
Smaller filesoptimize, which keeps the quality/forms/pdf/optimizeNo

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.