Health check

GEThttps://app.speybooks.com/api/v1/health/

Check the operational status of the SpeyBooks subsystems. Performs four sub-checks:

  1. API: always operational if this endpoint responds (latency fixed at 0). This is the liveness signal.
  2. Database: executes SELECT 1 with a 3-second timeout. Degraded if latency exceeds 1000ms; outage if the query fails or times out.
  3. Email: a lightweight email-provider reachability call with a 5-second timeout, verifying credentials and connectivity. Timeout without error is degraded; a credential or connection failure is outage.
  4. Auth: a probe of the login endpoint with throwaway credentials. A 400 or 401 proves the auth pipeline is processing; a 429 (rate limited) is also accepted. Other status codes are degraded; a connection failure or abort is outage.

The response carries per-service latency in milliseconds, the API version, and a UTC timestamp.

Degraded example:

{
  "success": true,
  "data": {
    "status": "degraded",
    "services": {
      "api": { "status": "operational", "latency": 0 },
      "database": { "status": "degraded", "latency": 1523, "message": "Slow response" },
      "email": { "status": "operational", "latency": 310 },
      "auth": { "status": "operational", "latency": 45 }
    }
  }
}

Outage example (HTTP 503):

{
  "success": true,
  "data": {
    "status": "outage",
    "services": {
      "api": { "status": "operational", "latency": 0 },
      "database": { "status": "outage", "message": "Connection failed" },
      "email": { "status": "operational", "latency": 200 },
      "auth": { "status": "operational", "latency": 50 }
    }
  }
}

Monitoring integration: This endpoint is designed for uptime services (e.g. UptimeRobot, Pingdom). Alert on HTTP 503 for outages. For degraded detection, parse the JSON body and check per-service statuses.

Response

200All services operational or degraded. Returns individual service status, latency, and an overall rollup.
Show response fields
servicesobject
Individual service health checks.
Show child attributes
apiobject
Show child attributes
latencyinteger
Response time in milliseconds. Always 0 for the API service itself.
statusstring
API process status. Always operational if this response is returned.
authobject
Show child attributes
latencyinteger
Auth endpoint response time in milliseconds.
messagestringnullable
Human-readable status message when degraded or outage.
statusstring
Authentication service status. Verified by probing the login endpoint.
databaseobject
Show child attributes
latencyinteger
Database query response time in milliseconds.
messagestringnullable
Human-readable status message when degraded or outage.
statusstring
PostgreSQL connection status. Degraded if latency exceeds 1000ms.
emailobject
Show child attributes
latencyinteger
SES GetSendQuota response time in milliseconds.
messagestringnullable
Human-readable status message when degraded or outage.
statusstring
AWS SES email service status.
statusstring
Overall system status. Outage if any service is down; degraded if any service is slow.
operationaldegradedoutage
timestampstringdate-time
ISO 8601 timestamp of the health check.
versionstring
API version string.

Error codes

503One or more services are in outage.