API Routes¶

Chromium¶

Access to the Chromium module of Gotenberg, as documented here.

URL into PDF¶

Gotenberg Documentation Link

Route Access: client.chromium.url_to_pdf()

Required Properties:

.url("http://localhost:8888")

HTML file into PDF¶

Gotenberg Documentation Link

Route Access: client.chromium.html_to_pdf()

Required Properties:

An index file is required:
- .index(Path("index.html")) sets the index from an HTML file
- .string_index("<html></html>") sets the index as the HTML string

Optional Properties:

Provide additional resource files as needed:
- .resource(Path("file-here")) or .resources([Path("file1"), Path("file2")]) adds the file or files as a resource for the HTML index
- Add a single string resource with .string_resource("file content", name="style.css")
- Add multiple string resources with .string_resources([("content", "name.css", "text/css"), ...])

Markdown file(s) into PDF¶

Gotenberg Documentation Link

Route Access: client.chromium.markdown_to_pdf()

Required Properties:

An index file is required:
- .index(Path("index.html")) sets the index from an HTML file
- .string_index("<html></html>") sets the index as the HTML string
At least one Markdown file:
- .markdown_file(Path("readme.md")) adds a single Markdown file
- .markdown_files([Path("a.md"), Path("b.md")]) adds multiple Markdown files

Optional Properties:

Provide additional resource files as needed:
- .resource(Path("file-here")) or .resources([Path("file1"), Path("file2")]) adds the file or files as a resource for the HTML index
- Add string resources with .string_resource("file content", name="style.css")

Screenshot Routes¶

Gotenberg Documentation Link

Three screenshot routes are available, each corresponding to a different input source:

Route Access	Input
`client.chromium.screenshot_url()`	A URL — use `.url("https://example.com")`
`client.chromium.screenshot_html()`	An HTML file — uses the same `.index()` / `.resource()` methods as HTML-to-PDF
`client.chromium.screenshot_markdown()`	Markdown — uses the same `.index()` / `.markdown_file()` methods as Markdown-to-PDF

Common Settings¶

Gotenberg Option	Route Configuration	Python Type	Notes
width	`.width()`	`int`
height	`.height()`	`int`
clip	`.clip()` or `.clip_to_dimensions()` or `.no_clip_to_dimensions()`	`bool`
format	`.output_format()`	`Literal["png", "jpeg", "webp"]`	defaults to `"png"`
quality	`.quality()`	`int`, between 0 and 100	out-of-range values are clamped
omitBackground	`.omit_background()` or `.hide_background()` or `.show_background()`	`bool`
optimizeForSpeed	`.image_optimize()` or `.image_optimize_for_speed()` or `.image_optimize_for_quality()`	`bool`

This route also supports other Chromium options:

Wait Before Rendering
JavaScript Timing
Emulated Media Type
Emulated Media Features
Cookies
Custom HTTP headers
Invalid HTTP Status Codes
Resource Status Codes
Console Exceptions
Performance Mode

Chromium Common Options¶

Page Properties¶

Gotenberg Documentation Link

Gotenberg Option	Route Configuration	Python Type	Notes
`singlePage`	`.single_page()`	`bool`	keyword only
`paperWidth` `paperHeight`	`.size()`	`PageSize`
`marginTop` `marginBottom` `marginLeft` `marginRight`	`.margins()`	`PageMarginsType`
`preferCssPageSize`	`.prefer_css_page_size()` `.prefer_set_page_size()`	N/A
`printBackground`	`.background_graphics()` `.no_background_graphics()`	N/A
`omitBackground`	`.hide_background()` `.show_background()`	N/A
`landscape`	`.orient()`	`PageOrientation`
`scale`	`.scale()`	`int \| float`
`nativePageRanges`	`.page_ranges()`	`str`
`generateDocumentOutline`	`.generate_document_outline()`	`bool`	keyword only

Header & Footer¶

Gotenberg Documentation Link

