Bootstrap App State

User-related API environment

Pre-live user-related API docs

These pages describe the Pre-live user-related API stack.

Use pre-live OAuth credentials, pre-live API base URLs, and pre-live app URLs when following this documentation. Keep your OAuth flow, API requests, callback URLs, and manual testing within the pre-live environment.

Use prelive.quran.com for auth-related testing.
Use prelive.quranreflect.org for Quran Reflect paths where applicable.
Do not mix production sessions or production user data with pre-live testing.

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.

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 the initial App State base scan.

application/json

Schema

Example (from schema)

Bootstrap page continues

Bootstrap complete

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,
    "nextSyncToken": null
  }
}

Bootstrap 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-bootstrap-cursor",
    "hasMore": true,
    "nextSyncToken": null
  }
}

Bootstrap complete

{
  "success": true,
  "data": {
    "items": [],
    "nextCursor": null,
    "hasMore": false,
    "nextSyncToken": "v2.opaque-sync-token"
  }
}

The API Gateway rejects missing authentication headers. The App State service can also return this status: The bootstrap cursor is invalid.

application/json

Schema

Example (from schema)

Missing authentication headers

Invalid bootstrap 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 bootstrap cursor

{
  "details": {
    "success": false,
    "error": {
      "code": "invalid_sync_token",
      "message": "The bootstrap cursor is invalid."
    }
  },
  "message": "The bootstrap 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

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
}

Policy changed during bootstrap. Resolve configuration and restart.

application/json

Schema

Example (from schema)

App State policy changed

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": {}
}

App State policy changed

{
  "details": {
    "success": false,
    "error": {
      "code": "app_state_policy_changed",
      "message": "Bootstrap is required because the App State policy changed."
    }
  },
  "message": "Bootstrap is required because the App State policy changed.",
  "type": "service_error",
  "success": false
}

Discard this cursor and restart bootstrap.

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
}

Pre-live user-related API docs

Bootstrap App State​

Bootstrap App State