Skip to main content
Version: 7.x

API

The API module is an HTTP server. Other modules may add multipart/form-data 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/jsonGotenberg-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"        },    }}
info

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

Modules#

POST /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}

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.

Webhook multipart#

The webhook feature allows you to upload the output file to the destination of your choice thanks to the following headers:

  • Gotenberg-Webhook-Url - the callback to use - required
  • Gotenberg-Webhook-Error-Url - the callback to use if error - required
  • Gotenberg-Webhook-Method - the HTTP method to use (POST, PATCH, or PUT - default POST).
  • Gotenberg-Webhook-Error-Method - the HTTP method to use if error (POST, PATCH, or PUT - default POST).
  • Gotenberg-Webhook-Extra-Http-Headers - the extra HTTP headers to send to both URLs (JSON format).

For instance:

curl \--request POST 'http://localhost:3000/forms/chromium/convert/url' \--header 'Gotenberg-Webhook-Extra-Http-Headers: {"MyHeader": "MyValue"}' \--header 'Gotenberg-Webhook-Url: https://my.webhook.url' \--header 'Gotenberg-Webhook-Method: PUT' \--header 'Gotenberg-Webhook-Error-Url: https://my.webhook.error.url' \--header 'Gotenberg-Webhook-Error-Method: POST' \--form 'url="https://my.url"'
Status: 204 No Content
tip

PipeDream provides an excellent platform if you wish to test the webhook feature.