{
  "openapi": "3.1.0",
  "info": {
    "title": "hotcfg API",
    "version": "1",
    "description": "Remote JSON config for apps. Read bins with any HTTP client; write, promote and roll back with a secret key. Errors are `{\"error\": {\"code\", \"message\", \"details\"}}`; match on `code`. Every route also works at `/v1/bins/{id}` for bins created before organization URLs.\n\nDocs: https://hotcfg.run/docs",
    "contact": {
      "name": "hotcfg support",
      "email": "support@hotcfg.run",
      "url": "https://hotcfg.run/contact"
    },
    "termsOfService": "https://hotcfg.run/terms"
  },
  "servers": [
    {
      "url": "https://api.hotcfg.run"
    }
  ],
  "externalDocs": {
    "description": "hotcfg docs",
    "url": "https://hotcfg.run/docs"
  },
  "security": [
    {
      "bearer": []
    }
  ],
  "tags": [
    {
      "name": "Reading"
    },
    {
      "name": "Writing"
    },
    {
      "name": "Versions"
    },
    {
      "name": "Bins"
    },
    {
      "name": "Keys"
    },
    {
      "name": "Organization"
    }
  ],
  "paths": {
    "/v1/{org}/{bin}": {
      "parameters": [
        {
          "name": "org",
          "in": "path",
          "required": true,
          "description": "The organization's slug. It never changes.",
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9-]{3,40}$"
          },
          "example": "acme"
        },
        {
          "name": "bin",
          "in": "path",
          "required": true,
          "description": "The bin's id, unique in its organization.",
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
          },
          "example": "mobile-flags"
        }
      ],
      "get": {
        "operationId": "readBin",
        "tags": [
          "Reading"
        ],
        "summary": "Read a bin",
        "description": "Returns the stored JSON of one environment, byte for byte. Public bins need no key and are served from Cloudflare's edge, purged on every write. Private bins need a key; without a valid one they answer `404`, like a missing bin.",
        "security": [
          {},
          {
            "bearer": []
          }
        ],
        "parameters": [
          {
            "name": "env",
            "in": "query",
            "description": "The environment. Defaults to `production`.",
            "schema": {
              "type": "string",
              "enum": [
                "production",
                "staging",
                "development"
              ],
              "default": "production"
            }
          },
          {
            "name": "v",
            "in": "query",
            "description": "`latest` or a version number. Pinned versions never change.",
            "schema": {
              "type": "string",
              "pattern": "^(latest|[1-9][0-9]*)$",
              "default": "latest"
            }
          },
          {
            "name": "query",
            "in": "query",
            "description": "A jq filter run on the payload, e.g. `.features.checkout_v2`. Evaluated within 50 ms.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "delay",
            "in": "query",
            "description": "Testing: wait this many milliseconds before answering, at most 10000. Never cached.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 10000
            }
          },
          {
            "name": "chaos",
            "in": "query",
            "description": "Testing: answer `500 simulated_failure` this percentage of the time. Never cached.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Testing: answer with this HTTP status instead. Never cached.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "If-None-Match",
            "in": "header",
            "description": "The `ETag` you have. Unchanged config answers `304` with no body.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The payload.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Any JSON value: whatever was published."
                },
                "example": {
                  "features": {
                    "checkout_v2": true,
                    "new_onboarding": false
                  },
                  "limits": {
                    "max_upload_mb": 50
                  }
                }
              }
            },
            "headers": {
              "ETag": {
                "description": "The SHA-256 of the payload, quoted.",
                "schema": {
                  "type": "string"
                }
              },
              "X-Hotcfg-Version": {
                "description": "The version served.",
                "schema": {
                  "type": "integer"
                }
              },
              "Cache-Control": {
                "description": "Public bins: `public, max-age=60, s-maxage=604800, stale-while-revalidate=3600, stale-if-error=86400`. Private bins: `private, max-age=60`.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "304": {
            "description": "Not modified: the `If-None-Match` ETag is current."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/QueryFailed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Busy"
          }
        }
      },
      "put": {
        "operationId": "publishBin",
        "tags": [
          "Writing"
        ],
        "summary": "Publish a new version",
        "description": "Stores the body as the next version of the environment, after checking it against the bin's JSON Schema, and purges the edge cache. Pushing identical content still makes a new version.",
        "parameters": [
          {
            "name": "env",
            "in": "query",
            "description": "The environment. Defaults to `production`.",
            "schema": {
              "type": "string",
              "enum": [
                "production",
                "staging",
                "development"
              ],
              "default": "production"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "description": "Any JSON value."
              },
              "example": {
                "features": {
                  "checkout_v2": true
                },
                "limits": {
                  "max_upload_mb": 50
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Published.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WriteResult"
                },
                "example": {
                  "bin_id": "mobile-flags",
                  "environment": "staging",
                  "version": 4,
                  "hash": "7ac562a24ad09d989d7a8cc810d64bd108028f013313b206aafba5c182fb951d"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "422": {
            "$ref": "#/components/responses/SchemaFailed"
          },
          "507": {
            "$ref": "#/components/responses/StorageFull"
          }
        }
      },
      "patch": {
        "operationId": "patchBin",
        "tags": [
          "Writing"
        ],
        "summary": "Publish a merge patch",
        "description": "Applies a JSON Merge Patch (RFC 7386) to the current payload and publishes the result as the next version: nested objects merge key by key, `null` deletes a key.",
        "parameters": [
          {
            "name": "env",
            "in": "query",
            "description": "The environment. Defaults to `production`.",
            "schema": {
              "type": "string",
              "enum": [
                "production",
                "staging",
                "development"
              ],
              "default": "production"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "example": {
                "limits": {
                  "max_upload_mb": 75
                },
                "features": {
                  "old_flag": null
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Published.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WriteResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "422": {
            "$ref": "#/components/responses/SchemaFailed"
          },
          "507": {
            "$ref": "#/components/responses/StorageFull"
          }
        }
      },
      "delete": {
        "operationId": "deleteBin",
        "tags": [
          "Bins"
        ],
        "summary": "Delete a bin",
        "description": "Deletes the bin with every environment and version, and purges the edge cache. Needs a key without bin or environment limits.",
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/{org}/{bin}/history": {
      "parameters": [
        {
          "name": "org",
          "in": "path",
          "required": true,
          "description": "The organization's slug. It never changes.",
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9-]{3,40}$"
          },
          "example": "acme"
        },
        {
          "name": "bin",
          "in": "path",
          "required": true,
          "description": "The bin's id, unique in its organization.",
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
          },
          "example": "mobile-flags"
        }
      ],
      "get": {
        "operationId": "listVersions",
        "tags": [
          "Versions"
        ],
        "summary": "List versions",
        "description": "The environment's kept versions, newest first.",
        "parameters": [
          {
            "name": "env",
            "in": "query",
            "description": "The environment. Defaults to `production`.",
            "schema": {
              "type": "string",
              "enum": [
                "production",
                "staging",
                "development"
              ],
              "default": "production"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "How many, 1\u2013200.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "before",
            "in": "query",
            "description": "Only versions below this number, for the next page.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Versions.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/History"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/{org}/{bin}/promote": {
      "parameters": [
        {
          "name": "org",
          "in": "path",
          "required": true,
          "description": "The organization's slug. It never changes.",
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9-]{3,40}$"
          },
          "example": "acme"
        },
        {
          "name": "bin",
          "in": "path",
          "required": true,
          "description": "The bin's id, unique in its organization.",
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
          },
          "example": "mobile-flags"
        }
      ],
      "post": {
        "operationId": "promote",
        "tags": [
          "Versions"
        ],
        "summary": "Promote between environments",
        "description": "Copies the latest version of `from_env` to `to_env` as its next version, checked against the schema. A limited key needs both environments.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "from_env",
                  "to_env"
                ],
                "properties": {
                  "from_env": {
                    "type": "string",
                    "enum": [
                      "production",
                      "staging",
                      "development"
                    ]
                  },
                  "to_env": {
                    "type": "string",
                    "enum": [
                      "production",
                      "staging",
                      "development"
                    ]
                  }
                }
              },
              "example": {
                "from_env": "staging",
                "to_env": "production"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Promoted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WriteResult"
                },
                "example": {
                  "bin_id": "mobile-flags",
                  "environment": "production",
                  "version": 5,
                  "hash": "7ac562a24ad09d989d7a8cc810d64bd108028f013313b206aafba5c182fb951d",
                  "promoted_from": "staging",
                  "promoted_from_version": 3
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "422": {
            "$ref": "#/components/responses/SchemaFailed"
          }
        }
      }
    },
    "/v1/{org}/{bin}/rollback": {
      "parameters": [
        {
          "name": "org",
          "in": "path",
          "required": true,
          "description": "The organization's slug. It never changes.",
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9-]{3,40}$"
          },
          "example": "acme"
        },
        {
          "name": "bin",
          "in": "path",
          "required": true,
          "description": "The bin's id, unique in its organization.",
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
          },
          "example": "mobile-flags"
        }
      ],
      "post": {
        "operationId": "rollback",
        "tags": [
          "Versions"
        ],
        "summary": "Roll back",
        "description": "Publishes the contents of an earlier version as the next version. History is never rewritten. Also republishes an unpublished environment.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "env",
                  "version"
                ],
                "properties": {
                  "env": {
                    "type": "string",
                    "enum": [
                      "production",
                      "staging",
                      "development"
                    ]
                  },
                  "version": {
                    "type": "integer",
                    "minimum": 1
                  }
                }
              },
              "example": {
                "env": "production",
                "version": 3
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rolled back.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WriteResult"
                },
                "example": {
                  "bin_id": "mobile-flags",
                  "environment": "production",
                  "version": 6,
                  "hash": "1a4cdd68925aa94d241b0cfc1aa2e40248c8476abc9602379ee69bbd82f56ac2",
                  "rolled_back_to": 3
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "422": {
            "$ref": "#/components/responses/SchemaFailed"
          }
        }
      }
    },
    "/v1/{org}/{bin}/unpublish": {
      "parameters": [
        {
          "name": "org",
          "in": "path",
          "required": true,
          "description": "The organization's slug. It never changes.",
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9-]{3,40}$"
          },
          "example": "acme"
        },
        {
          "name": "bin",
          "in": "path",
          "required": true,
          "description": "The bin's id, unique in its organization.",
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
          },
          "example": "mobile-flags"
        }
      ],
      "post": {
        "operationId": "unpublish",
        "tags": [
          "Versions"
        ],
        "summary": "Unpublish an environment",
        "description": "Stops serving the environment (reads answer `404`) and purges the edge cache. Versions are kept.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "env"
                ],
                "properties": {
                  "env": {
                    "type": "string",
                    "enum": [
                      "production",
                      "staging",
                      "development"
                    ]
                  }
                }
              },
              "example": {
                "env": "staging"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Unpublished.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bin_id": {
                      "type": "string"
                    },
                    "environment": {
                      "type": "string",
                      "enum": [
                        "production",
                        "staging",
                        "development"
                      ]
                    },
                    "version": {
                      "type": "integer",
                      "enum": [
                        0
                      ]
                    },
                    "unpublished_version": {
                      "type": "integer"
                    }
                  }
                },
                "example": {
                  "bin_id": "mobile-flags",
                  "environment": "staging",
                  "version": 0,
                  "unpublished_version": 3
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/{org}/{bin}/environments/{env}": {
      "parameters": [
        {
          "name": "org",
          "in": "path",
          "required": true,
          "description": "The organization's slug. It never changes.",
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9-]{3,40}$"
          },
          "example": "acme"
        },
        {
          "name": "bin",
          "in": "path",
          "required": true,
          "description": "The bin's id, unique in its organization.",
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
          },
          "example": "mobile-flags"
        },
        {
          "name": "env",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "enum": [
              "production",
              "staging",
              "development"
            ]
          }
        }
      ],
      "delete": {
        "operationId": "deleteEnvironment",
        "tags": [
          "Versions"
        ],
        "summary": "Delete an environment",
        "description": "Deletes the environment with every version. The next write starts again at version 1. Needs a key without bin or environment limits.",
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/{org}/{bin}/settings": {
      "parameters": [
        {
          "name": "org",
          "in": "path",
          "required": true,
          "description": "The organization's slug. It never changes.",
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9-]{3,40}$"
          },
          "example": "acme"
        },
        {
          "name": "bin",
          "in": "path",
          "required": true,
          "description": "The bin's id, unique in its organization.",
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
          },
          "example": "mobile-flags"
        }
      ],
      "get": {
        "operationId": "getBinSettings",
        "tags": [
          "Bins"
        ],
        "summary": "Get a bin's settings",
        "responses": {
          "200": {
            "description": "The bin.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Bin"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "patch": {
        "operationId": "updateBinSettings",
        "tags": [
          "Bins"
        ],
        "summary": "Change a bin's settings",
        "description": "Any of `name`, `description`, `is_public` and `schema` (`null` removes it). A new schema must accept every environment's current payload. Changing visibility purges the edge cache. Needs a key without bin or environment limits.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "description": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 1000
                  },
                  "is_public": {
                    "type": "boolean"
                  },
                  "schema": {
                    "description": "A JSON Schema, at most 64 KiB, or null."
                  }
                }
              },
              "example": {
                "is_public": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated bin.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Bin"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "422": {
            "$ref": "#/components/responses/SchemaFailed"
          }
        }
      }
    },
    "/v1/{org}/{bin}/payload": {
      "parameters": [
        {
          "name": "org",
          "in": "path",
          "required": true,
          "description": "The organization's slug. It never changes.",
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9-]{3,40}$"
          },
          "example": "acme"
        },
        {
          "name": "bin",
          "in": "path",
          "required": true,
          "description": "The bin's id, unique in its organization.",
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
          },
          "example": "mobile-flags"
        }
      ],
      "get": {
        "operationId": "readPayloadUncached",
        "tags": [
          "Reading"
        ],
        "summary": "Read the stored payload, uncached",
        "description": "Like reading the bin, but never cached and only for writers. For tools that must see a write immediately.",
        "parameters": [
          {
            "name": "env",
            "in": "query",
            "description": "The environment. Defaults to `production`.",
            "schema": {
              "type": "string",
              "enum": [
                "production",
                "staging",
                "development"
              ],
              "default": "production"
            }
          },
          {
            "name": "v",
            "in": "query",
            "description": "`latest` or a version number.",
            "schema": {
              "type": "string",
              "default": "latest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The payload.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Any JSON value."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/bins": {
      "get": {
        "operationId": "listBins",
        "tags": [
          "Bins"
        ],
        "summary": "List bins",
        "description": "The key's organization's bins, most recently updated first. A limited key sees only its bins and environments.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Part of the id or name, any case.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "updated_after",
            "in": "query",
            "description": "RFC 3339 time or YYYY-MM-DD, inclusive.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "updated_before",
            "in": "query",
            "description": "RFC 3339 time or YYYY-MM-DD, exclusive.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size, 1\u2013100. Without it, every match is returned.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Matches to skip.",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bins.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "bins",
                    "total"
                  ],
                  "properties": {
                    "bins": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Bin"
                      }
                    },
                    "total": {
                      "type": "integer",
                      "description": "Matches, before limit and offset."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "createBin",
        "tags": [
          "Bins"
        ],
        "summary": "Create a bin",
        "description": "Creates a bin in the key's organization. Needs a key without bin or environment limits.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "id"
                ],
                "additionalProperties": false,
                "properties": {
                  "id": {
                    "type": "string",
                    "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 100,
                    "description": "Defaults to the id."
                  },
                  "description": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 1000
                  },
                  "schema": {
                    "description": "A JSON Schema every version must match, at most 64 KiB."
                  },
                  "is_public": {
                    "type": "boolean",
                    "description": "Omitted: private on Pro, public on Free. Private bins need Pro (403 private_bins_require_pro)."
                  }
                }
              },
              "example": {
                "id": "mobile-flags",
                "name": "Mobile flags",
                "is_public": true,
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "description": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "is_public": {
                      "type": "boolean"
                    },
                    "has_schema": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "422": {
            "$ref": "#/components/responses/LimitReached"
          }
        }
      }
    },
    "/v1/auth/me": {
      "get": {
        "operationId": "whoAmI",
        "tags": [
          "Keys"
        ],
        "summary": "Describe the key",
        "description": "The key's id, name, role and limits, and its organization. `hotcfg login` uses it to check a key.",
        "responses": {
          "200": {
            "description": "The key and organization.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "api_key": {
                      "$ref": "#/components/schemas/ApiKey"
                    },
                    "organization": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "slug": {
                          "type": "string"
                        },
                        "plan": {
                          "type": "string",
                          "enum": [
                            "free",
                            "pro"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/organizations/{id}/usage": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "The organization's id (`org_\u2026`), from `GET /v1/auth/me`.",
          "schema": {
            "type": "string"
          },
          "example": "org_8f3a2c"
        }
      ],
      "get": {
        "operationId": "getUsage",
        "tags": [
          "Organization"
        ],
        "summary": "Plan, usage and limits",
        "description": "`-1` means unlimited. Needs a secret key. Reads aren't counted: they're unlimited.",
        "responses": {
          "200": {
            "description": "Usage.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "plan": {
                      "type": "string"
                    },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "bins": {
                          "type": "integer"
                        },
                        "seats": {
                          "type": "integer"
                        },
                        "storage_bytes": {
                          "type": "integer"
                        },
                        "bins_created_today": {
                          "type": "integer"
                        },
                        "invites_today": {
                          "type": "integer"
                        }
                      }
                    },
                    "limits": {
                      "$ref": "#/components/schemas/Limits"
                    },
                    "read_only": {
                      "type": "boolean",
                      "description": "The organization has more bins or seats than its plan allows, so bin writes answer 403 over_plan_limits until it is back under."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/organizations/{id}/export": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "The organization's id (`org_\u2026`), from `GET /v1/auth/me`.",
          "schema": {
            "type": "string"
          },
          "example": "org_8f3a2c"
        }
      ],
      "get": {
        "operationId": "exportOrganization",
        "tags": [
          "Organization"
        ],
        "summary": "Export every bin",
        "description": "Every bin with its settings, schema and, per environment, every kept version (oldest first) with its payload, as one JSON download (`hotcfg-export/1`). Administrators, or a secret key not limited to some bins or environments.",
        "parameters": [
          {
            "name": "versions",
            "in": "query",
            "required": false,
            "description": "`all` (default) or `current`: only the version each environment serves.",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "current"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The export.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "format": {
                      "type": "string",
                      "example": "hotcfg-export/1"
                    },
                    "exported_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "organization": {
                      "type": "object"
                    },
                    "bins": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/organizations/{id}/keys": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "The organization's id (`org_\u2026`), from `GET /v1/auth/me`.",
          "schema": {
            "type": "string"
          },
          "example": "org_8f3a2c"
        }
      ],
      "get": {
        "operationId": "listKeys",
        "tags": [
          "Keys"
        ],
        "summary": "List active keys",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Part of the name or prefix.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "created_after",
            "in": "query",
            "description": "RFC 3339 or YYYY-MM-DD.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "created_before",
            "in": "query",
            "description": "RFC 3339 or YYYY-MM-DD.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Keys, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "keys": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ApiKey"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "createKey",
        "tags": [
          "Keys"
        ],
        "summary": "Create a key",
        "description": "`admin` makes a secret key (`sk_live_\u2026`), `read_only` a publishable one (`pk_live_\u2026`, Pro only: `403 read_only_keys_require_pro` on Free). A key without `production` in `environments` can't change production. Limits are fixed at creation. The plaintext `key` is in this response only. Keys with an expiry can't manage keys.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "role",
                  "name"
                ],
                "properties": {
                  "role": {
                    "type": "string",
                    "enum": [
                      "admin",
                      "read_only"
                    ]
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "bins": {
                    "type": "array",
                    "maxItems": 100,
                    "items": {
                      "type": "string"
                    }
                  },
                  "environments": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "production",
                        "staging",
                        "development"
                      ]
                    }
                  },
                  "expires_at": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              },
              "example": {
                "role": "admin",
                "name": "GitHub Actions (staging)",
                "bins": [
                  "mobile-flags"
                ],
                "environments": [
                  "development",
                  "staging"
                ],
                "expires_at": "2027-11-05T00:00:00Z"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created. Store `key` now.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKey"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/organizations/{id}/keys/{key_id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "The organization's id (`org_\u2026`), from `GET /v1/auth/me`.",
          "schema": {
            "type": "string"
          },
          "example": "org_8f3a2c"
        },
        {
          "name": "key_id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "example": "key_05738730ee3dd3b5"
        }
      ],
      "patch": {
        "operationId": "renameKey",
        "tags": [
          "Keys"
        ],
        "summary": "Rename a key",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKey"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "delete": {
        "operationId": "revokeKey",
        "tags": [
          "Keys"
        ],
        "summary": "Revoke a key",
        "responses": {
          "204": {
            "description": "Revoked. It's refused from now on."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/organizations/{id}/keys/{key_id}/rotate": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "The organization's id (`org_\u2026`), from `GET /v1/auth/me`.",
          "schema": {
            "type": "string"
          },
          "example": "org_8f3a2c"
        },
        {
          "name": "key_id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "example": "key_05738730ee3dd3b5"
        }
      ],
      "post": {
        "operationId": "rotateKey",
        "tags": [
          "Keys"
        ],
        "summary": "Rotate a key's secret",
        "description": "Replaces the secret, keeping the id, name, role and limits. The old secret is refused immediately. A secret key may rotate itself.",
        "responses": {
          "200": {
            "description": "The key with the new plaintext `key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKey"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/v1/plans": {
      "get": {
        "operationId": "listPlans",
        "tags": [
          "Organization"
        ],
        "summary": "Plans and their limits",
        "security": [
          {}
        ],
        "responses": {
          "200": {
            "description": "Free and Pro. `-1` means unlimited.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "free": {
                      "$ref": "#/components/schemas/Limits"
                    },
                    "pro": {
                      "$ref": "#/components/schemas/Limits"
                    },
                    "pro_price": {
                      "type": "string"
                    },
                    "promo_code": {
                      "type": "string",
                      "description": "A promotion code to enter at checkout; empty when there is none."
                    },
                    "promo_offer": {
                      "type": "string",
                      "description": "What the promotion code gives; empty when there is none."
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "`sk_live_\u2026` (secret: reads and writes) or `pk_live_\u2026` (publishable: reads only)."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "details": {
                "description": "Extra data for some codes: schema errors, limits, retry_after_seconds."
              }
            }
          }
        }
      },
      "SchemaError": {
        "type": "object",
        "properties": {
          "instance_location": {
            "type": "string",
            "description": "JSON Pointer into the payload."
          },
          "keyword_location": {
            "type": "string",
            "description": "JSON Pointer into the schema."
          },
          "message": {
            "type": "string"
          }
        }
      },
      "WriteResult": {
        "type": "object",
        "required": [
          "bin_id",
          "environment",
          "version",
          "hash"
        ],
        "properties": {
          "bin_id": {
            "type": "string"
          },
          "environment": {
            "type": "string",
            "enum": [
              "production",
              "staging",
              "development"
            ]
          },
          "version": {
            "type": "integer",
            "description": "The new version number."
          },
          "hash": {
            "type": "string",
            "description": "SHA-256 of the payload; the ETag."
          },
          "rolled_back_to": {
            "type": "integer"
          },
          "promoted_from": {
            "type": "string",
            "enum": [
              "production",
              "staging",
              "development"
            ]
          },
          "promoted_from_version": {
            "type": "integer"
          },
          "pruned_versions": {
            "type": "integer",
            "description": "Old versions deleted to stay within the plan's history limit."
          }
        }
      },
      "Bin": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "is_public": {
            "type": "boolean"
          },
          "has_schema": {
            "type": "boolean"
          },
          "schema": {
            "description": "The JSON Schema, in settings responses."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "environments": {
            "type": "object",
            "description": "Published environments.",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "version": {
                  "type": "integer"
                },
                "updated_at": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          }
        }
      },
      "History": {
        "type": "object",
        "properties": {
          "bin_id": {
            "type": "string"
          },
          "environment": {
            "type": "string",
            "enum": [
              "production",
              "staging",
              "development"
            ]
          },
          "current_version": {
            "type": "integer",
            "description": "0 when unpublished."
          },
          "versions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "version": {
                  "type": "integer"
                },
                "hash": {
                  "type": "string"
                },
                "created_at": {
                  "type": "string",
                  "format": "date-time"
                },
                "author_type": {
                  "type": "string",
                  "enum": [
                    "user",
                    "api_key"
                  ]
                },
                "created_by": {
                  "type": "string"
                },
                "author_name": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          }
        }
      },
      "ApiKey": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "role": {
            "type": "string",
            "enum": [
              "admin",
              "read_only"
            ]
          },
          "prefix": {
            "type": "string"
          },
          "redacted_key": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_used_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_by_user_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "bins": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "null: every bin."
          },
          "environments": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string",
              "enum": [
                "production",
                "staging",
                "development"
              ]
            },
            "description": "null: every environment."
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "key": {
            "type": "string",
            "description": "The plaintext key, only when created or rotated."
          }
        }
      },
      "Limits": {
        "type": "object",
        "properties": {
          "max_bins": {
            "type": "integer"
          },
          "max_seats": {
            "type": "integer"
          },
          "max_payload_bytes": {
            "type": "integer"
          },
          "retained_versions": {
            "type": "integer"
          },
          "max_storage_bytes": {
            "type": "integer"
          },
          "bin_creates_per_day": {
            "type": "integer"
          },
          "invites_per_day": {
            "type": "integer"
          },
          "max_organizations": {
            "type": "integer"
          },
          "audit_log": {
            "type": "boolean"
          },
          "private_bins": {
            "type": "boolean",
            "description": "Whether bins can be created or made private."
          },
          "scoped_keys": {
            "type": "boolean",
            "description": "Whether new keys can be limited to bins or environments, or expire."
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "A parameter or the body is invalid. Codes: `invalid_env`, `invalid_json`, `invalid_version`, `invalid_query_string`, `invalid_limit`, `unknown_field`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "invalid_env",
                "message": "env must be production, staging or development"
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "The key is unknown, revoked or expired. Codes: `unauthorized`, `key_expired`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "missing or invalid credentials"
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The key can't do this: a publishable key writing, or a limited key outside its bins and environments; or the organization is over its plan's bin or seat limit, so its bins are read-only. Only administrators change production (`production_admin_only`). Codes: `forbidden`, `key_scope_denied`, `key_creator_not_admin`, `key_unattributed`, `over_plan_limits`, `production_admin_only`, `private_bins_require_pro`, `scoped_keys_require_pro`, `read_only_keys_require_pro`, `owner_only` (billing and deleting the organization are the owner's), `owner_protected`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "key_scope_denied",
                "message": "this API key cannot access the production environment"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "No such bin, environment or version, or a private bin read without a key. Codes: `not_found`, `version_pruned`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "bin not found"
              }
            }
          }
        }
      },
      "Conflict": {
        "description": "Conflicts with the current state. Codes: `bin_exists`, `key_expired`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "bin_exists",
                "message": "a bin with this id already exists in this organization"
              }
            }
          }
        }
      },
      "TooLarge": {
        "description": "Over the plan's payload size, or a schema over 64 KiB. Codes: `payload_too_large`, `schema_too_large`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "payload_too_large",
                "message": "Configuration payload exceeds the maximum size allowed for your plan.",
                "details": {
                  "max_payload_bytes": 262144
                }
              }
            }
          }
        }
      },
      "SchemaFailed": {
        "description": "The payload doesn't match the bin's JSON Schema, or a new schema rejects a current payload. Codes: `schema_validation_failed`, `schema_rejects_current`, `invalid_schema`, `schema_too_complex`.",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "properties": {
                    "error": {
                      "properties": {
                        "details": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/SchemaError"
                          }
                        }
                      }
                    }
                  }
                }
              ]
            },
            "example": {
              "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"
                  }
                ]
              }
            }
          }
        }
      },
      "QueryFailed": {
        "description": "The jq filter failed. Codes: `query_syntax`, `query_runtime`, `query_timeout`, `query_input`, `query_empty`, `query_result_too_large`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "query_syntax",
                "message": "jq syntax error: unexpected EOF"
              }
            }
          }
        }
      },
      "LimitReached": {
        "description": "The plan's bin limit is reached. Codes: `bin_limit_reached`, `invalid_schema`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "bin_limit_reached",
                "message": "You have reached the maximum number of bins for your plan. Upgrade to Pro to create more.",
                "details": {
                  "max_bins": 10
                }
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests. Wait `Retry-After` seconds. Codes: `rate_limited`, `delay_limited`, `daily_bin_limit_reached`.",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Busy": {
        "description": "Testing delays, jq queries or writes are busy; retry after `Retry-After`. Codes: `delay_busy`, `query_busy`, `query_memory`, `query_unavailable`, `write_busy`.",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "StorageFull": {
        "description": "The organization's storage is full. Codes: `org_storage_exceeded`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "org_storage_exceeded",
                "message": "Organization storage limit reached. Clean up unused bins or upgrade your plan.",
                "details": {
                  "storage_bytes": 26214000,
                  "max_storage_bytes": 26214400
                }
              }
            }
          }
        }
      }
    }
  }
}
