openapi: 3.0.0 info: title: Gotenberg version: 6.3.1 license: name: MIT url: 'https://github.com/thecodingmachine/gotenberg/blob/master/LICENSE' contact: url: 'https://github.com/thecodingmachine/gotenberg' description: >- A Docker-powered stateless API for converting HTML, Markdown and Office documents to PDF. servers: - url: 'http://localhost:3000' description: Local server with the default Docker image and port paths: /convert/html: post: tags: - Gotenberg summary: Convert a given HTML file to PDF 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. An example `index.html` file can be as follows: ```html My PDF

Hello world!

``` You may also add a header and/or a footer in the resulting PDF by sending a file named `header.html` and `footer.html` respectively. Both the header and the footer files has to be a complete HTML document. An example `footer.html` can be as follows: ```html

of

``` The following classes will allow you to inject printing values in your document: - `date`: Formatted print date. - `title`: Document title. - `pageNumber`: Current page number. - `totalPage`: Total pages in the document. There are some limitations with header and footer files: - JavaScript is not executed. - External resources are not loaded. - The CSS properties are independant of the ones used in the `index.html` file. - `footer.html` CSS properties override the ones from `header.html`. - Only fonts installed in the Docker image are loaded (see the fonts section) - Images only work using a `base64` encoded source, e.g. ` My PDF {{ toHTML .DirPath "file.md" }} ``` Whereas your `file.md` file in the same level would be like: ```md # Title Content ``` 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. 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' /convert/office: post: tags: - Gotenberg summary: Convert an Office document to PDF description: >- Send one or more Office documents and get the resulting PDF file by merging all the files. The following file extensions are accepted: - `.txt` - `.rtf` - `.fodt` - `.doc` - `.docx` - `.odt` - `.xls` - `.xlsx` - `.ods` - `.ppt` - `.pptx` - `.odp` All files will be merged into a single PDF. > **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. requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/OfficeConvertRequestBody' 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' content: application/json: schema: type: object properties: {} /convert/merge: post: tags: - Gotenberg summary: Merge multiple PDFs into a single PDF 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. requestBody: content: multipart/form-data: schema: 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 resultFilename: type: string example: output.pdf description: >- If provided, the API will return the resulting PDF file with the given filename. Otherwise a random filename is used. required: - files 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' /ping: get: tags: - Gotenberg summary: Your GET endpoint responses: '200': description: The API is working fine. operationId: '' description: >- A simple endpoint to use as a healthcheck for the API availability with a simple request. 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. 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. resultFilename: type: string example: output.pdf description: >- If provided, the API will return the resulting PDF file with the given filename. Otherwise a random filename is used. required: - files MarkdownConvertRequestBody: title: Markdown 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. 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. resultFilename: type: string example: output.pdf description: >- If provided, the API will return the resulting PDF file with the given filename. Otherwise a random filename is used. required: - files URLConvertRequestBody: title: URL Conversion Request Body type: object properties: remoteURL: type: string example: 'https://google.com' 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. 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. resultFilename: type: string example: output.pdf description: >- If provided, the API will return the resulting PDF file with the given filename. Otherwise a random filename is used. required: - remoteURL OfficeConvertRequestBody: title: Office 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 pageRanges: type: string example: 1-3 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**. 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. resultFilename: type: string example: output.pdf description: >- If provided, the API will return the resulting PDF file with the given filename. Otherwise a random filename is used. required: - files MergeFilesRequestBody: title: Merge Files 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 resultFilename: type: string example: output.pdf description: >- If provided, the API will return the resulting PDF file with the given filename. Otherwise a random filename is used. required: - files securitySchemes: {} responses: SuccessfulPDF: description: Resulting PDF file from the conversion. content: application/pdf: schema: type: string format: binary