Health

The Health module provides uptime/probing endpoints for external monitoring (Kubernetes, load balancer, Sentry, etc.) and one admin endpoint to toggle the system-wide maintenance mode. The user-facing endpoints are @Public() and do not pass through the global ResponseInterceptor — the response is returned as-is via res.json(...). The admin endpoint follows the standard envelope and is guarded by an ACL permission.

Property	Value
Base URL	{HOST}/v1
Auth	Public for probe endpoints · Bearer JWT for admin maintenance toggle
Content-Type	application/json
Error envelope	Probe endpoints use the raw shape (see per-endpoint) · Admin endpoint uses the standard { "message", "statusCode", "error" }
Validation	Global ValidationPipe · whitelist: true, forbidNonWhitelisted: true
Related modules	infrastructure, monitoring (Sentry, k8s probes)
Document version	v1 · 2026-05-20
Audience	Internal FE devs (status page widget) + ops/infra

Summary

Public endpoints do not require Bearer and are used for uptime monitoring / readiness probes. The admin endpoint POST /admin/maintenance/toggle enables / disables the in-memory maintenanceMode flag in HealthService — when active, all probe endpoints return maintenance status (HTTP 503).

Method	Path	Auth	Summary
GET	/v1/health	public	Full status (DB, Mongo, uptime, version)
GET	/v1/status	public	Simple status (ok / maintenance / degraded)
GET	/v1/ping	public	Simple ping-pong
GET	/v1/ready	public	Kubernetes readiness probe
GET	/v1/live	public	Kubernetes liveness probe
GET	/v1/debug-sentry	public	Trigger a synthetic Sentry error (dev only)
POST	/v1/admin/maintenance/toggle	bearer	Enable/disable maintenance mode (admin)

Important FE notes

• The user-facing probe endpoints are not wrapped in the { status, statusCode, message, data } envelope — the controller calls res.json(...) directly. FE should parse the raw shape exactly as shown in each card.
• The admin POST /admin/maintenance/toggle endpoint still passes through the global interceptor → the response is wrapped in the standard envelope.
• Maintenance mode is in-memory per-instance — if the backend is running multi-replica, the toggle needs to be propagated to each instance.
• HTTP status reflects the system condition: 200 ok, 503 maintenance, 500 degraded (some service unhealthy).

---

GET /v1/health public

Full system status: MySQL + MongoDB connectivity, uptime in seconds, version, and timestamp. Suitable for a status dashboard or in-depth check.

public

Response — 200 OK (all services healthy)

{
  "status": "ok",
  "message": "All systems operational",
  "timestamp": "2026-05-20T10:30:00.000Z",
  "version": "1.0.0",
  "services": {
    "database": { "status": "healthy", "responseTime": 15 },
    "mongodb": { "status": "healthy", "responseTime": 8 }
  },
  "uptime": 3600
}

Response — 503 Service Unavailable (maintenance mode active)

{
  "status": "maintenance",
  "message": "Service is currently under maintenance. Please try again later.",
  "timestamp": "2026-05-20T10:30:00.000Z",
  "version": "1.0.0",
  "services": {
    "database": { "status": "healthy" },
    "mongodb": { "status": "healthy" }
  },
  "uptime": 3600
}

Response — 500 Internal Server Error (degraded — one service unhealthy)

{
  "status": "degraded",
  "message": "Some services are experiencing issues",
  "timestamp": "2026-05-20T10:30:00.000Z",
  "version": "1.0.0",
  "services": {
    "database": { "status": "unhealthy" },
    "mongodb": { "status": "healthy", "responseTime": 8 }
  },
  "uptime": 3600
}

The response shape is not wrapped in the global envelope — parse it directly as the object above. uptime is in seconds since the process booted. responseTime is in milliseconds.

---

GET /v1/status public

Simple status containing only status + message. Useful for monitoring that only needs to know OK/not without per-service detail.

public

Response — 200 OK

{ "status": "ok", "message": "API is healthy and operational" }

Response — 503 Service Unavailable (maintenance)

{ "status": "maintenance", "message": "API is currently under maintenance. Please try again later." }

