# Service routes

> Health checks, the dataset list and the calling key.

Page: https://docs.aggre.org/api/data/service · Section: API reference · All pages: https://docs.aggre.org/llms.txt

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](#healthz): `GET /healthz`
- [Readiness](#readyz): `GET /readyz`
- [The datasets and where to read them](#listDatasets): `GET /v1/datasets`
- [The calling key and its usage](#whoami): `GET /v1/whoami`

## Liveness {#healthz}

`GET /healthz`

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

**Example**

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

**Response** `200`: `HealthResponse`.

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | `ok` \| `unavailable` | yes |  |
| `checks` | object | no | readyz: postgres, clickhouse, and finance_db / legal_db when configured. |

## Readiness {#readyz}

`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**

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

**Response** `200`: `HealthResponse`.

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | `ok` \| `unavailable` | yes |  |
| `checks` | object | no | readyz: postgres, clickhouse, and finance_db / legal_db when configured. |

**Errors**: `503`, in the shared envelope ([Errors](https://docs.aggre.org/concepts/errors.md)).

## The datasets and where to read them {#listDatasets}

`GET /v1/datasets`

**Example**

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

**Response** `200`: `DatasetsResponse`.

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | array of `Dataset` | yes |  |

**Errors**: `400`, `401`, `403`, `429`, `503`, in the shared envelope ([Errors](https://docs.aggre.org/concepts/errors.md)).

## The calling key and its usage {#whoami}

`GET /v1/whoami`

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

**Example**

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

**Response** `200`: `WhoAmIResponse`.

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | `WhoAmI` | yes |  |

**Errors**: `400`, `401`, `403`, `429`, `503`, in the shared envelope ([Errors](https://docs.aggre.org/concepts/errors.md)).