Gotenberg Option	Route Configuration	Python Type	Notes
`header.html`	`.header()`	`Path`
`footer.html`	`.footer()`	`Path`
`header.html`	`.string_header(html)`	`str`	sets the header from an in-memory HTML string
`footer.html`	`.string_footer(html)`	`str`	sets the footer from an in-memory HTML string

Render Control¶

Gotenberg Documentation Link

Gotenberg Option	Route Configuration	Python Type	Notes
`waitDelay`	`.render_wait()`	`int \| float \| timedelta`	Raises `NegativeWaitDurationError` if negative
`waitForExpression`	`.render_expression()`	`str`

Emulated Media Type¶

Gotenberg Documentation Link

Gotenberg Option	Route Configuration	Python Type	Notes
`emulatedMediaType`	`.media_type()`	`Literal["print", "screen"]`

Cookies¶

Gotenberg Documentation Link

Gotenberg Option	Route Configuration	Python Type	Notes
`cookies`	`.cookies()`	`list[CookieJar]`

Custom HTTP Headers¶

Gotenberg Documentation Link

Gotenberg Option	Route Configuration	Python Type	Notes
`extraHttpHeaders`	`.headers()`	`dict[str, str]`	The dictionary of values will be JSON encoded for you
`userAgent`	`.user_agent()`	`str`

HTTP Status Codes¶

Gotenberg Documentation Link

Gotenberg Option	Route Configuration	Python Type	Notes
`failOnHttpStatusCodes`	`.fail_on_status_codes()`	`Iterable[HTTPStatus]`

Network Errors¶

Gotenberg Documentation Link

Gotenberg Option	Route Configuration	Python Type	Notes
`failOnResourceLoadingFailed`	`.fail_on_resource_loading_failed(*, fail_on_resource_loading_failed: bool)`	`bool`

Console Exceptions¶

Gotenberg Documentation Link

Gotenberg Option	Route Configuration	Python Type	Notes
`failOnConsoleExceptions`	`.fail_on_exceptions()` `.dont_fail_on_exceptions()`	N/A

Performance Mode¶

Gotenberg Documentation Link

Gotenberg Option	Route Configuration	Python Type	Notes
`skipNetworkIdleEvent`	`.skip_network_idle()` `.use_network_idle()`	N/A
`skipNetworkAlmostIdleEvent`	`.skip_network_almost_idle(*, skip)`	`bool`	keyword only

JavaScript Timing¶

Gotenberg Documentation

Gotenberg Option	Route Configuration	Python Type	Notes
`waitForSelector`	`.wait_for_selector()`	`str`

Emulated Media Features¶

Gotenberg Documentation

Gotenberg Option	Route Configuration	Python Type	Notes
`emulatedMediaFeatures`	`.emulated_media_features()`	`list[dict[str, str]]`	e.g. `[{"name": "prefers-color-scheme", "value": "dark"}]`

Resource Status Codes¶

Gotenberg Documentation

Gotenberg Option	Route Configuration	Python Type	Notes
`failOnResourceHttpStatusCodes`	`.fail_on_resource_status_codes()`	`Iterable[HTTPStatus]`
`ignoreResourceHttpStatusDomains`	`.ignore_resource_status_domains()`	`list[str]`

Accessibility (PDF routes only)¶

Gotenberg Documentation

Gotenberg Option	Route Configuration	Python Type	Notes
`generateTaggedPdf`	`.generate_tagged_pdf(*, generate)`	`bool`	keyword only; PDF routes only

Split¶

Gotenberg Documentation Link

Gotenberg Option	Route Configuration	Python Type	Notes
`splitMode`	`.split_mode()`	`Literal["pages", "intervals"]`
`splitSpan`	`.split_span()`	`str`
`splitUnify`	`.split_unify()`	`bool`	keyword only

PDF/A & PDF/UA¶

Gotenberg Option	Route Configuration	Python Type	Notes
`pdfa`	`.pdf_format()`	`PdfAFormat`
`pdfua`	`.enable_universal_access()` `.disable_universal_access()`	N/A

