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.

Sync local mutations​

Apply mutations in request order inside one atomic transaction. Repeated reading-bookmark slot upserts retain sequential semantics: omitted names preserve the preceding name; null clears it. NOTE writes are private-only: saveToQR and attachedEntity are rejected with indexed 422 errors. NOTE CREATE requires ranges (an empty array is allowed for a range-free note). READING_SESSION CREATE/UPDATE require an existing Quran chapter/verse pair; invalid locations return indexed 422 errors before any batch writes. NOTE CREATE requires a nonblank authenticated OAuth client_id; source attribution follows the existing server request-context policy. Use the direct note publication endpoint for QuranReflect publication.

Query Parameters
    lastMutationAt float required

    The effective sync head returned by the get mutations endpoint. It includes virtual resources such as the default Favorites collection, so even a new user must send the positive timestamp returned by GET rather than -1. A stale or different value will be rejected.

Request Body
    mutations object[] required
  • 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]

    Resource the mutation applies to.

    resourceId string

    Server's ID for finding the resource during update/delete operations.

    data object

    Resource data. Format depends on resource type.

  • ]
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 post mutations endpoint

    mutations object[] required

    Array of mutations that were successfully applied on the server.

  • 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.

    timestamp float required

    Unix timestamp when the latest mutation of the resource occurred

  • ]
  • lastMutationAt float required

    Effective sync head after applying the mutations. Use it for subsequent sync requests.

Loading...