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