Health check

GET https://app.speybooks.com/api/v1/health/

Check the operational status of all SpeyBooks subsystems. Performs four subsystem checks in sequence:

  1. API — always operational if this endpoint responds (latency fixed at 0)
  2. Database — executes SELECT 1 with a 3-second timeout. Marked degraded if latency exceeds 1000ms, outage if the query fails or times out
  3. Email (SES) — calls AWS SES GetSendQuota with a 5-second timeout. This verifies both credentials and service connectivity. Timeout without error is degraded; credential or connection failure is outage
  4. Auth — self-check POST to the login endpoint with dummy credentials. Expects 400 or 401 as proof the auth pipeline is operational. 429 (rate limited) is also accepted. Other status codes are degraded; connection failure or abort is outage

The response includes per-service latency in milliseconds, the current 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

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

Error codes

503 One or more services are in outage.