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, with request and response schemas, every error code and examples:
curl -O https://hotcfg.run/openapi.jsonImport it into Postman, Insomnia or Bruno, or generate a client:
npx @openapitools/openapi-generator-cli generate -i https://hotcfg.run/openapi.json -g typescript-fetch -o src/hotcfgFor reading config in an app, you don't need a client: use the fetching recipes.
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:
{
"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" }]
}
}Last updated 10 November 2026