Response — 500 Internal Server Error (degraded)

{ "status": "degraded", "message": "API is experiencing issues" }

---

GET /v1/ping public

Basic ping-pong. During maintenance, returns 503; otherwise, always 200 with body { "message": "pong" }.

public

Response — 200 OK

{ "message": "pong", "timestamp": "2026-05-20T10:30:00.000Z" }

Response — 503 Service Unavailable (maintenance)

{ "message": "API is under maintenance", "timestamp": "2026-05-20T10:30:00.000Z" }

---

GET /v1/ready public

Kubernetes-style readiness probe. 200 if the system is ready to accept traffic, 503 if not (maintenance or degraded).

public

Response — 200 OK

{ "status": "ready", "message": "API is ready to accept traffic" }

Response — 503 Service Unavailable

{
  "status": "not-ready",
  "message": "API is not ready to accept traffic",
  "reason": "API is currently under maintenance. Please try again later."
}

The reason field only appears on the 503 response and contains the message from getSimpleStatus().

---

GET /v1/live public

Kubernetes-style liveness probe. Always returns 200 as long as the process is still running — even in maintenance mode (the service is still “alive”).

public

Response — 200 OK

{ "status": "alive", "message": "API is alive" }

---

GET /v1/debug-sentry public

Development-only endpoint: throws a synthetic error (My first Sentry error!) to verify the Sentry integration. Do not call from production FE.

public

Response — 500 Internal Server Error

{
  "message": "Internal server error",
  "statusCode": 500,
  "error": "Internal Server Error"
}

The error is thrown synchronously and caught by the global filter — Sentry will receive an exception event. Only useful for smoke-testing instrumentation.

---

Admin endpoint

The following are admin-only endpoints

The section below is not for calls from end-user apps. Requires Bearer JWT with the can-manage-system ACL permission.

---

POST /v1/admin/maintenance/toggle bearer

Toggle the system-wide maintenance mode. When enabled = true, all public probe endpoints (/health, /status, /ping, /ready) will return maintenance status / HTTP 503 until toggled off.

bearer can-manage-system

Request body — MaintenanceModeDto

Field	Type	Required	Notes
enabled	boolean	✓	true to enable, false to disable
message	string	optional	Custom message returned in the data.message field. Default follows enabled ("System is under maintenance" / "System is operational")

Example request

{ "enabled": true, "message": "Backend upgrade for 30 minutes" }

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Maintenance mode enabled successfully",
  "data": {
    "maintenanceMode": true,
    "timestamp": "2026-05-20T10:30:00.000Z",
    "message": "Backend upgrade for 30 minutes"
  }
}

Errors

Status	When it occurs
400 Bad Request	enabled is not boolean / empty, or there is an unknown field
401 Unauthorized	Bearer/cookie token is invalid
403 Forbidden	Caller lacks can-manage-system permission

Side effects

• Modifies the in-memory maintenanceMode flag in HealthService. Not persistent — restarting the process resets it to the value of env MAINTENANCE_MODE.
• Does not affect DB data; purely gates health probe responses.
• On multi-replica deployments, the toggle must be sent to each instance (or use an external propagation mechanism — currently none).

---

Reference

Enum: HealthStatus.status

• ok — all services healthy → HTTP 200
• maintenance — maintenance flag active → HTTP 503
• degraded — at least one service unhealthy → HTTP 500

Enum: services.{db|mongo}.status

• healthy — test query succeeded
• unhealthy — test query failed (timeout / exception)

Env vars

• API_VERSION — appears in the version field (default 1.0.0)
• MAINTENANCE_MODE=true — initial flag at boot

Standard error envelope (admin endpoint)

{
  "message": "Forbidden resource",
  "statusCode": 403,
  "error": "Forbidden"
}

The user-facing probe endpoints do not use this envelope — the per-endpoint shape is described in each card.

Common HTTP codes

• 200 system ok
• 500 system degraded (DB/Mongo unhealthy)
• 503 maintenance mode active
• 401 admin endpoint without token
• 403 admin endpoint without permission