Service routes

Routes about the service itself. /healthz and /readyz need no key; /v1/datasets lists every dataset with the path to read it, and /v1/whoami describes the key you call with (never its secret) and what it has used.

On this page:

• Liveness: GET /healthz
• Readiness: GET /readyz
• The datasets and where to read them: GET /v1/datasets
• The calling key and its usage: GET /v1/whoami

Liveness#

GET /healthz

No auth. The process is up; nothing is checked.

Example

curl -s "https://api.aggre.org/healthz" \
  -H "Authorization: Bearer $AGGRE_API_KEY"

Response 200: HealthResponse.

Readiness#

GET /readyz

No auth. Postgres and ClickHouse answer (and finance_db / legal_db when configured). 503 with the same body shape when one does not.

Example

curl -s "https://api.aggre.org/readyz" \
  -H "Authorization: Bearer $AGGRE_API_KEY"

Response 200: HealthResponse.

Errors: 503, in the shared envelope (Errors).

The datasets and where to read them#

GET /v1/datasets

Example

curl -s "https://api.aggre.org/v1/datasets" \
  -H "Authorization: Bearer $AGGRE_API_KEY"

Response 200: DatasetsResponse.

Errors: 400, 401, 403, 429, 503, in the shared envelope (Errors).

The calling key and its usage#

GET /v1/whoami

Never returns the secret. Counts as a normal request against the key.

Example

curl -s "https://api.aggre.org/v1/whoami" \
  -H "Authorization: Bearer $AGGRE_API_KEY"

Response 200: WhoAmIResponse.

Errors: 400, 401, 403, 429, 503, in the shared envelope (Errors).