Health

Liveness check for the API and the dataset behind it. One of two paths served without a key, and the only endpoint that is never rate-limited or metered.

GET/v1/health

GEThttps://api.hyperjobs.io/v1/health

Is the API up and is the dataset behind it readable. One of two paths served without a key — the other is /openapi.json, the generated spec — and the only endpoint that isn't rate-limited.

# No Authorization header. That's not an omission.
curl https://api.hyperjobs.io/v1/health

Query parameters#

None. Anything you send is ignored.

Response#

ok

boolean

true when the API is serving. The endpoint doesn't return a 200 with ok: false — if the service is unhealthy you get a connection failure or a 500, not a negative report.

jobs

integer

Live postings — non-duplicate and non-expired. The same number /v1/meta reports — see below.

version

string

API version, e.g. "1.0.0". Matches version on /v1/meta.

Response

{ "ok": true, "jobs": 596768, "version": "1.0.0" }

That's the whole response. No component breakdown, no latency figures.

No key required#

This endpoint takes no authentication. A key is ignored if you send one — not rejected, just unused. It's also the only endpoint outside the rate limit: calls here don't count against your quota and can't return a 429, so you can poll it as often as your monitoring needs.

/openapi.json — the generated OpenAPI 3.1 spec — is served without a key too, so tooling can fetch the contract before it has credentials. Everything else requires one.

It can't validate an API key

Because it never reads one. A 200 from /v1/health tells you the API is up and says nothing about whether your key works — an expired, revoked, or misspelled key gets exactly the same response as a good one.

To check a key, call an endpoint that requires one and look for a 401. Verifying a key has the recipe; /v1/meta is the cheap choice.

Use it for liveness probes#

This is what the endpoint is for. It's free, unauthenticated, and does no filtering or sorting, which makes it the correct target for a health check, a load-balancer probe, or an uptime monitor.

BASH

# Kubernetes, ECS, an uptime monitor — anything that polls on a schedule.
curl -fsS https://api.hyperjobs.io/v1/health

Don't probe with `/v1/jobs?limit=1`

It's the reflex, and it's the wrong endpoint on three counts: it needs a key, it spends quota on every probe, and it does the full scan and sort that every /v1/jobs query does — so a probe on a short interval burns real work to learn nothing that /v1/health wouldn't have told you for free.

Probe here. Query /v1/jobs when you want jobs.

One count, everywhere#

jobs here is the live count — non-duplicate, non-expired — and it's the same number /v1/meta reports. (In a pre-release draft the two disagreed: health counted every row, duplicates and expired included, and ran a few thousand higher.) A dashboard can quote this number as "jobs available" without overstating.

A monitor that alerts on jobs dropping is reasonable — it going to zero or falling sharply means something is wrong. For the source breakdown, per-field coverage, and freshness, you still want /v1/meta, which needs a key.

For freshness rather than liveness, use newest from /v1/meta. /v1/health will happily report ok on a dataset that stopped updating hours ago — it checks that the data is readable, not that it's current. The two alerts answer different questions and you want both.