PDF Metadata Support¶

Gotenberg Documentation

Add metadata to your PDFs:

from gotenberg_client import GotenbergClient
from datetime import datetime
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.chromium.html_to_pdf() as route:
        response = (route
            .index(Path("my-index.html"))
            .metadata(
                title="My Document",
                author="John Doe",
                creation_date=datetime.now(),
                keywords=["sample", "document"],
                subject="Sample PDF Generation",
            )
            .run())

Supported metadata fields:

title: Document title
author: Document author
subject: Document subject
keywords: List of keywords (no commas in individual keywords)
creator: Creating application
creation_date: Creation datetime
modification_date: Last modification datetime
producer: PDF producer
trapped: Trapping status (bool, or TrappedStatus.TRUE / TrappedStatus.FALSE / TrappedStatus.UNKNOWN)
pdf_copyright: Copyright information
marked: PDF marked status (bool)
pdf_version: PDF version number (1.0–2.0)

Note

Some fields cannot be set or will be overwritten, depending on Gotenberg and its utilized PDF engine

Flatten, Watermark, Stamp, Rotate, Encrypt, Embeds, Download From¶

Chromium conversion routes also support flattening, watermarking, stamping, rotation, encryption, file embedding, and URL-based input. See the Global Options section for details.

LibreOffice¶

Office Documents to PDF¶

Gotenberg Link Route Access Required Properties Optional Properties

Documentation

client.libre_office.to_pdf()

Any of:

.convert(Path("mydoc.docx"))
.convert_files([Path("mydoc.docx")])
.convert_in_memory_file(data, name="mydoc.docx")

See common LibreOffice options

Note

convert / convert_in_memory_file may be called multiple times

Note

convert_files is a convenience method to convert a list of files into PDF

LibreOffice Properties¶

Page Properties¶

Gotenberg Documentation

Gotenberg Option	Route Configuration	Python Type	Notes
`landscape`	`.orient()`	`PageOrientation`
`nativePageRanges`	`.page_ranges()`	`str`	e.g. `"1-5,8,11-13"`
`exportFormFields`	`.export_form_fields()`	`bool`	keyword only
`singlePageSheets`	`.single_page_sheets()`	`bool`	keyword only; spreadsheets only
`password`	`.password()`	`str`	for password-protected documents
`updateIndexes`	`.update_indexes()`	`bool`	keyword only
`allowDuplicateFieldNames`	`.allow_duplicate_form_fields()`	`bool`	keyword only
`exportBookmarks`	`.export_bookmarks()`	`bool`	keyword only
`exportBookmarksToPdfDestination`	`.export_bookmarks_to_pdf_destination()`	`bool`	keyword only
`exportNotes`	`.export_notes()`	`bool`	keyword only
`exportNotesPages`	`.export_notes_pages()`	`bool`	keyword only; presentations only
`exportOnlyNotesPages`	`.export_only_notes_pages()`	`bool`	keyword only; presentations only
`exportNotesInMargin`	`.export_notes_in_margin()`	`bool`	keyword only
`convertOooTargetToPdfTarget`	`.convert_ooo_target_to_pdf_target()`	`bool`	keyword only
`exportLinksRelativeFsys`	`.export_links_relative_fsys()`	`bool`	keyword only
`exportHiddenSlides`	`.export_hidden_slides()`	`bool`	keyword only; presentations only
`skipEmptyPages`	`.skip_empty_pages()`	`bool`	keyword only
`addOriginalDocumentAsStream`	`.add_original_document_as_stream()`	`bool`	keyword only
`exportPlaceholders`	`.export_placeholders()`	`bool`	keyword only

Compress¶

Gotenberg Documentation

Gotenberg Option	Route Configuration	Python Type	Notes
`losslessImageCompression`	`.lossless_image_compression()`	`bool`	keyword only
`quality`	`.quality()`	`int` (1–100)	out-of-range values are clamped
`reduceImageResolution`	`.reduce_image_resolution()`	`bool`	keyword only
`maxImageResolution`	`.max_image_resolution()`	`Literal[75, 150, 300, 600, 1200]`	DPI

