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
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
- Array [
- ]
mutations object[] required
Possible values: [CREATE, UPDATE, DELETE]
The type of the mutation
Possible values: [BOOKMARK, COLLECTION, COLLECTION_BOOKMARK, NOTE, READING_BOOKMARK, READING_SESSION]
Resource the mutation applies to.
Server's ID for finding the resource during update/delete operations.
data object
Resource data. Format depends on resource type.
- 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 post mutations endpoint
mutations object[] required
Array of mutations that were successfully applied on the server.
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.
Unix timestamp when the latest mutation of the resource occurred
Effective sync head after applying the mutations. Use it for subsequent sync requests.
{
"success": true,
"data": {
"lastMutationAt": 1769340915578,
"mutations": [
{
"resource": "BOOKMARK",
"type": "CREATE",
"data": {
"key": 2,
"type": "ayah",
"verseNumber": 3,
"isReading": false,
"mushafId": 4,
"mushaf": 4
},
"resourceId": "u54maufl0ftmarp73ei0hg64",
"timestamp": 1769340915572
},
{
"resource": "COLLECTION",
"type": "CREATE",
"data": {
"name": "Woman in Quran"
},
"resourceId": "na6orcv0pbcomiphmkv0yhma",
"timestamp": 1769340915573
},
{
"resource": "COLLECTION",
"type": "UPDATE",
"resourceId": "na6orcv0pbcomiphmkv0yhma",
"data": {
"name": "string"
},
"timestamp": 1769340915574
},
{
"resource": "NOTE",
"type": "CREATE",
"data": {
"body": "This is a sample note body.",
"ranges": [
"2:255-2:257"
]
},
"resourceId": "his2lubkxxr3l102nqptmnur",
"timestamp": 1769340915575
},
{
"resource": "NOTE",
"type": "UPDATE",
"resourceId": "his2lubkxxr3l102nqptmnur",
"data": {
"body": "This is a sample note body."
},
"timestamp": 1769340915576
},
{
"resource": "READING_SESSION",
"type": "CREATE",
"data": {
"chapterNumber": 2,
"verseNumber": 255
},
"resourceId": "qk7j1ub8xxr3l102nqptxy9w",
"timestamp": 1769340915577
},
{
"resource": "READING_SESSION",
"type": "UPDATE",
"resourceId": "qk7j1ub8xxr3l102nqptxy9w",
"data": {
"chapterNumber": 2,
"verseNumber": 255
},
"timestamp": 1769340915578
}
]
}
}
{
"success": true,
"data": {
"lastMutationAt": 1769340915578,
"mutations": [
{
"resource": "BOOKMARK",
"type": "CREATE",
"data": {
"key": 2,
"type": "ayah",
"verseNumber": 3,
"isReading": false,
"mushafId": 4,
"mushaf": 4
},
"resourceId": "u54maufl0ftmarp73ei0hg64",
"timestamp": 1769340915572
},
{
"resource": "COLLECTION",
"type": "CREATE",
"data": {
"name": "Woman in Quran"
},
"resourceId": "na6orcv0pbcomiphmkv0yhma",
"timestamp": 1769340915573
},
{
"resource": "COLLECTION",
"type": "UPDATE",
"resourceId": "na6orcv0pbcomiphmkv0yhma",
"data": {
"name": "string"
},
"timestamp": 1769340915574
},
{
"resource": "NOTE",
"type": "CREATE",
"data": {
"body": "This is a sample note body.",
"ranges": [
"2:255-2:257"
]
},
"resourceId": "his2lubkxxr3l102nqptmnur",
"timestamp": 1769340915575
},
{
"resource": "NOTE",
"type": "UPDATE",
"resourceId": "his2lubkxxr3l102nqptmnur",
"data": {
"body": "This is a sample note body."
},
"timestamp": 1769340915576
},
{
"resource": "READING_SESSION",
"type": "CREATE",
"data": {
"chapterNumber": 2,
"verseNumber": 255
},
"resourceId": "qk7j1ub8xxr3l102nqptxy9w",
"timestamp": 1769340915577
},
{
"resource": "READING_SESSION",
"type": "UPDATE",
"resourceId": "qk7j1ub8xxr3l102nqptxy9w",
"data": {
"chapterNumber": 2,
"verseNumber": 255
},
"timestamp": 1769340915578
}
]
}
}
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. Either the request is not allowed (invalid token or missing client scopes for a mutation resource), or a mutation targets a resource owned by another user. Only the latter includes details.error.details.mutationIndex. The public Gateway nests the backend error envelope in details; direct backend calls return that nested envelope as their response. Errors generated by the Gateway itself can omit details.
Schema
Possible values: [false]
details object
error object
details object
Extra error data. Errors caused by a single mutation include mutationIndex. Request-level errors, such as the 409 OutOfSyncError and the 403 from authentication or the client-scope check, have no mutationIndex; their details is empty or absent. Some errors add other keys, such as name.
Index of the failing mutation in the request mutations array.
{
"success": false,
"type": "forbidden",
"message": "string",
"details": {
"success": false,
"error": {
"code": "ForbiddenError",
"message": "You don't have permission",
"details": {
"mutationIndex": 0
}
}
}
}
A mutation targets a resource owned by another user
{
"success": false,
"type": "forbidden",
"message": "You don't have permission",
"details": {
"success": false,
"error": {
"code": "ForbiddenError",
"message": "You don't have permission",
"details": {
"mutationIndex": 0
}
}
}
}
The client lacks a scope required by one of the mutation resources
{
"success": false,
"type": "forbidden",
"message": "You don't have permission",
"details": {
"success": false,
"error": {
"code": "ForbiddenError",
"message": "You don't have permission",
"details": {}
}
}
}
The Gateway rejects the request before it reaches the backend
{
"success": false,
"type": "insufficient_scope",
"message": "The access token does not have the required scopes"
}
Not Found. A mutation targets a resource that does not exist; details.error.details.mutationIndex identifies it. The public Gateway nests the backend error envelope in details; direct backend calls return that nested envelope as their response. Errors generated by the Gateway itself can omit details.
Schema
Possible values: [false]
details object
error object
details object
Extra error data. Errors caused by a single mutation include mutationIndex. Request-level errors, such as the 409 OutOfSyncError and the 403 from authentication or the client-scope check, have no mutationIndex; their details is empty or absent. Some errors add other keys, such as name.
Index of the failing mutation in the request mutations array.
{
"success": false,
"type": "not_found",
"message": "string",
"details": {
"success": false,
"error": {
"code": "NotFoundError",
"message": "Note not found",
"details": {
"mutationIndex": 0
}
}
}
}
An UPDATE targets a note that does not exist
{
"success": false,
"type": "not_found",
"message": "Note not found",
"details": {
"success": false,
"error": {
"code": "NotFoundError",
"message": "Note not found",
"details": {
"mutationIndex": 1
}
}
}
}
Conflict. Either a mutation violates a uniqueness rule (UniqueViolationError, with details.error.details.mutationIndex), or the request is out of sync. Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. The public Gateway nests the backend error envelope in details; direct backend calls return that nested envelope as their response. Errors generated by the Gateway itself can omit details.
Schema
Possible values: [false]
details object
error object
details object
Extra error data. Errors caused by a single mutation include mutationIndex. Request-level errors, such as the 409 OutOfSyncError and the 403 from authentication or the client-scope check, have no mutationIndex; their details is empty or absent. Some errors add other keys, such as name.
Index of the failing mutation in the request mutations array.
{
"success": false,
"type": "service_error",
"message": "string",
"details": {
"success": false,
"error": {
"code": "UniqueViolationError",
"message": "You already have a collection with this name",
"details": {
"mutationIndex": 0
}
}
}
}
A collection CREATE or rename uses a name that already exists
{
"success": false,
"type": "service_error",
"message": "You already have a collection with this name",
"details": {
"success": false,
"error": {
"code": "UniqueViolationError",
"message": "You already have a collection with this name",
"details": {
"name": "DUPLICATE",
"mutationIndex": 0
}
}
}
}
Out of sync
{
"success": false,
"type": "service_error",
"message": "Invalid lastMutationAt, please re-sync your data and try again.",
"details": {
"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. The public Gateway nests the backend error envelope in details; direct backend calls return that nested envelope as their response. Errors generated by the Gateway itself can omit details.
Schema
Possible values: [false]
details object
error object
details object
Extra error data. Errors caused by a single mutation include mutationIndex. Request-level errors, such as the 409 OutOfSyncError and the 403 from authentication or the client-scope check, have no mutationIndex; their details is empty or absent. Some errors add other keys, such as name.
Index of the failing mutation in the request mutations array.
{
"success": false,
"type": "unprocessable_entity",
"message": "string",
"details": {
"success": false,
"error": {
"code": "ValidationError",
"message": "Invalid mutations",
"details": {
"mutationIndex": 0
}
}
}
}
Invalid mutations format
{
"success": false,
"type": "unprocessable_entity",
"message": "Invalid mutations",
"details": {
"success": false,
"error": {
"code": "ValidationError",
"message": "Invalid mutations"
}
}
}
Too many mutations
{
"success": false,
"type": "unprocessable_entity",
"message": "Mutations must not exceed 100",
"details": {
"success": false,
"error": {
"code": "ValidationError",
"message": "Mutations must not exceed 100"
}
}
}
Missing resource
{
"success": false,
"type": "unprocessable_entity",
"message": "Missing resource at mutation[0]",
"details": {
"success": false,
"error": {
"code": "ValidationError",
"message": "Missing resource at mutation[0]",
"details": {
"mutationIndex": 0
}
}
}
}
Invalid resource
{
"success": false,
"type": "unprocessable_entity",
"message": "Invalid resource: \"invalidResource\" at mutation[0]",
"details": {
"success": false,
"error": {
"code": "ValidationError",
"message": "Invalid resource: \"invalidResource\" at mutation[0]",
"details": {
"mutationIndex": 0
}
}
}
}
Missing mutation type
{
"success": false,
"type": "unprocessable_entity",
"message": "Missing mutation type at mutation[0]",
"details": {
"success": false,
"error": {
"code": "ValidationError",
"message": "Missing mutation type at mutation[0]",
"details": {
"mutationIndex": 0
}
}
}
}
Invalid mutation type
{
"success": false,
"type": "unprocessable_entity",
"message": "Invalid mutation type: \"invalidType\" at mutation[0]",
"details": {
"success": false,
"error": {
"code": "ValidationError",
"message": "Invalid mutation type: \"invalidType\" at mutation[0]",
"details": {
"mutationIndex": 0
}
}
}
}
Missing resourceId
{
"success": false,
"type": "unprocessable_entity",
"message": "Missing resourceId at mutation[0]",
"details": {
"success": false,
"error": {
"code": "ValidationError",
"message": "Missing resourceId at mutation[0]",
"details": {
"mutationIndex": 0
}
}
}
}
Invalid resourceId type
{
"success": false,
"type": "unprocessable_entity",
"message": "Invalid resourceId at mutation[0]",
"details": {
"success": false,
"error": {
"code": "ValidationError",
"message": "Invalid resourceId at mutation[0]",
"details": {
"mutationIndex": 0
}
}
}
}
Missing data
{
"success": false,
"type": "unprocessable_entity",
"message": "Missing data at mutation[0]",
"details": {
"success": false,
"error": {
"code": "ValidationError",
"message": "Missing data at mutation[0]",
"details": {
"mutationIndex": 0
}
}
}
}
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. When applying a specific mutation failed, details.error.details.mutationIndex identifies it. The public Gateway nests the backend error envelope in details; direct backend calls return that nested envelope as their response. Errors generated by the Gateway itself can omit details.
Schema
Possible values: [false]
details object
error object
details object
Extra error data. Errors caused by a single mutation include mutationIndex. Request-level errors, such as the 409 OutOfSyncError and the 403 from authentication or the client-scope check, have no mutationIndex; their details is empty or absent. Some errors add other keys, such as name.
Index of the failing mutation in the request mutations array.
{
"success": false,
"type": "internal_server_error",
"message": "string",
"details": {
"success": false,
"error": {
"code": "ServerError",
"message": "Something went wrong",
"details": {
"mutationIndex": 0
}
}
}
}
Applying a mutation failed unexpectedly
{
"success": false,
"type": "internal_server_error",
"message": "Something went wrong",
"details": {
"success": false,
"error": {
"code": "ServerError",
"message": "Something went wrong",
"details": {
"mutationIndex": 2
}
}
}
}
The request failed outside any single mutation
{
"success": false,
"type": "internal_server_error",
"message": "Something went wrong",
"details": {
"success": false,
"error": {
"code": "ServerError",
"message": "Something went wrong"
}
}
}
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
}