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.
Upsert a reading bookmark slot
Create or replace one reading bookmark slot. The slot keeps its stable ReadingBookmark ID while its directly stored location changes. Multiple slots may store the same location.
Request Body
The Surah number.
Possible values: [ayah]
Default value: ayah
Possible values: >= 1
Possible values: [1, 2, 3, 4, 5, 6, 7, 11, 19]
The id of the Mushaf being used.
1 = QCFV2
2 = QCFV1
3 = Indopak
4 = UthmaniHafs
5 = KFGQPCHAFS
6 = Indopak15Lines
7 = Indopak16Lines
11 = Tajweeed
19 = QCFTajweedV4
Possible values: >= 1 and <= 3
One-based reading bookmark slot. Valid values are 1, 2, and 3.
Optional custom name. Null uses the localized default name.
metadata object nullable
Possible values: >= 1
Possible values: [juz, page, surah]
Possible values: [1, 2, 3, 4, 5, 6, 7, 11, 19]
The id of the Mushaf being used.
1 = QCFV2
2 = QCFV1
3 = Indopak
4 = UthmaniHafs
5 = KFGQPCHAFS
6 = Indopak15Lines
7 = Indopak16Lines
11 = Tajweeed
19 = QCFTajweedV4
Possible values: >= 1 and <= 3
One-based reading bookmark slot. Valid values are 1, 2, and 3.
Optional custom name. Null uses the localized default name.
metadata object nullable
- 200
- 400
- 401
- 403
- 404
- 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
data object
Possible values: >= 1 and <= 3
One-based reading bookmark slot. Valid values are 1, 2, and 3.
Optional custom name. Null uses the localized default name.
Possible values: [page, juz, surah, ayah]
metadata object nullable required
Server-maintained creation timestamp; legacy rows may be null.
Server-maintained last effective change timestamp; request values are ignored.
{
"success": true,
"data": {
"id": "cmwdzxsd6000zbtkw8czs4g6w",
"slot": 1,
"name": "string",
"mushafId": 0,
"type": "page",
"group": "string",
"key": 0,
"verseNumber": 0,
"metadata": {},
"createdAt": "2026-11-13T03:19:57.443Z",
"updatedAt": "2026-11-13T03:19:57.443Z",
"clientCreatedAt": "2026-11-13T03:19:57.443Z",
"clientUpdatedAt": "2026-11-13T03:19:57.443Z"
}
}
{
"success": true,
"data": {
"id": "cmwdzxsd6000zbtkw8czs4g6w",
"slot": 1,
"name": "string",
"mushafId": 1,
"type": "page",
"group": "string",
"key": 1,
"verseNumber": 1,
"metadata": {},
"createdAt": "2026-04-02T00:00:00.000Z",
"updatedAt": "2026-04-02T00:00:00.000Z",
"clientCreatedAt": "2026-04-02T00:00:00.000Z",
"clientUpdatedAt": "2026-04-02T00:00:00.000Z"
}
}
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
}
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
}