Merge¶

Gotenberg Documentation

Gotenberg Option	Route Configuration	Python Type	Notes
`merge`	`.do_merge()` `.no_merge()`	N/A

Note

If multiple files are provided, and the merge is left as default or no_merge() is called, the resulting file will be a zip

Split¶

Gotenberg Documentation

Gotenberg Option	Route Configuration	Python Type	Notes
`splitMode`	`.split_mode()`	`Literal["pages", "intervals"]`
`splitSpan`	`.split_span()`	`str`	e.g. `"1-3"`
`splitUnify`	`.split_unify()`	`bool`	keyword only

PDF/A & PDF/UA¶

Gotenberg Documentation

Gotenberg Option	Route Configuration	Python Type	Notes
`pdfa`	`.pdf_format()`	`PdfAFormat`
`pdfua`	`.enable_universal_access()` `.disable_universal_access()`	N/A

Metadata¶

Gotenberg Documentation

See PDF Metadata Support for the API interface.

Flatten¶

Gotenberg Documentation

Gotenberg Option	Route Configuration	Python Type	Notes
`flatten`	`.flatten()`	`bool`	keyword only

Native Watermark¶

Gotenberg Documentation

Apply a watermark using LibreOffice's own watermarking engine (distinct from the pdfcpu/pdftk-based Watermark in Global Options).

Gotenberg Option	Route Configuration	Python Type	Notes
`nativeWatermarkText`	`.native_watermark_text()`	`str`	center watermark text
`nativeWatermarkColor`	`.native_watermark_color()`	`int`	RGB color as integer (e.g. `0x808080`)
`nativeWatermarkFontHeight`	`.native_watermark_font_height()`	`int`	font size in points
`nativeWatermarkRotateAngle`	`.native_watermark_rotate_angle()`	`int`	rotation in tenths of a degree (e.g. `450` = 45.0°)
`nativeWatermarkFontName`	`.native_watermark_font_name()`	`str`	font name
`nativeTiledWatermarkText`	`.native_tiled_watermark_text()`	`str`	tiled watermark text repeated across page

PDF Viewer Preferences¶

Gotenberg Documentation

Set PDF viewer preferences that are embedded into the output PDF by LibreOffice.

Gotenberg Option	Route Configuration	Python Type	Notes
`initialView`	`.initial_view()`	`InitialView`	panel open on initial display
`initialPage`	`.initial_page()`	`int`	page to display initially
`magnification`	`.magnification()`	`MagnificationOption`	initial zoom level
`zoom`	`.zoom()`	`int`	zoom percentage
`pageLayout`	`.page_layout()`	`PageLayout`	page layout mode
`firstPageOnLeft`	`.first_page_on_left(*, ...)`	`bool`	keyword only
`resizeWindowToInitialPage`	`.resize_window_to_initial_page(*, ...)`	`bool`	keyword only
`centerWindow`	`.center_window(*, ...)`	`bool`	keyword only
`openInFullScreenMode`	`.open_in_full_screen_mode(*, ...)`	`bool`	keyword only
`displayPDFDocumentTitle`	`.display_pdf_document_title(*, ...)`	`bool`	keyword only
`hideViewerMenubar`	`.hide_viewer_menubar(*, ...)`	`bool`	keyword only
`hideViewerToolbar`	`.hide_viewer_toolbar(*, ...)`	`bool`	keyword only
`hideViewerWindowControls`	`.hide_viewer_window_controls(*, ...)`	`bool`	keyword only
`useTransitionEffects`	`.use_transition_effects(*, ...)`	`bool`	keyword only
`openBookmarkLevels`	`.open_bookmark_levels()`	`int`	`-1` to open all levels

InitialView, MagnificationOption, and PageLayout are importable from gotenberg_client.options.

Watermark, Stamp, Rotate, Encrypt, Embeds, Download From¶

