Server health

One address tells you whether the server is well. You will be able to use it for a monitor and to read each field.

Before you start #

No sign-in is needed. Public routes allow 120 requests a minute for each address.

Steps #

1. Call GET /health. It answers at /api/v1/health and at /health, so a monitor can use the short path.
2. Read the answer:
   • ok: true when the database passes a quick integrity check and the launch check found no problem.
   • version: the API version, v1.
   • time: the server time in UTC.
   • safe_mode: true when the server is read-only after repeated crashes.
   • banner: "The app needs your help" when safe mode or a failed launch check applies, otherwise empty.
3. The public answer does not name the program version or the licence state. Sign in and call GET /me for app_version and licence (active, grace, read_only or unchecked).
4. Treat ok: false, safe_mode: true or licence: read_only as a reason to act.

What to do for each #

• ok: false: see "Server down or restoring a backup".
• safe_mode: true: see "Safe mode, crashes and the Restored your last session bar".
• licence: read_only: see "How licence checks work".

Good to know #

The server answers 200 even when ok is false, so a monitor should read the field. Every response also carries an X-Request-Id header. Quote it when you contact support.

GET /me also shows safe_mode, the banner and a safety block. Owners and managers see the path of the newest crash log and, after a failed launch check, the newest backup to restore.

GET /openapi.json describes every call in OpenAPI form. It holds no secrets.

If something goes wrong #

• No answer at all: the server is stopped or the address is wrong. See the playbook.
• 429: a monitor polls too fast. Poll every 30 seconds or slower.