Health
Unauthenticated health, liveness, and readiness endpoints for monitoring the Tokeflow API and its dependencies.
The health endpoints report whether the Tokeflow API is running and whether its dependencies are reachable. Use them for uptime monitoring, load-balancer health checks, and orchestrator probes — /health/live and /health/ready map directly onto Kubernetes-style liveness and readiness probes.
These endpoints behave differently from the rest of the API. They require no authentication, and they do not wrap their responses in the standard success/data envelope: the body is a bare health report, and the HTTP status code carries the verdict — 200 when everything is up, 503 when any check fails.
Because the HTTP status code alone tells you whether the service is healthy, most monitoring systems only need to check for a 200. Parse the body when you want to know which dependency is failing.
The health report object
All three endpoints return the same report shape:
| Field | Type | Description |
|---|---|---|
status | string | Overall result — ok when every check passes, error when at least one fails. |
info | object | null | Checks that are currently healthy, keyed by check name. Each entry contains at least a status field. |
error | object | null | Checks that are currently failing, keyed by check name. Each entry contains at least a status field, plus extra detail such as a message. Empty when everything is healthy. |
details | object | Every check, healthy or not, keyed by check name — the union of info and error. Each entry contains at least a status field. |
The keys inside info, error, and details are the names of the individual checks (for example database). Each check entry always has a status (up or down) and may carry additional fields describing the failure.
Endpoints
GET/api/v1/health
Auth: None. This endpoint is publicly accessible — no API key required.
Runs the full health check: the API process plus its backing dependencies. Returns 200 with every check under info when the service is healthy, or 503 with the failing checks under error when it is not.
Example request
curl https://api.tokeflow.com/api/v1/healthExample response — 200 OK
{
"status": "ok",
"info": {
"database": {
"status": "up"
}
},
"error": {},
"details": {
"database": {
"status": "up"
}
}
}Example response — 503 Service Unavailable
{
"status": "error",
"info": {
"database": {
"status": "up"
}
},
"error": {
"cache": {
"status": "down",
"message": "Could not connect"
}
},
"details": {
"database": {
"status": "up"
},
"cache": {
"status": "down",
"message": "Could not connect"
}
}
}GET/api/v1/health/live
Auth: None. This endpoint is publicly accessible — no API key required.
Liveness probe: reports whether the API process itself is running and able to respond. Point restart-oriented checks here — if this endpoint stops returning 200, the process should be restarted.
Example request
curl https://api.tokeflow.com/api/v1/health/liveExample response — 200 OK
{
"status": "ok",
"info": {
"database": {
"status": "up"
}
},
"error": {},
"details": {
"database": {
"status": "up"
}
}
}GET/api/v1/health/ready
Auth: None. This endpoint is publicly accessible — no API key required.
Readiness probe: reports whether the service is ready to receive traffic, including the state of its dependencies. Point traffic-gating checks here — a load balancer or orchestrator should stop routing requests to an instance while this endpoint returns 503, without restarting it.
Example request
curl https://api.tokeflow.com/api/v1/health/readyExample response — 200 OK
{
"status": "ok",
"info": {
"database": {
"status": "up"
}
},
"error": {},
"details": {
"database": {
"status": "up"
}
}
}Example response — 503 Service Unavailable
{
"status": "error",
"info": {
"database": {
"status": "up"
}
},
"error": {
"cache": {
"status": "down",
"message": "Could not connect"
}
},
"details": {
"database": {
"status": "up"
},
"cache": {
"status": "down",
"message": "Could not connect"
}
}
}Errors
The health endpoints do not use the standard error envelope. There are only two outcomes:
| HTTP | Meaning |
|---|---|
200 | Every check passed. status is ok and error is empty. |
503 | One or more checks failed. status is error and the failing checks appear under error (and details). |
For the envelope used by every other endpoint, see Errors.
Related
- Errors — the standard error envelope used by the rest of the API.
- Authentication — how authenticated endpoints verify your API keys.
- How Tokeflow works — the orchestration architecture these checks monitor.