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
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.
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.
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.
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 }.
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.
Possible values: >= 1
Default value: 1
Page number; a 1-based integer. Fractional values return 422.
- 200
- 400
- 401
- 403
- 404
- 409
- 422
- 429
- 500
- 502
- 503
- 504
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
- Array [
- ]
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.
Possible values: [CREATE, UPDATE, DELETE]
The type of the mutation
Possible values: [BOOKMARK, COLLECTION, COLLECTION_BOOKMARK, NOTE, READING_BOOKMARK, READING_SESSION]
The resource the mutation was applied to.
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.
BOOKMARK CREATE/UPDATE only. True when the bookmark is in the user's Favorites (virtual __default__ collection).
Unix timestamp when the latest mutation of the resource occurred
Current page number
Items per page
Total number of mutations
Whether more pages exist
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.
{
"success": true,
"data": {
"lastMutationAt": 1769986347987,
"mutations": [
{
"resource": "NOTE",
"resourceId": "slubp2n5z8t5h4fz0comix8j",
"type": "CREATE",
"data": {
"body": "This is a sample note body.",
"ranges": [
"2:255-2:255"
],
"source": "8efa4ad1-b2b9-4c9a-acc1-744dadfcb087",
"attachedEntities": [],
"clientCreatedAt": "2026-05-19T10:15:30.000Z",
"clientUpdatedAt": "2026-05-19T10:16:30.000Z"
},
"timestamp": 1769526422109
},
{
"resource": "BOOKMARK",
"resourceId": "j1rnpmr1zu3ytynk6e0w5zp0",
"type": "UPDATE",
"data": {
"bookmarkType": "ayah",
"bookmarkGroup": "verses_6236",
"key": 18,
"verseNumber": 3,
"isInDefaultCollection": true,
"clientCreatedAt": "2026-05-19T10:15:30.000Z",
"clientUpdatedAt": "2026-05-19T10:16:30.000Z"
},
"timestamp": 1769985812916
},
{
"resource": "COLLECTION",
"resourceId": "yyshgj0mv0z27chfmbd6hczt",
"type": "UPDATE",
"data": {
"name": "Collection 1",
"slug": "collection-1",
"isPrivate": true,
"clientCreatedAt": "2026-05-19T10:15:30.000Z",
"clientUpdatedAt": "2026-05-19T10:16:30.000Z"
},
"timestamp": 1769986347985
},
{
"resource": "COLLECTION_BOOKMARK",
"type": "CREATE",
"data": {
"collectionId": "yyshgj0mv0z27chfmbd6hczt",
"bookmarkId": "j1rnpmr1zu3ytynk6e0w5zp0",
"clientCreatedAt": "2026-05-19T10:15:30.000Z",
"clientUpdatedAt": "2026-05-19T10:16:30.000Z"
},
"timestamp": 1769986347986
},
{
"resource": "READING_SESSION",
"resourceId": "rs8w98f0mv0z27chfmbd6r4x",
"type": "UPDATE",
"data": {
"chapterNumber": 2,
"verseNumber": 255,
"clientCreatedAt": "2026-05-19T10:15:30.000Z",
"clientUpdatedAt": "2026-05-19T10:16:30.000Z"
},
"timestamp": 1769986347987
}
],
"page": 1,
"limit": 100,
"total": 5,
"hasMore": false
}
}
{
"success": true,
"data": {
"lastMutationAt": 1769986347987,
"mutations": [
{
"resource": "NOTE",
"resourceId": "slubp2n5z8t5h4fz0comix8j",
"type": "CREATE",
"data": {
"body": "This is a sample note body.",
"ranges": [
"2:255-2:255"
],
"source": "8efa4ad1-b2b9-4c9a-acc1-744dadfcb087",
"attachedEntities": [],
"clientCreatedAt": "2026-05-19T10:15:30.000Z",
"clientUpdatedAt": "2026-05-19T10:16:30.000Z"
},
"timestamp": 1769526422109
},
{
"resource": "BOOKMARK",
"resourceId": "j1rnpmr1zu3ytynk6e0w5zp0",
"type": "UPDATE",
"data": {
"bookmarkType": "ayah",
"bookmarkGroup": "verses_6236",
"key": 18,
"verseNumber": 3,
"isInDefaultCollection": true,
"clientCreatedAt": "2026-05-19T10:15:30.000Z",
"clientUpdatedAt": "2026-05-19T10:16:30.000Z"
},
"timestamp": 1769985812916
},
{
"resource": "COLLECTION",
"resourceId": "yyshgj0mv0z27chfmbd6hczt",
"type": "UPDATE",
"data": {
"name": "Collection 1",
"slug": "collection-1",
"isPrivate": true,
"clientCreatedAt": "2026-05-19T10:15:30.000Z",
"clientUpdatedAt": "2026-05-19T10:16:30.000Z"
},
"timestamp": 1769986347985
},
{
"resource": "COLLECTION_BOOKMARK",
"type": "CREATE",
"data": {
"collectionId": "yyshgj0mv0z27chfmbd6hczt",
"bookmarkId": "j1rnpmr1zu3ytynk6e0w5zp0",
"clientCreatedAt": "2026-05-19T10:15:30.000Z",
"clientUpdatedAt": "2026-05-19T10:16:30.000Z"
},
"timestamp": 1769986347986
},
{
"resource": "READING_SESSION",
"resourceId": "rs8w98f0mv0z27chfmbd6r4x",
"type": "UPDATE",
"data": {
"chapterNumber": 2,
"verseNumber": 255,
"clientCreatedAt": "2026-05-19T10:15:30.000Z",
"clientUpdatedAt": "2026-05-19T10:16:30.000Z"
},
"timestamp": 1769986347987
}
],
"page": 1,
"limit": 100,
"total": 5,
"hasMore": false
}
}
The request is missing required parameters or is invalid.
Schema
{
"message": "The request is missing required headers or is invalid",
"type": "invalid_request",
"success": false
}
{
"message": "The request is missing required headers or is invalid",
"type": "invalid_request",
"success": false
}
The request is unauthorized.
Schema
{
"message": "The request requires user authentication",
"type": "unauthorized",
"success": false
}
{
"message": "The request requires user authentication",
"type": "unauthorized",
"success": false
}
Forbidden error. Can either be due to access token not being passed, having been expired or the caller trying to access a resource without enough permissions.
Schema
{
"message": "The server understood the request, but refuses to authorize it",
"type": "forbidden",
"success": false
}
{
"message": "The server understood the request, but refuses to authorize it",
"type": "forbidden",
"success": false
}
Not Found. The resource being accessed does not exist.
Schema
{
"message": "The requested resource could not be found",
"type": "not_found",
"success": false
}
{
"message": "The requested resource could not be found",
"type": "not_found",
"success": false
}
Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.
Schema
error object
{
"success": false,
"error": {
"code": "OutOfSyncError",
"message": "Invalid lastMutationAt, please re-sync your data and try again."
}
}
{
"success": false,
"error": {
"code": "OutOfSyncError",
"message": "Invalid lastMutationAt, please re-sync your data and try again."
}
}
Validation Error. The request includes one or more invalid params. Please check the request params and try again.
Schema
{
"message": "The request was well-formed but was unable to be followed due to semantic errors",
"type": "unprocessable_entity",
"success": false
}
{
"message": "The request was well-formed but was unable to be followed due to semantic errors",
"type": "unprocessable_entity",
"success": false
}
Too many requests, please try again later.
Schema
{
"message": "Too many requests, please try again later",
"type": "rate_limit_exceeded",
"success": false
}
{
"message": "Too many requests, please try again later",
"type": "rate_limit_exceeded",
"success": false
}
Server Error. Something went wrong, try again later.
Schema
{
"message": "The server encountered an internal error and was unable to complete your request",
"type": "internal_server_error",
"success": false
}
{
"message": "The server encountered an internal error and was unable to complete your request",
"type": "internal_server_error",
"success": false
}
Invalid response from the upstream server
Schema
{
"message": "The server was acting as a gateway or proxy and received an invalid response from the upstream server",
"type": "bad_gateway",
"success": false
}
{
"message": "The server was acting as a gateway or proxy and received an invalid response from the upstream server",
"type": "bad_gateway",
"success": false
}
The server is currently unable to handle the request due to a temporary overload or scheduled maintenance
Schema
{
"message": "The server is currently unable to handle the request due to a temporary overload or scheduled maintenance",
"type": "service_unavailable",
"success": false
}
{
"message": "The server is currently unable to handle the request due to a temporary overload or scheduled maintenance",
"type": "service_unavailable",
"success": false
}
The server did not receive a timely response from the upstream server.
Schema
{
"message": "The server was acting as a gateway or proxy and did not receive a timely response from the upstream server",
"type": "gateway_timeout",
"success": false
}
{
"message": "The server was acting as a gateway or proxy and did not receive a timely response from the upstream server",
"type": "gateway_timeout",
"success": false
}