Skip to main content

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.

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.

Path Parameters
    collection string required

    Possible values: Value must match regular expression ^[a-z0-9][a-z0-9._-]{0,79}$

    Enabled data-group name returned by GET /v1/app-state:config.

    Example: settings
    key string required

    Possible values: non-empty and <= 512 characters, Value must match regular expression ^(?=(?:(?:[\uD800-\uDBFF][\uDC00-\uDFFF]|[^\uD800-\uDFFF])){1,512}$)[^\u0000-\u001f\u007f/\\]+$

    Application-defined document key of 1-512 Unicode scalar values. Keys are compared by exact code points without Unicode normalization, so canonically equivalent spellings are distinct keys. It cannot contain slashes, backslashes, or control characters.

    Example: theme
Header Parameters
    Idempotency-Key string required

    Possible values: >= 16 characters and <= 256 characters

    High-entropy key retained for 24 hours and scoped to the user and App State namespace. The fingerprint covers the method, route, body, and preconditions. An exact retry replays the original status, body, and ETag only after current authorization and current App State policy validation succeed. A current authorization or policy validation failure is returned instead of the stored replay. Reusing the key with a different method, route, body, or precondition returns 409.

    Example: 01HZX4EXAMPLE8J4K7M2PQ9RST
    If-Match string

    Possible values: Value must match regular expression ^((?:W\/)?"[A-Za-z0-9_-]{43}"|\*)$

    Mutate only when the current quoted ETag matches. Send weak validators returned by an intermediary unchanged. Use * to require an existing live document.

    Example: "s_6UYAfR2WOsf0gHaRMUXBw2kP1S-kRXyCmbCl6yZpk"
    If-None-Match string

    Possible values: Value must match regular expression ^((?:W\/)?"[A-Za-z0-9_-]{43}"|\*)$

    Mutate only when the supplied ETag does not match. Send weak validators returned by an intermediary unchanged. Use * to require no live document.

    Example: *
Request Body required

Complete replacement document. No generic JSON merge is performed.

    value required

    Application-owned JSON value stored as the complete document.

    schemaVersion integer required

    Possible values: >= 1 and <= 2147483647

    Application-owned schema version for value.

Responses

The existing document was replaced, or an exact retry replayed its result.

Response Headers
  • ETag string
    Example: "s_6UYAfR2WOsf0gHaRMUXBw2kP1S-kRXyCmbCl6yZpk"

    Opaque quoted document validator. An intermediary may add W/. Store it and send it unchanged in If-Match; never construct it from version.

Schema
    success boolean required

    Possible values: [true]

    data object required
    collection string required

    Possible values: Value must match regular expression ^[a-z0-9][a-z0-9._-]{0,79}$

    Enabled data group containing the document.

    key string required

    Possible values: non-empty and <= 512 characters, Value must match regular expression ^(?=(?:(?:[\uD800-\uDBFF][\uDC00-\uDFFF]|[^\uD800-\uDFFF])){1,512}$)[^\u0000-\u001f\u007f/\\]+$

    Document key within the data group.

    schemaVersion integer required

    Possible values: >= 1 and <= 2147483647

    Application-owned schema version for the document value.

    version integer required

    Possible values: >= 1

    Server-assigned document version.

    updatedAt date-time required
Loading...