User-related API environment

Pre-live user-related API docs

These pages describe the Pre-live user-related API stack.

Use pre-live OAuth credentials, pre-live API base URLs, and pre-live app URLs when following this documentation. Keep your OAuth flow, API requests, callback URLs, and manual testing within the pre-live environment.

• Use prelive.quran.com for auth-related testing.
• Use prelive.quranreflect.org for Quran Reflect paths where applicable.
• Do not mix production sessions or production user data with pre-live testing.

Sync local mutations

An endpoint to sync local mutations to the server.

Query Parameters

lastMutationAt float required

The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.

application/json

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_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

• 200
• 400
• 401
• 403
• 404
• 409
• 422
• 429
• 500
• 502
• 503
• 504

---

Request has been handled successfully.

Response Headers

• X-Mutation-At string

  Unix timestamp (milliseconds) of the latest mutation for the user. Clients should store this value and include it in subsequent mutation requests for optimistic concurrency control.

application/json

Schema

Example (from schema)

Example

---

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_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. For create/update mutations, clientCreatedAt and clientUpdatedAt represent the client-local action timestamps, while timestamp represents the server sync mutation timestamp.

timestamp float required

Unix timestamp when the latest mutation of the resource occurred

]

lastMutationAt float required

Timestamp of the latest mutation that was applied on the server. This should be used 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,
          "clientCreatedAt": "2026-05-19T10:15:30.000Z",
          "clientUpdatedAt": "2026-05-19T10:16:30.000Z"
        },
        "resourceId": "u54maufl0ftmarp73ei0hg64",
        "timestamp": 1769340915572
      },
      {
        "resource": "COLLECTION",
        "type": "CREATE",
        "data": {
          "name": "Woman in Quran",
          "clientCreatedAt": "2026-05-19T10:15:30.000Z",
          "clientUpdatedAt": "2026-05-19T10:16:30.000Z"
        },
        "resourceId": "na6orcv0pbcomiphmkv0yhma",
        "timestamp": 1769340915573
      },
      {
        "resource": "COLLECTION",
        "type": "UPDATE",
        "resourceId": "na6orcv0pbcomiphmkv0yhma",
        "data": {
          "name": "string",
          "clientCreatedAt": "2026-05-19T10:15:30.000Z",
          "clientUpdatedAt": "2026-05-19T10:16:30.000Z"
        },
        "timestamp": 1769340915574
      },
      {
        "resource": "NOTE",
        "type": "CREATE",
        "data": {
          "body": "This is a sample note body.",
          "saveToQR": true,
          "attachedEntity": {
            "entityId": "entity123",
            "entityType": "reflection",
            "entityMetadata": {
              "key": "value"
            }
          },
          "ranges": [
            "2:255-2:257"
          ],
          "clientCreatedAt": "2026-05-19T10:15:30.000Z",
          "clientUpdatedAt": "2026-05-19T10:16:30.000Z"
        },
        "resourceId": "his2lubkxxr3l102nqptmnur",
        "timestamp": 1769340915575
      },
      {
        "resource": "NOTE",
        "type": "UPDATE",
        "resourceId": "his2lubkxxr3l102nqptmnur",
        "data": {
          "body": "This is a sample note body.",
          "saveToQR": false,
          "clientCreatedAt": "2026-05-19T10:15:30.000Z",
          "clientUpdatedAt": "2026-05-19T10:16:30.000Z"
        },
        "timestamp": 1769340915576
      },
      {
        "resource": "READING_SESSION",
        "type": "CREATE",
        "data": {
          "chapterNumber": 2,
          "verseNumber": 255,
          "clientCreatedAt": "2026-05-19T10:15:30.000Z",
          "clientUpdatedAt": "2026-05-19T10:16:30.000Z"
        },
        "resourceId": "qk7j1ub8xxr3l102nqptxy9w",
        "timestamp": 1769340915577
      },
      {
        "resource": "READING_SESSION",
        "type": "UPDATE",
        "resourceId": "qk7j1ub8xxr3l102nqptxy9w",
        "data": {
          "chapterNumber": 2,
          "verseNumber": 255,
          "clientUpdatedAt": "2026-05-19T10:16:30.000Z"
        },
        "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,
          "clientCreatedAt": "2026-05-19T10:15:30.000Z",
          "clientUpdatedAt": "2026-05-19T10:16:30.000Z"
        },
        "resourceId": "u54maufl0ftmarp73ei0hg64",
        "timestamp": 1769340915572
      },
      {
        "resource": "COLLECTION",
        "type": "CREATE",
        "data": {
          "name": "Woman in Quran",
          "clientCreatedAt": "2026-05-19T10:15:30.000Z",
          "clientUpdatedAt": "2026-05-19T10:16:30.000Z"
        },
        "resourceId": "na6orcv0pbcomiphmkv0yhma",
        "timestamp": 1769340915573
      },
      {
        "resource": "COLLECTION",
        "type": "UPDATE",
        "resourceId": "na6orcv0pbcomiphmkv0yhma",
        "data": {
          "name": "string",
          "clientCreatedAt": "2026-05-19T10:15:30.000Z",
          "clientUpdatedAt": "2026-05-19T10:16:30.000Z"
        },
        "timestamp": 1769340915574
      },
      {
        "resource": "NOTE",
        "type": "CREATE",
        "data": {
          "body": "This is a sample note body.",
          "saveToQR": true,
          "attachedEntity": {
            "entityId": "entity123",
            "entityType": "reflection",
            "entityMetadata": {
              "key": "value"
            }
          },
          "ranges": [
            "2:255-2:257"
          ],
          "clientCreatedAt": "2026-05-19T10:15:30.000Z",
          "clientUpdatedAt": "2026-05-19T10:16:30.000Z"
        },
        "resourceId": "his2lubkxxr3l102nqptmnur",
        "timestamp": 1769340915575
      },
      {
        "resource": "NOTE",
        "type": "UPDATE",
        "resourceId": "his2lubkxxr3l102nqptmnur",
        "data": {
          "body": "This is a sample note body.",
          "saveToQR": false,
          "clientCreatedAt": "2026-05-19T10:15:30.000Z",
          "clientUpdatedAt": "2026-05-19T10:16:30.000Z"
        },
        "timestamp": 1769340915576
      },
      {
        "resource": "READING_SESSION",
        "type": "CREATE",
        "data": {
          "chapterNumber": 2,
          "verseNumber": 255,
          "clientCreatedAt": "2026-05-19T10:15:30.000Z",
          "clientUpdatedAt": "2026-05-19T10:16:30.000Z"
        },
        "resourceId": "qk7j1ub8xxr3l102nqptxy9w",
        "timestamp": 1769340915577
      },
      {
        "resource": "READING_SESSION",
        "type": "UPDATE",
        "resourceId": "qk7j1ub8xxr3l102nqptxy9w",
        "data": {
          "chapterNumber": 2,
          "verseNumber": 255,
          "clientUpdatedAt": "2026-05-19T10:16:30.000Z"
        },
        "timestamp": 1769340915578
      }
    ]
  }
}

