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("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("file-here") or resources(["file1", "file2"]) adds the file or files as a resource for the HTML index
- Add string resources with string_resource("file content").

Markdown file(s) into PDF¶

Gotenberg Documentation Link

Route Access: chromium.markdown_to_pdf()

Required Properties:

An index file is required:
- .index("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("file-here") or resources(["file1", "file2"]) adds the file or files as a resource for the HTML index
- Add string resources with string_resource("file content").

Screenshot Routes¶

Gotenberg Documentation Link

Common Settings¶

Gotenberg Option	Route Configuration	Python Type
width	`.width()`	`int`
height	`height()`	`int`
clip	`clip()` or `clip_to_dimensions()` or `no_clip_to_dimensions()`	`bool`
format	`output_format()`	one of "png", "jpeg" or "webp".
quality	`quality()`	`int`, between 1 and 100
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
Emulated Media Type
Cookies
Custom HTTP headers
Invalid HTTP 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`	Set via keyword only
`paperWidth` `paperHeight`	`.size()`	`PageSize`	Current only allows size configuration in inches
`marginTop` `marginBottom` `marginLeft` `marginRight`	`.margin()`	`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`

Header & Footer¶

Gotenberg Documentation Link

Gotenberg Option	Route Configuration	Python Type	Notes
`header.html`	`.header()`	`Path`
`footer.html`	`.footer()`	`Path`

Render Control¶

Gotenberg Documentation Link

Gotenberg Option	Route Configuration	Python Type	Notes
`waitDelay`	`.render_wait()`	`int \| float`
`waitForExpression`	`.render_expr()`	`str`

Emulated Media Type¶

Gotenberg Documentation Link

Gotenberg Option	Route Configuration	Python Type	Notes
`emulatedMediaType`	`.media_type()`	`EmulatedMediaType`

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

HTTP Status Codes¶

Gotenberg Documentation Link

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

Network Errors¶

Gotenberg Documentation Link

Gotenberg Option	Route Configuration	Python Type	Notes
`failOnResourceLoadingFailed`	`fail_on_resource_loading_failed`	`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

Split¶

Gotenberg Documentation Link

Gotenberg Option	Route Configuration	Python Type
splitMode	`.split_mode()`	one of "pages", "intervals"
splitSpan	`split_span()`	`str`
splitUnify	`split_unify()`	`bool`

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

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

Supported metadata fields:

title: Document title
author: Document author
subject: Document subject
keywords: List of keywords
creator: Creating application
creation_date: Creation datetime
modification_date: Last modification datetime
producer: PDF producer
trapped: Trapping status ('True', 'False', 'Unknown')
copyright: Copyright information
marked: PDF marked status
pdf_version: PDF version number

Note

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

LibreOffice¶

Office Documents to PDF¶

Gotenberg Link	Route Access	Required Properties	Optional Properties
Documentation	`libre_office.to_pdf`	`.convert("mydoc.docx")` or `.convert_files(["mydoc.docx"])`	See common LibreOffice options

Note

convert may be called multiple times" !!! note "convert_files is a convenience method to convert a list of file into PDF

LibreOffice Properties¶

Page Properties¶

Gotenberg Documentation

Gotenberg Option	Route Configuration	Python Type	Notes
`landscape`	`.orient()`	`PageOrientation`
`nativePageRanges`	`page_ranges()`	`str`
`exportFormFields`	N/A	N/A	This option is not implemented yet
`singlePageSheets`	N/A	N/A	This option is not implemented yet

Compress¶

Gotenberg Documentation

Merge¶

Gotenberg Documentation

Gotenberg Option	Route Configuration	Python Type	Notes
`merge`	`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

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

Convert into PDF/A & PDF/UA¶

Gotenberg Documentation

Gotenberg Link	Route Access	Required Properties	Optional Properties
`pdfa`	`.pdf_format()`	`PdfAFormat`
`pdfua`	`enable_universal_access()` `disable_universal_access()`	N/A

Note

At least one of pdf_format(), enable_universal_access() or disable_universal_access() must be set

Read PDF metadata¶

Gotenberg Documentation

Write PDF metadata¶

Gotenberg Documentation

Merge PDFs¶

Gotenberg Documentation

Gotenberg Link	Route Access	Required Properties	Optional Properties
`pdfa`	`.pdf_format()`	`PdfAFormat`
`pdfua`	`enable_universal_access()` `disable_universal_access()`	N/A
`metadata`	N/A	N/A	See PDF Metadata Support for the API interface.

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

Flatten PDFs¶

Gotenberg Documentation

Health Check¶

Gotenberg Documentation

Metrics¶

Warning

This route is not implemented

Version¶

Warning

This route is not implemented

Debug¶

Warning

This route is not implemented

Global Options¶

Request Tracing¶

Output Filename¶

Download From¶

Warning

This feature is not implemented