Skip to main content
Version: 9.x

How Gotenberg works

Gotenberg is an HTTP API in a Docker container. You post files and form fields; it answers with a PDF, an image, a ZIP of several files, or JSON.

What runs inside​

  • Chromium prints web pages: a URL, an HTML file with its assets, or Markdown. It also takes screenshots.
  • LibreOffice converts office documents: Word, Excel, PowerPoint, OpenDocument and over a hundred more formats. Gotenberg drives it through lok, a small program built on LibreOfficeKit.
  • litho, Gotenberg's PDF engine, written in Go, does everything to PDFs: merge, split, stamp, sign, encrypt, make PDF/A, PDF/UA or both, and validate.

Every image variant includes litho. The -chromium and -libreoffice variants leave out the other engine: see Install.

The routes​

  • Conversion routes turn what you send into PDF: /forms/chromium/convert/* and /forms/libreoffice/convert. The screenshot routes, /forms/chromium/screenshot/*, make images instead.
  • PDF routes work on PDFs you upload: /forms/pdf/pipe runs a list of stages, and each stage has a route of its own, such as /forms/pdf/merge.
  • Read routes answer JSON about PDFs: /forms/pdf/info, /forms/pdf/metadata, /forms/pdf/validate, and so on.

Routes lists them all, and shows what works where.

Stages​

A stage is one operation on a PDF: merge, stamp, redact, sign, make PDF/A. A request lists them in its stages field, and Gotenberg runs them in order:

curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@report.docx \
--form files=@annex.docx \
--form 'stages=[
{ "op": "merge" },
{ "op": "remediate", "profile": "PDF/A-2b" }
]' \
-o documents.pdf

The conversion routes and /forms/pdf/pipe take stages. A few rules keep a list sensible, such as signing last: see Order rules.

Native field or stage​

Some results have two ways in. A field whose name starts with native asks Chromium or LibreOffice to do it while they make the PDF. A stage does it afterwards, with litho, on any route:

ResultNative fieldStagePick the stage when
PDF/AnativePdfa: LibreOffice, four levels, uncheckedremediate: any route, eleven levels, reports what's leftUsually: it checks its result
PDF/UAnativePdfua: LibreOffice, PDF/UA-1, uncheckedremediate: PDF/UA-1 or PDF/UA-2, tags the PDF if neededAlways, to claim conformance
TagsnativeTaggedPdf: from your source's structureautotag: inferred from the page layoutThe PDF comes from elsewhere
BookmarksnativeBookmarks: from the headingsset-bookmarks: the list you giveYou want your own titles, or after a merge
PagesnativePages: the engine skips the others, which is fasterselect: also odd, even, last, exclusions such as !1, and a new orderYou reorder, or pick after a merge
WatermarknativeWatermarkText: LibreOffice, any script, sized to the pagestamp-text: any route, at an exact position, any script the image has a font forThe PDF comes from Chromium or elsewhere
Image sizenativeQuality: LibreOffice, lowers the qualityoptimize: keeps the quality, packs the fileYou can't lose quality

What comes back​

  • One file answers as itself, and several as a ZIP.
  • A PDF from a URL or HTML takes a random name, an office document report.docx.pdf, a merge the name of its first file. The parts of a split count from 0, report_0.pdf, and rendered pages from 1, report_1.png.
  • Gotenberg-Output-Filename names the result instead.
  • With webhook headers, Gotenberg answers right away and uploads the result: see Deliver with webhooks.

What Gotenberg checks​

  • remediate reports the violations it couldn't fix in Gotenberg-Remediation-Residual, and still answers 200: check the header.
  • Nothing checks what the native fields produce. /forms/pdf/validate checks any PDF against PDF/A, PDF/UA or Factur-X.
  • A stage that rewrites the file refuses a signed PDF, since rewriting it would drop the signature: see which stages rewrite.

How a request flows​

  1. Gotenberg reads the form: uploaded files, ZIP archives, and files to download from URLs.
  2. A conversion route hands the files to Chromium or LibreOffice. A PDF route skips this step.
  3. Gotenberg runs the stages, in order.
  4. It answers with the result, or uploads it to your webhook.

Gotenberg keeps nothing between requests. It deletes a request's files once it answers, so you can run as many containers as you need behind a load balancer.

Keep it private​

Gotenberg loads the URLs and opens the documents callers send it. Keep it behind your firewall: Secure your deployment covers the rest.

Open source​

Gotenberg is open source, under the MIT license, on GitHub. Its sponsors, listed at the bottom of every docs page, fund its development.