The request is missing required parameters or is invalid.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "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.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "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.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "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.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "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.

application/json

Schema

Example (from schema)

Out of sync

First sync - wrong lastMutationAt

---

Schema

success boolean
error object
code string
message string

{
  "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."
  }
}

{
  "success": false,
  "error": {
    "code": "OutOfSyncError",
    "message": "First sync detected. Please use lastMutationAt=-1 for initial sync."
  }
}

Validation Error. The request includes one or more invalid params.

application/json

Schema

Example (from schema)

Invalid mutations format

Too many mutations

Missing resource

Invalid resource

Missing mutation type

Invalid mutation type

Missing resourceId

Invalid resourceId type

Missing data

---

Schema

success boolean
error object
code string
message string

{
  "success": false,
  "error": {
    "code": "ValidationError",
    "message": "Invalid mutations"
  }
}

{
  "success": false,
  "error": {
    "code": "ValidationError",
    "message": "Invalid mutations"
  }
}

{
  "success": false,
  "error": {
    "code": "ValidationError",
    "message": "Mutations must not exceed 100"
  }
}

{
  "success": false,
  "error": {
    "code": "ValidationError",
    "message": "Missing resource at mutation[0]"
  }
}

{
  "success": false,
  "error": {
    "code": "ValidationError",
    "message": "Invalid resource: \"invalidResource\" at mutation[0]"
  }
}

{
  "success": false,
  "error": {
    "code": "ValidationError",
    "message": "Missing mutation type at mutation[0]"
  }
}

{
  "success": false,
  "error": {
    "code": "ValidationError",
    "message": "Invalid mutation type: \"invalidType\" at mutation[0]"
  }
}

{
  "success": false,
  "error": {
    "code": "ValidationError",
    "message": "Missing resourceId at mutation[0]"
  }
}

{
  "success": false,
  "error": {
    "code": "ValidationError",
    "message": "Invalid resourceId at mutation[0]"
  }
}

{
  "success": false,
  "error": {
    "code": "ValidationError",
    "message": "Missing data at mutation[0]"
  }
}

Too many requests, please try again later.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "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.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "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

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "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

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "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.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "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
}

Loading...