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:

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.

Endpoints

MethodPathDoes
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}/historyList versions
POST/v1/{org}/{bin}/promotePromote between environments
POST/v1/{org}/{bin}/rollbackRoll back
POST/v1/{org}/{bin}/unpublishUnpublish an environment
DELETE/v1/{org}/{bin}/environments/{env}Delete an environment
GET/v1/{org}/{bin}/settingsGet a bin's settings
PATCH/v1/{org}/{bin}/settingsChange a bin's settings
GET/v1/{org}/{bin}/payloadRead the stored payload, uncached
GET/v1/binsList bins
POST/v1/binsCreate a bin
GET/v1/auth/meDescribe the key
GET/v1/organizations/{id}/usagePlan, usage and limits
GET/v1/organizations/{id}/exportExport every bin, with history
GET/v1/organizations/{id}/keysList active keys
POST/v1/organizations/{id}/keysCreate 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}/rotateRotate a key's secret
GET/v1/plansPlans 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. Rate limits are in Limits.

Last updated 10 November 2026