API

# Reading a bin

GET a bin's JSON, choose the environment or version, revalidate with ETags.

GET

```
curl "https://api.hotcfg.run/v1/acme/mobile-flags?env=staging"
```

The response body is the stored JSON, byte for byte.

## Parameters

| Parameter | Values | Effect |
| --- | --- | --- |
| `env` | `production` (default), `staging`, `development` | Which environment to read. |
| `v` | `latest` (default) or a number | Read a pinned version. Pinned URLs never change, so they're cached at the edge and served for up to a week if our servers fail. |
| `query` | a jq filter, e.g. `.features.checkout` | Return only the filter's result. See [Querying with jq](https://hotcfg.run/docs/guides/queries). |
| `delay`, `chaos`, `status` |  | For testing. See [Testing slow and failing networks](https://hotcfg.run/docs/guides/testing-failures). |

## Caching and ETags

Responses carry an `ETag` and an `X-Hotcfg-Version` header. Send `If-None-Match` with the ETag to get a bodyless `304` when nothing changed.

Public bins are cached at Cloudflare's edge and purged on every publish, promote, rollback and unpublish, including `?query=` variants. Private bins are never cached at the edge. Responses with testing parameters are never cached.

## Private bins

Private bins are on Pro.

Send a key as a bearer token:

header

```
curl https://api.hotcfg.run/v1/acme/private-config \
  -H "Authorization: Bearer pk_live_…"
```

Without a valid key, a private bin answers `404`, the same as a bin that doesn't exist, so its existence isn't revealed.

## Reads are unlimited

No plan counts or caps reads. Reads that reach hotcfg's servers (private bins, queries, testing parameters and cache misses) are limited to 600 a minute per IP address. See [Limits](https://hotcfg.run/docs/reference/limits).

Last updated 10 November 2026
