openapi: 3.0.3 info: title: Gotenberg version: 7.x license: name: MIT url: 'https://github.com/gotenberg/gotenberg/blob/main/LICENSE' contact: url: 'https://github.com/gotenberg/gotenberg' description: >- A Docker-powered stateless API for PDF files. externalDocs: url: https://gotenberg.dev servers: - url: 'http://localhost:3000' description: Local server with the default Docker image and port tags: - name: chromium description: Operations of the Chromium module externalDocs: url: https://gotenberg.dev/docs/modules/chromium - name: libreoffice description: Operations of the Libreoffice module externalDocs: url: https://gotenberg.dev/docs/modules/libreoffice - name: pdfengines description: Operations of the PDF Engines module externalDocs: url: https://gotenberg.dev/docs/modules/pdf-engines paths: /forms/chromium/convert/url: post: tags: - chromium summary: Convert the contents of a given URL to PDF externalDocs: url: https://gotenberg.dev/docs/modules/chromium description: >- Send a URL in your API request via the `url` form field Send a remote URL in your API request via the `remoteURL` parameter, and get the resulting PDF file. The API will fetch the given URL and render the page to PDF using the underlying headless Chrome instance. You can optionally include `header.html` and `footer.html` files as part of the request as well. See externalDocs for more details. parameters: - in: header name: Gotenberg-Output-Filename description: >- By default, the API generates a UUID filename. However, you may also specify the filename per request, thanks to the Gotenberg-Output-Filename header. Caution! The API adds the file extension automatically; you don't have to set it. schema: type: string required: false - in: header name: Gotenberg-Trace description: >- The trace, or request ID, identifies a request in the logs. By default, the API generates a UUID trace for each request. However, you may also specify the trace per request, thanks to the Gotenberg-Trace header. schema: type: string required: false requestBody: required: true description: >- The request must be `multipart/form-data` that includes a `url` form field. The API uses a headless Chrome instance to do the conversion, therefore print parameter such as margins and paper size are also accepted as optional parameters. content: multipart/form-data: schema: $ref: '#/components/schemas/URLConvertRequestBody' examples: { } responses: '200': $ref: '#/components/responses/SuccessfulPDF' '400': description: Bad Request /forms/chromium/convert/html: post: tags: - chromium summary: Convert a given HTML file to PDF externalDocs: url: https://gotenberg.dev/docs/modules/chromium description: >- Send an HTML file called `index.html` as a multipart form request, and get the resulting PDF file. You can optionally include `header.html` and `footer.html` files as part of the request as well. See externalDocs for more details. parameters: - in: header name: Gotenberg-Output-Filename description: >- By default, the API generates a UUID filename. However, you may also specify the filename per request, thanks to the Gotenberg-Output-Filename header. Caution! The API adds the file extension automatically; you don't have to set it. schema: type: string required: false - in: header name: Gotenberg-Trace description: >- The trace, or request ID, identifies a request in the logs. By default, the API generates a UUID trace for each request. However, you may also specify the trace per request, thanks to the Gotenberg-Trace header. schema: type: string required: false requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/HTMLConvertRequestBody' description: >- The request body must have an `index.html` file in the `files` array, as well as all the referred resources on the same level as the `index.html` file. The request can also include `header.html` and `footer.html`, given the limitations in the API description above. responses: '200': $ref: '#/components/responses/SuccessfulPDF' '400': description: Bad Request /forms/chromium/convert/markdown: post: tags: - chromium summary: Convert a Markdown file to PDF externalDocs: url: https://gotenberg.dev/docs/modules/chromium description: >- Accepts an HTML file called `index.html` plus markdown files as a multipart form request and embeds the markdown files into the HTML file using the Golang template function `toHTML`. The API will convert the markdown to HTML and embed it into your `index.html` file, then render the resulting page. You can include your own styling and more in your HTML file. Refer to the HTML conversion page for all the options you can use when converting Markdown documents as well. You can optionally include `header.html` and `footer.html` files as part of the request as well. See externalDocs for more details. parameters: - in: header name: Gotenberg-Output-Filename description: >- By default, the API generates a UUID filename. However, you may also specify the filename per request, thanks to the Gotenberg-Output-Filename header. Caution! The API adds the file extension automatically; you don't have to set it. schema: type: string required: false - in: header name: Gotenberg-Trace description: >- The trace, or request ID, identifies a request in the logs. By default, the API generates a UUID trace for each request. However, you may also specify the trace per request, thanks to the Gotenberg-Trace header. schema: type: string required: false requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/MarkdownConvertRequestBody' description: >- The request body must have an `index.html` file in the `files` array, as well as all the referred markdown resources on the same level as the `index.html` file. responses: '200': $ref: '#/components/responses/SuccessfulPDF' '400': description: Bad Request /forms/libreoffice/convert: post: tags: - libreoffice summary: Convert an Office document to PDF externalDocs: url: https://gotenberg.dev/docs/modules/libreoffice description: >- This route accepts multipart/form-data requests and files with the following extensions: .bib .doc .xml .docx .fodt .html .ltx .txt .odt .ott .pdb .pdf .psw .rtf .sdw .stw .sxw .uot .vor .wps .epub .png .bmp .emf .eps .fodg .gif .jpg .met .odd .otg .pbm .pct .pgm .ppm .ras .std .svg .svm .swf .sxd .sxw .tiff .xhtml .xpm .fodp .potm .pot .pptx .pps .ppt .pwp .sda .sdd .sti .sxi .uop .wmf .csv .dbf .dif .fods .ods .ots .pxl .sdc .slk .stc .sxc .uos .xls .xlt .xlsx .tif .jpeg .odp By default, if you send more than one file to convert, the route returns a ZIP archive of the resulting PDF files. However, you may prefer to merge all the PDF files into an individual PDF file. > **Attention:** The files will be merged alphabetically for the resulting PDF. You may also specify the page ranges to convert from the incoming Office documents. The expected format is the same as the one from the print options of LibreOffice, e.g. `1-1` or `1-4`. > **Attention:** if more than one document, the page ranges will be applied for each document. See externalDocs for more details. parameters: - in: header name: Gotenberg-Output-Filename description: >- By default, the API generates a UUID filename. However, you may also specify the filename per request, thanks to the Gotenberg-Output-Filename header. Caution! The API adds the file extension automatically; you don't have to set it. schema: type: string required: false - in: header name: Gotenberg-Trace description: >- The trace, or request ID, identifies a request in the logs. By default, the API generates a UUID trace for each request. However, you may also specify the trace per request, thanks to the Gotenberg-Trace header. schema: type: string required: false requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/OfficeConvertRequestBody' responses: '200': $ref: '#/components/responses/SuccessfulPDF' '400': description: Bad Request, e.g. Both 'pdfFormat' and 'nativePdfA1aFormat' form values are provided /forms/pdfengines/merge: post: tags: - pdfengines summary: Merge multiple PDFs into a single PDF externalDocs: url: https://gotenberg.dev/docs/modules/pdf-engines description: >- You can send multiple PDF files to this endpoint, the API will merge them into a single PDF and return the resulting PDF file. > **Attention:** The PDF files will be merged alphabetically. parameters: - in: header name: Gotenberg-Output-Filename description: >- By default, the API generates a UUID filename. However, you may also specify the filename per request, thanks to the Gotenberg-Output-Filename header. Caution! The API adds the file extension automatically; you don't have to set it. schema: type: string required: false - in: header name: Gotenberg-Trace description: >- The trace, or request ID, identifies a request in the logs. By default, the API generates a UUID trace for each request. However, you may also specify the trace per request, thanks to the Gotenberg-Trace header. schema: type: string required: false requestBody: content: multipart/form-data: schema: type: object properties: files: type: array items: type: string format: binary pdfFormat: type: string description: The PDF format of the resulting PDF example: PDF/A-1a required: - files responses: '200': $ref: '#/components/responses/SuccessfulPDF' '400': description: Bad Request /forms/pdfengines/convert: post: tags: - pdfengines summary: Convert PDFs into the given formats externalDocs: url: https://gotenberg.dev/docs/modules/pdf-engines description: >- This route accepts PDF files and a form field pdfFormat for converting them into the specified format. parameters: - in: header name: Gotenberg-Output-Filename description: >- By default, the API generates a UUID filename. However, you may also specify the filename per request, thanks to the Gotenberg-Output-Filename header. Caution! The API adds the file extension automatically; you don't have to set it. schema: type: string required: false - in: header name: Gotenberg-Trace description: >- The trace, or request ID, identifies a request in the logs. By default, the API generates a UUID trace for each request. However, you may also specify the trace per request, thanks to the Gotenberg-Trace header. schema: type: string required: false requestBody: content: multipart/form-data: schema: type: object properties: files: type: array items: type: string format: binary pdfFormat: type: string description: The PDF format of the resulting PDF example: PDF/A-1a required: - files - pdfFormat responses: '200': $ref: '#/components/responses/SuccessfulPDF' '400': description: >- Bad Request, e.g. Invalid form data: no form file found for extensions: [.pdf]; form value 'pdfFormat' is required components: schemas: HTMLConvertRequestBody: title: HTML Conversion Request Body type: object properties: files: type: array description: >- List of HTML files to be converted to PDF. An `index.html` file is required, and any other resources that are referenced through the HTML file must be included as well. All the referenced files must be on the same level as the `index.html` file. items: type: string format: binary marginTop: type: number example: 0 default: 1 description: Top margin for the page in inches. marginBottom: type: number example: 0 default: 1 description: Bottom margin for the page in inches. marginLeft: type: number example: 0 default: 1 description: Left margin for the page in inches. marginRight: type: number example: 0 default: 1 description: Right margin for the page in inches. paperWidth: type: number example: 8.27 description: >- Paper width to be used while rendering the PDF. The default page size is A4. paperHeight: type: number example: 11.69 description: >- Paper height to be used while rendering the PDF. The default page size is A4. preferCssPageSize: type: boolean description: >- Define whether to prefer page size as defined by CSS (default false) default: false printBackground: type: boolean description: >- Print the background graphics (default false) default: false landscape: type: boolean example: true default: false description: >- The default orientation for rendering the page is "portrait" mode. By sending "landscape" parameter, you can ask the output to be landscape. scale: type: number minimum: 0.1 maximum: 2.0 example: 1.5 description: >- The scale of the page rendering default: 1.0 waitDelay: type: string example: 5s description: >- When the page relies on JavaScript for rendering, and you don't have access to the page's code, you may want to wait a certain amount of time to make sure Chromium has fully rendered the page you're trying to generate. waitWindowStatus: type: string example: done description: >- If you have access to the page's code, you may set the window status and tell Gotenberg to wait for a specific value. For instance await promises() window.status = 'ready' Prefer this option over waitDelay. extraHttpHeaders: type: string description: HTTP headers to send by Chromium while loading the HTML document (JSON format) nativePageRanges: type: string example: 1-4 description: >- The page ranges to be converted to PDF for the incoming Office documents. pdfFormat: type: string description: >- The PDF format of the resulting PDF. Caution! You cannot use both nativePdfA1aFormat and pdfFormat form fields. example: PDF/A-1a required: - files MarkdownConvertRequestBody: title: Markdown Conversion Request Body type: object properties: files: type: array items: type: string format: binary marginTop: type: number example: 0 default: 1 description: Top margin for the page in inches. marginBottom: type: number example: 0 default: 1 description: Bottom margin for the page in inches. marginLeft: type: number example: 0 default: 1 description: Left margin for the page in inches. marginRight: type: number example: 0 default: 1 description: Right margin for the page in inches. paperWidth: type: number example: 8.27 description: >- Paper width to be used while rendering the PDF. The default page size is A4. paperHeight: type: number example: 11.69 description: >- Paper height to be used while rendering the PDF. The default page size is A4. preferCssPageSize: type: boolean description: >- Define whether to prefer page size as defined by CSS (default false) default: false printBackground: type: boolean description: >- Print the background graphics (default false) default: false landscape: type: boolean example: true default: false description: >- The default orientation for rendering the page is "portrait" mode. By sending "landscape" parameter, you can ask the output to be landscape. scale: type: number minimum: 0.1 maximum: 2.0 example: 1.5 description: >- The scale of the page rendering default: 1.0 waitDelay: type: string example: 5s description: >- When the page relies on JavaScript for rendering, and you don't have access to the page's code, you may want to wait a certain amount of time to make sure Chromium has fully rendered the page you're trying to generate. waitWindowStatus: type: string example: done description: >- If you have access to the page's code, you may set the window status and tell Gotenberg to wait for a specific value. For instance await promises() window.status = 'ready' Prefer this option over waitDelay. extraHttpHeaders: type: string description: HTTP headers to send by Chromium while loading the HTML document (JSON format) nativePageRanges: type: string example: 1-4 description: >- The page ranges to be converted to PDF for the incoming Office documents. pdfFormat: type: string description: >- The PDF format of the resulting PDF. Caution! You cannot use both nativePdfA1aFormat and pdfFormat form fields. example: PDF/A-1a required: - files URLConvertRequestBody: title: URL Conversion Request Body type: object properties: url: type: string example: 'https://google.com' files: description: Optional files named header.html and footer.html type: array items: type: string format: binary marginTop: type: number example: 0 default: 1 description: Top margin for the page in inches. marginBottom: type: number example: 0 default: 1 description: Bottom margin for the page in inches. marginLeft: type: number example: 0 default: 1 description: Left margin for the page in inches. marginRight: type: number example: 0 default: 1 description: Right margin for the page in inches. paperWidth: type: number example: 8.27 description: >- Paper width to be used while rendering the PDF. The default page size is A4. paperHeight: type: number example: 11.69 description: >- Paper height to be used while rendering the PDF. The default page size is A4. preferCssPageSize: type: boolean description: >- Define whether to prefer page size as defined by CSS (default false) default: false printBackground: type: boolean description: >- Print the background graphics (default false) default: false landscape: type: boolean example: true default: false description: >- The default orientation for rendering the page is "portrait" mode. By sending "landscape" parameter, you can ask the output to be landscape. scale: type: number minimum: 0.1 maximum: 2.0 example: 1.5 description: >- The scale of the page rendering default: 1.0 waitDelay: type: string example: 5s description: >- When the page relies on JavaScript for rendering, and you don't have access to the page's code, you may want to wait a certain amount of time to make sure Chromium has fully rendered the page you're trying to generate. waitWindowStatus: type: string example: done description: >- If you have access to the page's code, you may set the window status and tell Gotenberg to wait for a specific value. For instance await promises() window.status = 'ready' Prefer this option over waitDelay. extraHttpHeaders: type: string description: HTTP headers to send by Chromium while loading the HTML document (JSON format) nativePageRanges: type: string example: 1-4 description: >- The page ranges to be converted to PDF for the incoming Office documents. pdfFormat: type: string description: >- The PDF format of the resulting PDF. Caution! You cannot use both nativePdfA1aFormat and pdfFormat form fields. example: PDF/A-1a required: - url OfficeConvertRequestBody: title: Office Conversion Request Body type: object properties: files: type: array items: type: string format: binary nativePageRanges: type: string example: 1-4 description: >- The page ranges to be converted to PDF for the incoming Office documents. **If there are multiple files sent to the API, this page range will apply to all of the documents**. Empty means all pages. nativePdfA1aFormat: type: boolean description: >- Use unoconv to convert the resulting PDF to the 'PDF/A-1a' format. Caution! You cannot use both nativePdfA1aFormat and pdfFormat form fields. pdfFormat: type: string description: >- The PDF format of the resulting PDF. Caution! You cannot use both nativePdfA1aFormat and pdfFormat form fields. example: PDF/A-1a landscape: type: boolean example: true default: false description: >- The default orientation for rendering the page is "portrait" mode. By sending "landscape" parameter, you can ask the output to be landscape. merge: type: boolean description: >- Merge all PDF files into an individual PDF file. required: - files MergeFilesRequestBody: title: Merge Files Request Body type: object properties: files: type: array items: type: string format: binary required: - files securitySchemes: { } responses: SuccessfulPDF: description: Resulting PDF file from the conversion. content: application/pdf: schema: type: string format: binary