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.

Get mutations​

Pulls the mutations (creates, updates and deletes) made to the signed-in user's synced resources after a sync cursor. This is the delta endpoint of the Sync API: pull and apply server changes first, then push local changes with POST /v1/sync. Persist the returned lastMutationAt as your next cursor only after the final page (hasMore=false).

Requires the sync scope plus the scope of each resource you want to receive. Mutations for resources your token cannot access are not returned.

Example requests (paths are relative to the User API base URL, for example https://apis.quran.foundation/auth)

Read the current sync head without fetching mutations:

GET /v1/sync?mutationsSince=0&metadataOnly=true

Pull bookmark and collection changes since a stored cursor (first page):

GET /v1/sync?mutationsSince=1731636500303&resources=BOOKMARK,COLLECTION&limit=100&page=1

Fetch the next page of the same pull, sending the lastMutationAt returned by page 1:

GET /v1/sync?mutationsSince=1731636500303&resources=BOOKMARK,COLLECTION&limit=100&page=2&lastMutationAt=1731636600000
Query Parameters
    mutationsSince float required

    Pull cursor as a Unix timestamp in milliseconds; returns mutations made after it. Use 0 for a full initial pull. After that, send the lastMutationAt you stored after your last completed pull (all pages). Do not use the X-Mutation-At header from a write as this cursor. Combine with metadataOnly=true to check whether newer data exists without fetching mutations.

    lastMutationAt integer

    For page > 1, send the lastMutationAt returned by page 1. A missing continuation head or a changed head returns 409. Restart from page 1 with the original mutationsSince, resources, and limit; only advance mutationsSince after all pages succeed.

    resources string

    Comma-separated list of resources to filter mutations by (e.g. "BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE,READING_BOOKMARK,READING_SESSION"). If not provided, all accessible resources will be returned.

    metadataOnly boolean

    When true, returns only the lastMutationAt timestamp without fetching actual mutations. This is significantly faster (single DB query vs multiple joins) and ideal for: 1) Checking if new data exists before performing a full sync, 2) Implementing periodic background polling to detect changes, 3) Recovering the current lastMutationAt if the client missed the X-Mutation-At header from a previous successful mutation response. Response will only contain { lastMutationAt: number }.

    limit integer

    Possible values: >= 1 and <= 1000

    Default value: 100

    Maximum number of mutations to return per page; an integer from 1 to 1000. Fractional values return 422.

    page integer

    Possible values: >= 1

    Default value: 1

    Page number; a 1-based integer. Fractional values return 422.

Responses

Request has been handled successfully.

Response Headers
  • X-Mutation-At string

    Effective user mutation head in Unix milliseconds. GET returns its observed sync head; writes capture it inside their serialized database operation, before releasing the user lock. Effective writes advance it; no-ops may retain it. Successful publication uses the final attachment transaction; partial publication retains the private-write or pre-publication baseline head. A concurrent write may make it stale before receipt, so POST /v1/sync can still return 409. Use it only as an optimistic write precondition, never as a pull watermark. See the Sync API guide for how sync clients store and use it.


Schema
    success boolean
    data object

    Response schema for get mutations endpoint. When metadataOnly=true, only lastMutationAt is returned.

    mutations object[]

    Array of mutations that occurred after lastMutationAt. Will be omitted when metadataOnly is set to true.

  • Array [
  • type string required

    Possible values: [CREATE, UPDATE, DELETE]

    The type of the mutation

    resource string required

    Possible values: [BOOKMARK, COLLECTION, COLLECTION_BOOKMARK, NOTE, READING_BOOKMARK, READING_SESSION]

    The resource the mutation was applied to.

    resourceId string

    The id of the resource the mutation was applied to. In GET /sync responses, this will be omitted for composite-key resources (e.g. COLLECTION_BOOKMARK). In POST /sync responses, the server may return a composite id (e.g. "collectionId-bookmarkId") for such resources.

    data object

    The latest version of the data of the resource that was mutated. Delete mutations usually return empty data; composite-key resources can return identifier fields such as collectionId and bookmarkId. clientCreatedAt and clientUpdatedAt are maintained internally by the backend and cannot be set through request bodies. timestamp represents the server sync mutation timestamp.

    isInDefaultCollection boolean

    BOOKMARK CREATE/UPDATE only. True when the bookmark is in the user's Favorites (virtual __default__ collection).

    timestamp float required

    Unix timestamp when the latest mutation of the resource occurred

  • ]
  • page float

    Current page number

    limit float

    Items per page

    total float

    Total number of mutations

    hasMore boolean

    Whether more pages exist

    lastMutationAt float required

    Effective sync head, including virtual resources such as the default Favorites collection. Use it for subsequent sync requests. If metadataOnly is true, this is the only field returned.

Loading...