App State

User-related API environment

Production user-related API docs

These pages describe the Production user-related API stack.

Use production OAuth credentials, production API base URLs, and production app URLs when following this documentation.

Need to test before going live? Switch to the Pre-live docs using the environment switcher above.

Store and synchronize app-specific user data across devices.

📄️ Get the active App State configuration

Returns enabled data groups and effective limits for the authenticated OAuth client. Call it before writing so the app knows which names are available and which require ETag preconditions. Requires a user-delegated access token with app_state, app_state.read, or app_state.write. Client-credentials tokens are rejected because App State is always scoped to a real user.

📄️ Bootstrap App State

Builds a paged base scan while writes may continue. Persist pages in staging. After the final page, drain GET /v1/app-state:changes from nextSyncToken before exposing the snapshot. Requires a user-delegated access token with app_state or app_state.read. Client-credentials tokens are rejected because App State is always scoped to a real user.

📄️ Synchronize App State changes

Pulls a bounded page after an opaque sync token. Apply the page and nextSyncToken atomically; drain until hasMore is false. On 410, preserve pending mutations, bootstrap, drain, replay, then pull again. Requires a user-delegated access token with app_state or app_state.read. Client-credentials tokens are rejected because App State is always scoped to a real user.

📄️ List App State documents

Lists live documents in one enabled data group in ascending key order. Continue with the opaque nextCursor until hasMore is false. Requires a user-delegated access token with app_state or app_state.read. Client-credentials tokens are rejected because App State is always scoped to a real user.

📄️ Get an App State document

Returns one live document and its quoted ETag. Send the ETag unchanged in If-Match for a strict replacement. Requires a user-delegated access token with app_state or app_state.read. Client-credentials tokens are rejected because App State is always scoped to a real user.

📄️ Create or replace an App State document

Stores value as a complete replacement; no JSON merge is performed. Idempotency-Key is required. Strict data groups also require exactly one precondition header. Requires a user-delegated access token with app_state or app_state.write. Client-credentials tokens are rejected because App State is always scoped to a real user.

📄️ Delete an App State document

Deletes the live document and emits a tombstone. Deleting an absent document returns 204. Idempotency-Key is required; strict data groups also require a precondition. Requires a user-delegated access token with app_state or app_state.write. Client-credentials tokens are rejected because App State is always scoped to a real user.