Skip to main content
Version: 10.0

Health API

The server API provides a /health endpoint that returns the current health status of the server and the services.

Example: http://localhost:8080/webPDF/health

The endpoint /health, which provides an overview of all available status checks, always responds with an HTTP status of 200 OK and a JSON structure (Content-Type: application/json) with further information about the individual services of the server.

The status of the individual services can be found in the JSON structure.

  • status: If UP, the service is available, if DOWN, it is not.
  • time: UTC time of the check execution
  • message: Additional information about the status of the service (optional).

Each health check has a name, such as live or ready, which is contained in the JSON structure.

Example:

{
  "checks": {
    "api": {
      "status": "UP",
      "time": "2025-08-13T08:56:51Z"
    },
    "cluster": {
      "status": "DOWN",
      "message": "Server is not running in cluster mode",
      "time": "2025-08-13T08:56:51Z"
    },
    "live": {
      "status": "UP",
      "time": "2025-08-13T08:56:51Z"
    },
    "ready": {
      "status": "UP",
      "time": "2025-08-13T08:56:51Z"
    }
  }
}

The health status of an individual service can be retrieved via its name and a direct endpoint where the name is appended.

Example: http://localhost:8080/webPDF/health/live or http://localhost:8080/webPDF/health/ready

These endpoints then return 503 Service Unavailable when the service is DOWN or a 200 OK when the service is UP.

note

In addition, the JSON structure is also returned for a 503 Service Unavailable.

The individual endpoints are structured according to the names in the JSON structure of /health:

  • /health/api: If UP, then at least one of the web service APIs (REST or SOAP) is available. If one API is disabled in the server configuration, the status of the API is still UP. If both APIs are disabled, the status of the API is DOWN.

  • /health/live: If UP, then the server has started, i.e., the server has started according to the configuration and can accept HTTP/HTTPS requests. However, the web service API has not yet started, i.e., no web service operations can be executed. For this use case, the /health/ready endpoint is more appropriate.

  • /health/ready: If UP, the web service API (see /health/api) is available and requests can be sent to the REST and SOAP web services. The server is operational (see /health/live) and can process requests. If the server is part of a cluster, it is ready to accept requests if the cluster status is also UP (see /health/cluster).

  • /health/cluster: Checks the server's status in relation to a cluster. If UP, then the server is part of a cluster and connected to it. It also checks the health status of all required components, including file, document and session storage. The server can operate as a node of the cluster when the health status of all components is UP. When the server is part of a cluster, the /health/cluster endpoint reports it status to the /health/ready endpoint. In this case the /health/ready endpoint returns UP when the server is part of a cluster and the cluster status is UP.

note

This endpoint /health/cluster can be used, for example, for a proxy to determine whether the server in the cluster can be used. It therefore corresponds to the status /health/ready when the server is operated in standalone mode.

In addition to the HTTP status code and the overall health status in status, some endpoints also provide detailed information about the checks performed under checks. In this case, the overall health status status is determined by the status of the individual checks in checks.

Example: The health status of the server is DOWN because at least one detailed health check is not healthy.

{
  "status": "DOWN",
  "message": "At least one detailed health check is not healthy",
  "checks": {
    "fileStorage": {
      "status": "UP",
      "time": "2025-08-13T11:09:41Z"
    },
    "documentStorage": {
      "status": "DOWN",
      "message": "REDIS: Connection to 'localhost/127.0.0.1:6379' lost",
      "time": "2025-08-13T11:09:41Z"
    },
    "sessionStorage": {
      "status": "DOWN",
      "message": "REDIS: Connection to 'localhost/127.0.0.1:6379' lost",
      "time": "2025-08-13T11:09:41Z"
    }
  }
}