SkyState

Public State ​

Public state is versioned JSON state scoped by account, project, and environment. It is readable by browser apps through anonymous readonly routes and writable by developer bearer tokens or project API keys.

Use it for application config, feature flags, public settings, announcements, theme values, safe client-visible 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/{projectId}/public-state/{env}
PUT   /v1/{accountId}/projects/{projectId}/public-state/{env}
PATCH /v1/{accountId}/projects/{projectId}/public-state/{env}
GET   /v1/{accountId}/projects/{projectId}/public-state/{env}/versions

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

Anonymous Readonly Route ​

text
GET /v1/readonly/{accountId}/projects/{projectId}/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.
  • Writes require If-Match.
  • If-Match: "0" is the first-write guard for an empty slot.
  • Successful writes return 200 with version, state, comment, createdAt, and stateSizeBytes.
  • Conflicts return 412.
  • PATCH expects an ops array of JSON Patch operations and optional comment.