List App State documents

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.

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.

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

Query Parameters

cursor string

Opaque cursor returned by the preceding page. Never decode or construct it.

Example: v2.opaque-page-cursor

limit integer

Default value: 100

Maximum rows or changes scanned. Invalid or non-positive values use 100; values above 100 are capped at 100.

Example: 50

Responses

One page of live documents in the requested data group.

application/json

Schema

Example (from schema)

Document page continues

No documents

Schema

success boolean required

Possible values: [true]

data object required

oneOf

object

{
  "success": true,
  "data": {
    "items": [
      {
        "collection": "settings",
        "key": "theme",
        "schemaVersion": 1,
        "version": 3,
        "updatedAt": "2026-08-27T00:15:00.000Z",
        "value": {
          "mode": "dark",
          "fontScale": 1.1
        },
        "etag": "\"s_6UYAfR2WOsf0gHaRMUXBw2kP1S-kRXyCmbCl6yZpk\""
      }
    ],
    "nextCursor": "string",
    "hasMore": true
  }
}

Document page continues

{
  "success": true,
  "data": {
    "items": [
      {
        "collection": "settings",
        "key": "theme",
        "schemaVersion": 1,
        "version": 3,
        "value": {
          "mode": "dark",
          "fontScale": 1.1
        },
        "updatedAt": "2026-08-27T00:15:00.000Z",
        "etag": "\"s_6UYAfR2WOsf0gHaRMUXBw2kP1S-kRXyCmbCl6yZpk\""
      }
    ],
    "nextCursor": "v2.opaque-collection-cursor",
    "hasMore": true
  }
}

No documents

{
  "success": true,
  "data": {
    "items": [],
    "nextCursor": null,
    "hasMore": false
  }
}

The API Gateway rejects missing authentication headers. The App State service can also return this status: The data-group name or cursor is invalid.

application/json

Schema

Example (from schema)

Missing authentication headers

Invalid collection cursor

Schema

message string required

type string required

success boolean required

Possible values: [false]

details object

The upstream service error body, when the failure came from a service.

property name* any

The upstream service error body, when the failure came from a service.

{
  "message": "string",
  "type": "string",
  "success": false,
  "details": {}
}

Missing authentication headers

{
  "message": "The request is missing required headers or is invalid",
  "type": "invalid_request",
  "success": false
}

Invalid collection cursor

{
  "details": {
    "success": false,
    "error": {
      "code": "invalid_sync_token",
      "message": "The collection cursor is invalid."
    }
  },
  "message": "The collection cursor is invalid.",
  "type": "invalid_request",
  "success": false
}

The Gateway and App State service reject malformed, expired, inactive, revoked, or non-user-delegated access tokens and tokens associated with another client. The service can also reject a banned authenticated user.

Response Headers

WWW-Authenticate string
Example: Bearer error="invalid_token"
Bearer challenge returned for invalid App State credentials.

application/json

Schema

Example (from schema)

Malformed access token

Expired or inactive access token

Revoked access token

Token belongs to another client

Invalid access token rejected by App State

Banned user

Schema

message string required

type string required

success boolean required

Possible values: [false]

details object

The upstream service error body, when the failure came from a service.

property name* any

The upstream service error body, when the failure came from a service.

{
  "message": "string",
  "type": "string",
  "success": false,
  "details": {}
}

Malformed access token

{
  "message": "The access token is not a valid JWT",
  "type": "invalid_token",
  "success": false
}

Expired or inactive access token

{
  "message": "The access token is expired or inactive",
  "type": "invalid_token",
  "success": false
}

Revoked access token

{
  "message": "The access token is expired or inactive",
  "type": "invalid_token",
  "success": false
}

Token belongs to another client

{
  "message": "The access token is not associated with the client",
  "type": "invalid_token",
  "success": false
}

Invalid access token rejected by App State

{
  "details": {
    "success": false,
    "error": {
      "code": "invalid_token",
      "message": "The access token is invalid."
    }
  },
  "message": "The access token is invalid.",
  "type": "unauthorized",
  "success": false
}

Banned user

{
  "details": {
    "success": false,
    "name": "external.banned",
    "error": {
      "code": "BANNED",
      "message": "Sorry, Your account is banned. Contact Quran.Foundation",
      "details": {
        "email": "BANNED"
      }
    }
  },
  "message": "Sorry, Your account is banned. Contact Quran.Foundation",
  "type": "unauthorized",
  "success": false
}