The LibreOffice route also supports watermarking, stamping, rotation, encryption, file embedding, and URL-based input. See the Global Options section for details.

Convert into PDF/A & PDF/UA¶

Gotenberg Documentation

Route Access: client.pdf_convert.to_pdfa()

Required Properties:

At least one file via .convert(Path("file.pdf")) or .convert_files([...])
At least one of pdf_format(), enable_universal_access(), or disable_universal_access() must be set

Gotenberg Option	Route Configuration	Python Type	Notes
`pdfa`	`.pdf_format()`	`PdfAFormat`
`pdfua`	`.enable_universal_access()` `.disable_universal_access()`	N/A

from gotenberg_client import GotenbergClient
from gotenberg_client.options import PdfAFormat
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.pdf_convert.to_pdfa() as route:
        response = (
            route.convert(Path("my.pdf"))
            .pdf_format(PdfAFormat.A2b)
            .run()
        )
        response.to_file(Path("my-pdfa.pdf"))

Read PDF Metadata¶

Gotenberg Documentation

Route Access: client.metadata.read()

Required Properties:

At least one file via .read(Path("file.pdf")) or .read_files([...])

Note

Unlike other routes, .run() returns dict[str, dict[str, str]] — one entry per input file mapping to that file's metadata fields — rather than a file response.

from gotenberg_client import GotenbergClient
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.metadata.read() as route:
        metadata = route.read(Path("my.pdf")).run()
        # metadata == {"my.pdf": {"Title": "...", "Author": "...", ...}}

Write PDF Metadata¶

Gotenberg Documentation

Route Access: client.metadata.write()

Required Properties:

At least one file via .write(Path("file.pdf")) or .write_files([...])
At least one metadata field set via .metadata()

See PDF Metadata Support for all available metadata fields.

from gotenberg_client import GotenbergClient
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.metadata.write() as route:
        response = (
            route.write(Path("my.pdf"))
            .metadata(title="New Title", author="New Author")
            .run()
        )
        response.to_file(Path("my-updated.pdf"))

Merge PDFs¶

Gotenberg Documentation

Route Access: client.merge.merge()

Required Properties:

At least one call to .merge([Path("a.pdf"), Path("b.pdf")]) — list order determines merge order

Optional Properties:

Gotenberg Option	Route Configuration	Python Type	Notes
`pdfa`	`.pdf_format()`	`PdfAFormat`
`pdfua`	`.enable_universal_access()` `.disable_universal_access()`	N/A
`flatten`	`.flatten()`	`bool`	keyword only
`metadata`	`.metadata()`	N/A	See PDF Metadata Support
`autoIndexBookmarks`	`.auto_index_bookmarks(*, enable)`	`bool`	keyword only; re-index bookmark page numbers
`bookmarks`	`.merge_bookmarks(bookmark_list)`	`list[dict[str, Any]]`	custom bookmarks; each entry: `{"title": str, "page": int, "children": [...]}`
watermark	See Watermark	`WatermarkStampSource`
stamp	See Stamp	`WatermarkStampSource`
rotate	`.rotate()`	`RotateAngle`
encrypt	`.user_password()` / `.owner_password()`	`str`
embeds	`.embed()` / `.embed_files()`	`Path` / `list[Path]`
downloadFrom	`.download_from()`	`list[DownloadFromUrl]`

from gotenberg_client import GotenbergClient
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.merge.merge() as route:
        response = route.merge([Path("a.pdf"), Path("b.pdf"), Path("c.pdf")]).run()
        response.to_file(Path("merged.pdf"))

Note

Prefixes will be added to the file to ensure they are merged in the order provided to merge(), even with multiple calls

Split PDFs¶

Gotenberg Documentation

Route Access: client.split.split()

Required Properties:

At least one file via .split(Path("file.pdf")) or .split_files([...])
.split_mode() and .split_span() must be configured

Optional Properties:

