Service endpoints

HealthPermalink to this section

Use health as a liveness probe for your own monitoring. It needs no key and is not metered, but poll it at a sensible interval rather than on a tight loop.

Health reports a count of markets in the current feed alongside a markets_in_feed_is_estimate boolean. When that flag is true the count is an estimate for orientation and not a guarantee of exact coverage, so do not reconcile against it.

CapabilitiesPermalink to this section

Capabilities is the endpoint to read at start-up rather than hard-coding assumptions about coverage. Reading it means your integration notices a change instead of silently working from a stale idea of what is available.

Capabilities checks the dependencies activation actually rests on: key storage, request counters, quota enforcement and key issuance. It reports activation as complete, partial, absent or unavailable, so a partial or absent report means some of that machinery is not in place yet.

Readiness distinguishes absent from unknown. Absent means a specific dependency was checked and is not in place. Unknown or unavailable means the check itself could not be completed and should not be read as absence. An absent result for one routine is a statement about that routine only: it is not evidence that the other routines are missing, so read each entry on its own rather than collapsing the report into a single yes or no.

OpenAPI documentPermalink to this section

The OpenAPI document is the authoritative contract and can be fed straight into a client generator. Where these pages and the document ever disagree, the document is correct and we will fix the page.

# No key required on these three paths.
curl "$RIDDLE_API_BASE/v1/health"
curl "$RIDDLE_API_BASE/v1/capabilities"
curl "$RIDDLE_API_BASE/v1/openapi.json"