# Retrieve the List discovery index

> Returns the manifest of Public List discovery: every non-empty bucket with its path and List count.

`GET /lists` on `https://api.mediux.io`

Fetch the manifest, then fetch each bucket (re-fetching with `If-None-Match` after the hourly refresh answers `304 Not Modified` while a bucket is unchanged). Bucket `xx` lists the Public Lists whose List ID starts with those two lower-case hexadecimal digits. Sort the entries locally by `updatedAt` or `subscriberCount`. A List is listed while it is public and its owner is not hidden, banned or a system account. Names, item counts, Subscriber counts and change times refresh hourly, except that a List made private or deleted, and the Lists of a banned or hidden owner, leave at once. The manifest is served with `Cache-Control: public, no-cache`, so send `If-None-Match` and expect `304 Not Modified` while nothing changed.

## Responses

### 200

The List discovery manifest.

- `data` (array of object, required)
  - `chunk` (integer | string, required)
  - `path` (string (starts_with), required)
  - `itemCount` (integer, required)
  - `updatedAt` (string, required): ISO 8601 UTC instant with milliseconds, such as `2026-11-14T15:03:02.000Z`.
- `meta` (object, required)
  - `scheme` (string, required): One of "idRange", "uuidPrefix".
  - `chunkSize` (integer)
  - `chunkCount` (integer, required)
  - `totalItems` (integer, required)

### 304

Not modified. The `If-None-Match` validator still matches; no body.

### 400

The path is not a valid route, or the request carried a query string or body.

### 404

The resource does not exist or is not public.

### 405

Only `GET`, `HEAD` and `OPTIONS` are supported.

### 429

Too many cache misses from this address. Retry after the `Retry-After` delay.

### 503

Temporarily unavailable. Retry after the `Retry-After` delay.

## Example response (200)

```json
{
  "data": [
    {
      "chunk": "18",
      "path": "/lists/chunks/18",
      "itemCount": 1,
      "updatedAt": "2026-11-18T00:50:08.022Z"
    },
    {
      "chunk": "1f",
      "path": "/lists/chunks/1f",
      "itemCount": 1,
      "updatedAt": "2026-11-18T00:50:05.083Z"
    },
    {
      "chunk": "3b",
      "path": "/lists/chunks/3b",
      "itemCount": 2,
      "updatedAt": "2026-10-28T07:03:11.678Z"
    }
  ],
  "meta": {
    "scheme": "uuidPrefix",
    "chunkCount": 7,
    "totalItems": 8
  }
}
```