The Gateway rejects insufficient scopes. The service additionally requires an active App State policy and an enabled data group.

application/json

Schema

Example (from schema)

Insufficient App State scope

App State disabled

Data group not enabled

Schema

message string required

type string required

success boolean required

Possible values: [false]

details object

The upstream service error body, when the failure came from a service.

property name* any

The upstream service error body, when the failure came from a service.

{
  "message": "string",
  "type": "string",
  "success": false,
  "details": {}
}

Insufficient App State scope

{
  "message": "The access token does not have the required scopes",
  "type": "insufficient_scope",
  "success": false
}

App State disabled

{
  "details": {
    "success": false,
    "error": {
      "code": "app_state_disabled",
      "message": "App State is disabled."
    }
  },
  "message": "App State is disabled.",
  "type": "forbidden",
  "success": false
}

Data group not enabled

{
  "details": {
    "success": false,
    "error": {
      "code": "collection_not_allowed",
      "message": "The collection is not approved."
    }
  },
  "message": "The collection is not approved.",
  "type": "forbidden",
  "success": false
}

Restart the listing without a cursor.

application/json

Schema

Example (from schema)

Bootstrap required

Sync token expired

Schema

message string required

type string required

success boolean required

Possible values: [false]

details object

The upstream service error body, when the failure came from a service.

property name* any

The upstream service error body, when the failure came from a service.

{
  "message": "string",
  "type": "string",
  "success": false,
  "details": {}
}

Bootstrap required

{
  "details": {
    "success": false,
    "error": {
      "code": "bootstrap_required",
      "message": "Bootstrap is required to recover App State."
    }
  },
  "message": "Bootstrap is required to recover App State.",
  "type": "gone",
  "success": false
}

Sync token expired

{
  "details": {
    "success": false,
    "error": {
      "code": "sync_token_expired",
      "message": "The sync token has expired."
    }
  },
  "message": "The sync token has expired.",
  "type": "gone",
  "success": false
}

The request was rate limited by the public API Gateway. Retry after the communicated interval.

application/json

Schema

Example (from schema)

Client rate limited

Schema

message string required

type string required

success boolean required

Possible values: [false]

details object

The upstream service error body, when the failure came from a service.

property name* any

The upstream service error body, when the failure came from a service.

{
  "message": "string",
  "type": "string",
  "success": false,
  "details": {}
}

Client rate limited

{
  "message": "Too many requests, please try again later",
  "type": "rate_limit_exceeded",
  "success": false
}

An unexpected server or database failure prevented the request from completing.

application/json

Schema

Example (from schema)

Unexpected server error

Schema

message string required

type string required

success boolean required

Possible values: [false]

details object

The upstream service error body, when the failure came from a service.

property name* any

The upstream service error body, when the failure came from a service.

{
  "message": "string",
  "type": "string",
  "success": false,
  "details": {}
}

Unexpected server error

{
  "details": {
    "success": false,
    "error": {
      "code": "ServerError",
      "message": "Something went wrong"
    }
  },
  "message": "Something went wrong",
  "type": "internal_server_error",
  "success": false
}

App State policy or stream state could not be resolved. Retry with backoff.

application/json

Schema

Example (from schema)

Namespace resolution unavailable

App State unavailable

Schema

message string required

type string required

success boolean required

Possible values: [false]

details object

The upstream service error body, when the failure came from a service.

property name* any

The upstream service error body, when the failure came from a service.

{
  "message": "string",
  "type": "string",
  "success": false,
  "details": {}
}

Namespace resolution unavailable

{
  "details": {
    "success": false,
    "error": {
      "code": "namespace_resolution_unavailable",
      "message": "App State namespace resolution is temporarily unavailable."
    }
  },
  "message": "App State namespace resolution is temporarily unavailable.",
  "type": "service_unavailable",
  "success": false
}

App State unavailable

{
  "details": {
    "success": false,
    "error": {
      "code": "app_state_unavailable",
      "message": "The App State stream or document is temporarily unavailable."
    }
  },
  "message": "The App State stream or document is temporarily unavailable.",
  "type": "service_unavailable",
  "success": false
}

Production user-related API docs

List App State documents​

List App State documents