Health / Status API

Two open endpoints for monitors and dashboards: a single-purpose health probe and a structured per-component status snapshot.

Both endpoints are open (no API key required), cached for ~15 s at the edge plus 30 s in-process so a flood of probes never burns through to the underlying checks, and safe to hit from any host (no rate-limit attribution).

`GET /api/verify`: minimal health

Use when all you need is "is links.et alive". Always returns 200 with a tiny JSON body.

curl https://links.et/api/verify

{ "ok": true, "ts": "2026-06-11T19:23:11.482Z" }

Don't use this to check whether an upstream (telebirr, CBE, …) is healthy; this endpoint only reports on links.et itself.

`GET /api/status`: structured per-component status

Use when you want to know which upstream is degraded or what response times look like right now.

curl https://links.et/api/status

Response

HTTP	When
`200`	Overall status is `operational` or `slow`
`503`	Overall status is `down` (at least one component returned a 5xx or timed out)

{
	"ok": true,
	"status": "operational",
	"checkedAt": "2026-06-11T19:23:11.482Z",
	"cached": true,
	"components": [
		{
			"name": "verify-web (this service)",
			"host": "links.et",
			"group": "internal",
			"status": "operational",
			"responseMs": 0,
			"httpStatus": 200,
			"error": null
		},
		{
			"name": "Postgres (auth + API keys)",
			"host": "127.0.0.1:5432",
			"group": "internal",
			"status": "operational",
			"responseMs": 35,
			"httpStatus": null,
			"error": null
		},
		{
			"name": "Telebirr — transactioninfo.ethiotelecom.et",
			"host": "transactioninfo.ethiotelecom.et",
			"group": "upstream",
			"status": "operational",
			"responseMs": 522,
			"httpStatus": 200,
			"error": null
		}
	]
}

Field reference

Field	Type	Notes
`ok`	boolean	`true` unless overall status is `down`
`status`	enum	`operational` \| `slow` \| `down`; worst across all components
`checkedAt`	ISO timestamp	When the underlying probe round was last taken
`cached`	boolean	`true` if the snapshot came from the in-process 30 s cache
`components[].name`	string	Human label (e.g. `"Telebirr — transactioninfo.ethiotelecom.et"`)
`components[].host`	string	Upstream host or internal address
`components[].group`	enum	`internal` (the links.et service itself) or `upstream`
`components[].status`	enum	Per-component `operational` / `slow` / `down`
`components[].responseMs`	number \| null	Probe round-trip time
`components[].httpStatus`	number \| null	HTTP status the upstream returned (or `null` for non-HTTP probes like Postgres)
`components[].error`	string \| null	Network or timeout error message when the probe failed

Classification rules (same as the human-readable /status page)

down: probe failed or upstream returned HTTP >= 500
slow: probe succeeded but took longer than the per-component slow threshold (typically 1.5 s)
operational: probe succeeded under threshold

`HEAD /api/status`: uptime-monitor friendly

Same status code semantics as GET /api/status, no body. Cheapest possible probe; recommended for monitors that only need to react to 200 vs 503.

curl -I https://links.et/api/status
# HTTP/2 200
# cache-control: public, max-age=15, s-maxage=15

Polling cadence

The in-process snapshot refreshes every 30 s and the public response is cache-controlled for 15 s. A polling interval between 30 s and 5 minutes is plenty; anything faster gets you the same cached snapshot, just with extra bandwidth.

Health / Status API

GET /api/verify: minimal health

GET /api/status: structured per-component status