Gotenberg Option	Route Configuration	Python Type	Notes
`splitMode`	`.split_mode()`	`Literal["pages", "intervals"]`
`splitSpan`	`.split_span()`	`str`	e.g. `"1-3"`
`splitUnify`	`.split_unify()`	`bool`	keyword only
`pdfa`	`.pdf_format()`	`PdfAFormat`
`pdfua`	`.enable_universal_access()` `.disable_universal_access()`	N/A
`flatten`	`.flatten()`	`bool`	keyword only
`metadata`	`.metadata()`	N/A	See PDF Metadata Support
watermark	See Watermark	`WatermarkStampSource`
stamp	See Stamp	`WatermarkStampSource`
rotate	`.rotate()`	`RotateAngle`
encrypt	`.user_password()` / `.owner_password()`	`str`
embeds	`.embed()` / `.embed_files()`	`Path` / `list[Path]`
downloadFrom	`.download_from()`	`list[DownloadFromUrl]`

from gotenberg_client import GotenbergClient
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.split.split() as route:
        response = (
            route.split(Path("large.pdf"))
            .split_mode("pages")
            .split_span("1-3")
            .run()
        )
        # Split produces a ZIP containing the resulting pages
        response.to_file(Path("split.zip"))

Flatten PDFs¶

Gotenberg Documentation

Route Access: client.flatten.flatten()

Required Properties:

At least one file via .flatten(Path("file.pdf")) or .flatten_files([...])

from gotenberg_client import GotenbergClient
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.flatten.flatten() as route:
        response = route.flatten(Path("my.pdf")).run()
        response.to_file(Path("flattened.pdf"))

Watermark PDFs¶

Gotenberg Documentation

Route Access: client.watermark.watermark()

Apply a watermark behind the content of each page of existing PDFs.

Required Properties:

At least one file via .add_file(Path("file.pdf")) or .add_files([...])
.watermark_source() with a WatermarkStampSource value

from gotenberg_client import GotenbergClient
from gotenberg_client.options import WatermarkStampSource
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.watermark.watermark() as route:
        response = (
            route.add_file(Path("my.pdf"))
            .watermark_source(WatermarkStampSource.Text)
            .watermark_expression("DRAFT")
            .run()
        )
        response.to_file(Path("watermarked.pdf"))

See Watermark in Global Options for all available watermark configuration options. This route also supports Stamp, Rotate, Encrypt, Embeds, PDF/A & PDF/UA, PDF Metadata Support, and Download From.

Stamp PDFs¶

Gotenberg Documentation

Route Access: client.stamp.stamp()

Apply a stamp on top of the content of each page of existing PDFs.

Required Properties:

At least one file via .add_file(Path("file.pdf")) or .add_files([...])
.stamp_source() with a WatermarkStampSource value

from gotenberg_client import GotenbergClient
from gotenberg_client.options import WatermarkStampSource
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.stamp.stamp() as route:
        response = (
            route.add_file(Path("my.pdf"))
            .stamp_source(WatermarkStampSource.Text)
            .stamp_expression("CONFIDENTIAL")
            .run()
        )
        response.to_file(Path("stamped.pdf"))

See Stamp in Global Options for all available stamp configuration options. This route also supports Watermark, Rotate, Encrypt, Embeds, PDF/A & PDF/UA, PDF Metadata Support, and Download From.

Rotate PDFs¶

Gotenberg Documentation

Route Access: client.rotate.rotate()

Rotate pages of existing PDFs.

Required Properties:

At least one file via .add_file(Path("file.pdf")) or .add_files([...])
.rotate() with a RotateAngle value

from gotenberg_client import GotenbergClient
from gotenberg_client.options import RotateAngle
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.rotate.rotate() as route:
        response = (
            route.add_file(Path("my.pdf"))
            .rotate(RotateAngle.Clockwise90)
            .run()
        )
        response.to_file(Path("rotated.pdf"))

An optional pages string argument limits rotation to specific pages (e.g. "1-3"). This route also supports Encrypt, Embeds, PDF/A & PDF/UA, PDF Metadata Support, and Download From.

