diagnose

Produces a diagnosis of the server: its version, the system it runs on, its license, and the options it was started with.

Route: POST /api/v2/system/diagnose
Category: system
Authentication: required, with the API token
Answer: a single JSON envelope

A diagnosis helps to check that the right version is deployed, that the server runs with the options you meant, and how long its license remains valid, see Diagnostics and Troubleshooting. It reports what the server was started with, not what it is doing now, and it reports no secrets: neither the API token, nor the license itself, nor the signing key, nor the paths of the files that hold them. For the state of the database at the moment, ask health.

Request#

The route takes no body, and ignores one that is sent:

curl \
  -X POST \
  -H "authorization: Bearer secret" \
  http://localhost:3000/api/v2/system/diagnose

Answer#

The answer is a single envelope of the type event, which holds a CloudEvent of the type io.eventsourcingdb.api.server-diagnosed. Its data holds four sections:

Section	Fields
`license`	`id`, `type`, and `licensee`; `issuedAt` and `expiresAt`; `remainingDurationInSeconds`; `status`, which is `valid` or `expired`; and `maxEventCapacity`, the number of events the license permits.
`options`	Whether HTTP and HTTPS are enabled, `isHttpEnabled` and `isHttpsEnabled`, and their ports, `httpPort` and `httpsPort`; the data directory, `dataDirectory`, and whether it is temporary, `isDataDirectoryTemporary`; `heartbeatIntervalInSeconds`; `areEventSchemasRequired`; `isDevelopmentModeEnabled`; `isEventSigningEnabled`; `isReadOnly`, which says whether the server was started in read-only mode, not whether it is in read-only mode now; `rateLimitRequestsPerSecond`; and `withUi`.
`system`	`operatingSystem` and `architecture`; `cpuCores`, the cores of the host, next to `usableCpuCores`, those the server may use, which a CPU limit of a container lowers; and `memorySize`, the memory of the host in bytes.
`version`	`eventSourcingDb`, the version of the server, and `revision`, the revision it was built from.

Shortened to two of its four sections, the request above is answered for a server that runs on the evaluation license, which EventSourcingDB uses without a license of its own, with:

{
  "type": "event",
  "data": {
    "specversion": "1.0",
    "id": "01a180d9-d578-73fb-8162-5d9ecb1f124a",
    "source": "https://www.eventsourcingdb.io",
    "type": "io.eventsourcingdb.api.server-diagnosed",
    "subject": "/api/v2/system/diagnose",
    "time": "2026-10-28T04:52:02.040258Z",
    "datacontenttype": "application/json",
    "data": {
      "license": {
        "expiresAt": "2027-10-28T04:51:55.709093Z",
        "id": "00000000-0000-0000-0000-000000000000",
        "issuedAt": "2026-10-28T04:51:55.709093Z",
        "licensee": "n/a",
        "maxEventCapacity": 25000,
        "remainingDurationInSeconds": 31535993.66884183,
        "status": "valid",
        "type": "evaluation"
      },
      "system": {
        "architecture": "arm64",
        "cpuCores": 8,
        "memorySize": 25769803776,
        "operatingSystem": "darwin",
        "usableCpuCores": 8
      }
    }
  }
}

Status Codes#

The server answers with a status code other than 200 where it cannot take the request at all, as described in Errors:

401: The API token is missing or wrong.
429: Too many requests were sent; the answer says when to try again.
500: The server failed unexpectedly.
503: The server is shutting down.