API

# Writing

Publish, patch, promote, roll back and manage bins over HTTP.

All writes need a secret key (`sk_live_…`) or a dashboard session. Bodies are JSON, at most your plan's payload size (see [Limits](https://hotcfg.run/docs/reference/limits)). Every write is checked against the bin's [schema](https://hotcfg.run/docs/guides/schemas).

PUT

```
curl -X PUT "https://api.hotcfg.run/v1/acme/mobile-flags?env=staging" \
  -H "Authorization: Bearer $HOTCFG_SECRET_KEY" \
  -d '{"features": {"checkout_v2": true}}'

# {"bin_id":"mobile-flags","environment":"staging","version":4,"hash":"…"}
```

## Bins

| Request | Does |
| --- | --- |
| `POST /v1/bins` | Create a bin in your key's organization: `{"id", "name", "description", "schema", "is_public"}`. |
| `GET /v1/bins` | List bins, most recently updated first, with `total`. Optional `q`, `updated_after`, `updated_before`, and `limit` (1–100) with `offset`. |
| `DELETE /v1/:org/:bin` | Delete the bin with all environments and history. |

## Versions

| Request | Does |
| --- | --- |
| `PUT /v1/:org/:bin?env=` | Publish the body as the next version. |
| `PATCH /v1/:org/:bin?env=` | Apply a JSON Merge Patch (RFC 7386) to the current version; `null` deletes a key. |
| `POST /v1/:org/:bin/promote` | Copy one environment's current version to another: `{"from_env", "to_env"}`. |
| `POST /v1/:org/:bin/rollback?env=&to=N` | Publish version N again, as a new version. |
| `GET /v1/:org/:bin/history?env=` | List versions, newest first, with authors. |
| `POST /v1/:org/:bin/unpublish` | Take an environment offline: `{"env": "staging"}`. History is kept. |
| `DELETE /v1/:org/:bin/environments/:env` | Delete the environment and its whole history. |

## Keys

| Request | Does |
| --- | --- |
| `PATCH /v1/organizations/:id/keys/:key_id` | Rename a key: `{"name"}`. Its role and limits never change. |
| `POST /v1/organizations/:id/keys/:key_id/rotate` | Replace a key's secret; the old one stops working at once. Returns the new `key`, once. |

Last updated 5 November 2026