Encrypt PDFs¶

Gotenberg Documentation

Route Access: client.encrypt.encrypt()

Password-protect existing PDFs.

Required Properties:

At least one file via .add_file(Path("file.pdf")) or .add_files([...])
.user_password() — the password required to open the PDF (required by Gotenberg)

from gotenberg_client import GotenbergClient
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.encrypt.encrypt() as route:
        response = (
            route.add_file(Path("my.pdf"))
            .user_password("open-secret")
            .owner_password("edit-secret")  # optional
            .run()
        )
        response.to_file(Path("encrypted.pdf"))

Note

userPassword is required by the API. Providing only ownerPassword without userPassword will return a 400 error.

Embed Attachments¶

Gotenberg Documentation

Route Access: client.embed.embed()

Embed external files as attachments inside existing PDFs (e.g. for ZUGFeRD/Factur-X XML invoices).

Required Properties:

At least one PDF via .add_pdf(Path("file.pdf")) or .add_pdfs([...])
At least one file to embed via .embed(Path("attachment.xml")) or .embed_files([...])

from gotenberg_client import GotenbergClient
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.embed.embed() as route:
        response = (
            route.add_pdf(Path("invoice.pdf"))
            .embed(Path("factur-x.xml"))
            .run()
        )
        response.to_file(Path("invoice-with-attachment.pdf"))

This route also supports Download From.

Read PDF Bookmarks¶

Gotenberg Documentation

Route Access: client.bookmarks.read()

Extract the bookmark outline from existing PDFs.

Required Properties:

At least one file via .read(Path("file.pdf")) or .read_files([...])

Note

Unlike other routes, .run() returns dict[str, list[BookmarkEntry]] — one entry per input file mapping to that file's bookmark list — rather than a file response.

from gotenberg_client import GotenbergClient, BookmarkEntry
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.bookmarks.read() as route:
        bookmarks = route.read(Path("my.pdf")).run()
        # bookmarks == {"my.pdf": [{"title": "Chapter 1", "page": 1, "children": []}]}

Write PDF Bookmarks¶

Gotenberg Documentation

Route Access: client.bookmarks.write()

Write a bookmark outline into existing PDFs.

Required Properties:

At least one file via .add_file(Path("file.pdf")) or .add_files([...])
A bookmark list via .bookmarks(bookmark_list)

from gotenberg_client import GotenbergClient, BookmarkEntry
from pathlib import Path

bookmarks: list[BookmarkEntry] = [
    {"title": "Chapter 1", "page": 1, "children": []},
    {
        "title": "Chapter 2",
        "page": 5,
        "children": [
            {"title": "Section 2.1", "page": 6, "children": []},
        ],
    },
]

with GotenbergClient("http://localhost:3000") as client:
    with client.bookmarks.write() as route:
        response = route.add_file(Path("my.pdf")).bookmarks(bookmarks).run()
        response.to_file(Path("my-with-bookmarks.pdf"))

BookmarkEntry is a typed dict with fields:

Field	Type	Notes
`title`	`str`	Display name of the entry
`page`	`int`	1-based destination page
`children`	`list[BookmarkEntry]`	Nested child bookmarks

Health Check¶

Gotenberg Documentation

Route Access: client.health.health()

Returns a HealthStatus object with:

overall: overall service status (StatusOptions.Up or StatusOptions.Down)
chromium: ModuleStatus for the Chromium module (or None if not present)
uno: ModuleStatus for the LibreOffice/UNO module (or None if not present)

Metrics¶

Warning

This route is not implemented

Version¶

Gotenberg Documentation

Route Access: client.version.get()

Returns the Gotenberg server version as a string (e.g. "8.29.1").

from gotenberg_client import GotenbergClient

with GotenbergClient("http://localhost:3000") as client:
    version = client.version.get()
    print(version)  # e.g. "8.29.1"

Debug¶

Warning

This route is not implemented

Global Options¶

Request Tracing¶

