Skip to main content
Version: 7.x

API

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

Properties​

--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

Routes​

Health​

GET /health

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"
        },
    }
}

The details section gathers the health checks from modules. If none, this entry is not present.

Currently, only the following module provides a health check:

Modules​

multipart/form-data​

METHOD /forms/{module}/{handler}

The following modules provide multipart/form-data routes:

Status: 200 OK

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

Body: {output-file}

Other routes​

METHOD /{module}/{handler}

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

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.

tip

You may customize the time limit thanks to the --api-timeout property.

info

The API will close the socket if it fails to read the request body before the time limit. It will also close the socket if the API fails to write the response after a duration equal to two times the time limit. However, this scenario is unlikely.

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: