API

The API module is an HTTP/1 and HTTP/2 (H2C) server. Other modules may add routes, middlewares, and health checks.

Properties

Port

--api-port          int     Set the port on which the API should listen (default 3000)
--api-port-from-env string  Set the environment variable with the port on which the API should listen - override the default port

Timeout

--api-read-timeout    duration  Set the maximum duration allowed to read a complete request, including the body (default 30s)
--api-process-timeout duration  Set the maximum duration allowed to process a request (default 30s)
--api-write-timeout   duration  Set the maximum duration before timing out writes of the response (default 30s)

Root path

--api-root-path string  Set the root path of the API - for service discovery via URL paths (default "/")

Trace

--api-trace-header string  Set the header name to use for identifying requests (default "Gotenberg-Trace")

Health

--api-disable-health-check-logging bool  Disable health check logging

Routes

Health

GET /health

Success

Status: 200 OK

Content-Type: application/json
Gotenberg-Trace: {trace}

Body:

{
    "status": "up",
    "details": {
        "moduleX": {
            "status": "up",
            "timestamp": "2021-07-01T08:05:14.603364Z"
        },
        "moduleY": {
            "status": "up",
            "timestamp": "2021-07-01T08:05:14.603364Z"
        },
    }
}

Error

Status: 503 Service Unavailable

Content-Type: application/json
Gotenberg-Trace: {trace}

Body:

{
    "status": "down",
    "details": {
        "moduleX": {
            "status": "up",
            "timestamp": "2021-07-01T08:05:14.603364Z"
        },
        "moduleY": {
            "status": "down",
            "timestamp": "2021-07-01T08:05:14.603364Z",
            "error": "An health check error"
        },
    }
}

info

There are no health checks in the standard version of Gotenberg. The details key is therefore not present.

Modules

multipart/form-data

METHOD /forms/{module}/{handler}

The following modules provide multipart/form-data routes:

• Chromium
• LibreOffice
• PDF Engines

Success

Status: 200 OK

Content-Disposition: attachement; filename={output-filename.ext}
Content-Type: {content-type}
Content-Length: {content-length}
Gotenberg-Trace: {trace}

Body: {output-file}

Error

Status: {status}

Content-Type: text/plain; charset=UTF-8
Gotenberg-Trace: {trace}

Body: {error}

---

Other routes

METHOD /{module}/{handler}

Currently, only the following module provides a non-multipart/form-data route:

• Prometheus

Middlewares

Trace all routes

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.

For instance:

curl \
--request POST 'http://localhost:3000/forms/chromium/convert/url' \
--header 'Gotenberg-Trace: debug' \
--form 'url="https://my.url"' \
-o my.pdf

info

The API adds a header Gotenberg-Trace to each response. If you're using the webhook feature, it also adds the header to each request to your callbacks.

tip

You may customize the trace header thanks to the --api-trace-header property.

Timeout all routes

The API returns a 503 Service Unavailable response if a request fails to finish before a given duration in one of these steps:

1. The server is reading a request.
2. A route handler is processing a request.
3. A route handler keeps processing a request, even if the timeout duration has expired (hard timeout).
4. The server is writing a response.

tip

You may customize the timeout durations thanks to the following properties:

• --api-read-timeout
• --api-process-timeout
• --api-write-timeout

Output Filename multipart

By default, the API generates a UUID filename. However, you may also specify the filename per request, thanks to the Gotenberg-Output-Filename header.

For instance:

curl \
--request POST 'http://localhost:3000/forms/chromium/convert/url' \
--header 'Gotenberg-Output-Filename: result' \
--form 'url="https://my.url"' \
-O -J

caution

The API adds the file extension automatically; you don't have to set it.

Modules

Currently, only the following module provides a middleware:

• Webhook