SkyState

Public State ​

Public state is versioned JSON state scoped by account, project, and environment. It is readable anonymously through the readonly route and readable or writable by developer bearer tokens or project API keys.

Use it for application config, feature flags, settings, announcements, theme values, safe limits, and catalog or inventory data. Do not use it for secrets, private user data, or inventory counts that require reservation-grade consistency.

Most developers should use the SDK, CLI, or console instead of calling these endpoints directly.

Developer Or API-Key Routes ​

text
GET   /v1/{accountId}/projects/{slug}/public-state/{env}
PUT   /v1/{accountId}/projects/{slug}/public-state/{env}
PATCH /v1/{accountId}/projects/{slug}/public-state/{env}
GET   /v1/{accountId}/projects/{slug}/public-state/{env}/versions

These routes accept Authorization: Bearer <developer-token> or Authorization: ApiKey <sky_...>.

Anonymous Readonly Route ​

text
GET /v1/readonly/{accountId}/projects/{slug}/public-state/{env}

This route is used by SDK public-state reads. It sets ETag and Cache-Control; development and staging responses use a short cache window, while production responses use a longer one.

Write Semantics ​

  • Public state must be a JSON object.
  • Creates use If-None-Match: *. The write succeeds only when no state exists yet; if state already exists it returns 412. On PATCH, the operations apply to an empty {} document.
  • Updates use a quoted positive version, If-Match: "N". A stale or missing version returns 412, and If-Match: "0" always returns 412.
  • When both headers are sent, the server evaluates If-Match first, following RFC 9110. If-Match: "N" together with If-None-Match: * is an update-then-create write: it updates version N if that version exists, and otherwise creates the state. If-Match together with any If-None-Match value other than exactly * returns 400 with { error: "validation_error", message: "If-None-Match must contain only *" }.
  • A write with neither header returns 400 with { error: "validation_error", message: "If-Match or If-None-Match header is required" }.
  • Successful writes return 200 with version, state, comment, createdAt, and stateSizeBytes.
  • Every accepted PATCH creates a new version and returns 200, even when the operations leave the data unchanged; the comment is still recorded on that version.
  • PATCH expects an ops array of JSON Patch operations and optional comment.