Gotenberg Documentation

Set a trace ID on any route to correlate Gotenberg server logs with your requests:

with client.chromium.html_to_pdf() as route:
    response = route.index(Path("index.html")).trace_id("my-request-123").run()

Output Filename¶

Gotenberg Documentation

Control the filename Gotenberg sets in the Content-Disposition response header:

with client.chromium.html_to_pdf() as route:
    response = route.index(Path("index.html")).output_filename("report.pdf").run()

Download From¶

Gotenberg Documentation

Instruct Gotenberg to fetch input files from URLs instead of requiring direct uploads. Available on Chromium, LibreOffice, Merge, Split, Watermark, Stamp, Rotate, Encrypt, and Embed routes.

from gotenberg_client import GotenbergClient
from gotenberg_client.options import DownloadFromUrl
from pathlib import Path

with GotenbergClient("http://localhost:3000") as client:
    with client.chromium.url_to_pdf() as route:
        response = route.download_from([
            DownloadFromUrl(url="https://example.com/my.html"),
        ]).run()
        response.to_file(Path("output.pdf"))

DownloadFromUrl fields:

Field	Type	Notes
`url`	`str`	Required
`extra_http_headers`	`dict[str, str] \\| None`	Additional request headers
`embedded`	`bool`	Embed the file in the request (default: `False`)
`field`	`str \\| None`	Override the form field name

Watermark¶

Gotenberg Documentation

Apply a watermark behind the content of each page. Available on Chromium, LibreOffice, Merge, Split, Watermark, and Stamp routes. See also the standalone Watermark PDFs route.

Route Method	Python Type	Notes
`.watermark_source()`	`WatermarkStampSource`	`Text`, `Image`, or `Pdf`
`.watermark_expression()`	`str`	Text string or expression (when source is `Text`)
`.watermark_pages()`	`str`	Page range (e.g. `"1-3"`)
`.watermark_options()`	`WatermarkStampOptions`	Font, size, color, rotation, opacity, scale
`.watermark_file()`	`Path`	Image or PDF file to use as watermark (when source is `Image`/`Pdf`)

Stamp¶

Gotenberg Documentation

Apply a stamp on top of the content of each page. Available on Chromium, LibreOffice, Merge, Split, Watermark, and Stamp routes. Uses the same option types as Watermark. See also the standalone Stamp PDFs route.

Route Method	Python Type	Notes
`.stamp_source()`	`WatermarkStampSource`	`Text`, `Image`, or `Pdf`
`.stamp_expression()`	`str`	Text string or expression (when source is `Text`)
`.stamp_pages()`	`str`	Page range (e.g. `"1-3"`)
`.stamp_options()`	`WatermarkStampOptions`	Font, size, color, rotation, opacity, scale
`.stamp_file()`	`Path`	Image or PDF file to use as stamp

Rotate¶

Gotenberg Documentation

Rotate PDF pages. Available on Chromium, LibreOffice, Merge, Split, Watermark, Stamp, and Rotate routes. See also the standalone Rotate PDFs route.

Route Method	Python Type	Notes
`.rotate()`	`RotateAngle`	`Clockwise90`, `Clockwise180`, `Clockwise270`

An optional pages string argument limits rotation to specific pages (e.g. "1-3").

Encrypt¶

Gotenberg Documentation

Password-protect the output PDF. Available on Chromium, LibreOffice, Merge, Split, Watermark, Stamp, and Rotate routes. See also the standalone Encrypt PDFs route.

Route Method	Python Type	Notes
`.user_password()`	`str`	User (open) password
`.owner_password()`	`str`	Owner (permissions) password

Embeds¶

Gotenberg Documentation

Attach external files as embedded attachments inside the PDF container. Available on Chromium, LibreOffice, Merge, Split, Watermark, and Stamp routes. See also the standalone Embed Attachments route.

Route Method	Python Type	Notes
`.embed()`	`Path`	Attach a single file
`.embed_files()`	`list[Path]`	Convenience method to attach many files