API

# API reference

Every endpoint of the hotcfg HTTP API, and its OpenAPI 3.1 description for clients, Postman and code generators.

The API is at `https://api.hotcfg.run`. Bodies are JSON. Authenticate with `Authorization: Bearer <key>`: a secret key (`sk_live_…`) to write, or a publishable key (`pk_live_…`) to read private bins. Public bins need no key.

## OpenAPI

The whole API is described in one OpenAPI 3.1 file, [openapi.json](https://hotcfg.run/openapi.json), with request and response schemas, every error code and examples:

terminal

```
curl -O https://hotcfg.run/openapi.json
```

Import it into Postman, Insomnia or Bruno, or generate a client:

terminal

```
npx @openapitools/openapi-generator-cli generate -i https://hotcfg.run/openapi.json -g typescript-fetch -o src/hotcfg
```

For reading config in an app, you don't need a client: use the [fetching recipes](https://hotcfg.run/docs/guides/fetching).

## Endpoints

| Method | Path | Does |
| --- | --- | --- |
| `GET` | `/v1/{org}/{bin}` | Read a bin |
| `PUT` | `/v1/{org}/{bin}` | Publish a new version |
| `PATCH` | `/v1/{org}/{bin}` | Publish a merge patch |
| `DELETE` | `/v1/{org}/{bin}` | Delete a bin |
| `GET` | `/v1/{org}/{bin}/history` | List versions |
| `POST` | `/v1/{org}/{bin}/promote` | Promote between environments |
| `POST` | `/v1/{org}/{bin}/rollback` | Roll back |
| `POST` | `/v1/{org}/{bin}/unpublish` | Unpublish an environment |
| `DELETE` | `/v1/{org}/{bin}/environments/{env}` | Delete an environment |
| `GET` | `/v1/{org}/{bin}/settings` | Get a bin's settings |
| `PATCH` | `/v1/{org}/{bin}/settings` | Change a bin's settings |
| `GET` | `/v1/{org}/{bin}/payload` | Read the stored payload, uncached |
| `GET` | `/v1/bins` | List bins |
| `POST` | `/v1/bins` | Create a bin |
| `GET` | `/v1/auth/me` | Describe the key |
| `GET` | `/v1/organizations/{id}/usage` | Plan, usage and limits |
| `GET` | `/v1/organizations/{id}/export` | Export every bin, with history |
| `GET` | `/v1/organizations/{id}/keys` | List active keys |
| `POST` | `/v1/organizations/{id}/keys` | Create a key |
| `PATCH` | `/v1/organizations/{id}/keys/{key_id}` | Rename a key |
| `DELETE` | `/v1/organizations/{id}/keys/{key_id}` | Revoke a key |
| `POST` | `/v1/organizations/{id}/keys/{key_id}/rotate` | Rotate a key's secret |
| `GET` | `/v1/plans` | Plans and their limits |

Bins created before organization URLs also answer at `/v1/bins/{id}`, on every bin route.

## Errors

Errors are JSON with a stable `code` to match on, a `message` for people, and sometimes `details`:

422

```
{
  "error": {
    "code": "schema_validation_failed",
    "message": "payload failed schema validation at \"/limits/max_upload_mb\": expected integer, but got string",
    "details": [{ "instance_location": "/limits/max_upload_mb", "keyword_location": "/properties/limits/properties/max_upload_mb/type", "message": "expected integer, but got string" }]
  }
}
```

Every code is listed in [Errors](https://hotcfg.run/docs/reference/errors). Rate limits are in [Limits](https://hotcfg.run/docs/reference/limits).

Last updated 10 November 2026
