Sync local mutations​
An endpoint to sync local mutations to the server.
Query Parameters
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.
Request Body
- Array [
- ]
mutations object[] required
Possible values: [CREATE, UPDATE, DELETE]
The type of the mutation
Possible values: [BOOKMARK, COLLECTION, COLLECTION_BOOKMARK, NOTE]
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
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.
Schema
- Array [
- ]
data object
Response schema for post mutations endpoint
mutations object[]
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]
The resource the mutation was applied to.
The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).
data object
The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.
Unix timestamp when the latest mutation of the resource occurred
Current page number
Items per page
Total number of mutations
Whether more pages exist
Timestamp of the latest mutation that was applied on the server. This should be used for subsequent sync requests.
{
"success": true,
"data": {
"mutations": [
{
"type": "CREATE",
"resource": "BOOKMARK",
"resourceId": "u54maufl0ftmarp73ei0hg64",
"data": {
"bookmarkType": "ayah",
"bookmarkGroup": "verses_6236",
"key": 6,
"verseNumber": 3
},
"timestamp": 1769340915572
},
{
"type": "UPDATE",
"resource": "COLLECTION",
"resourceId": "na6orcv0pbcomiphmkv0yhma",
"data": {
"name": "New collection!",
"slug": "new-collection",
"isPrivate": true
},
"timestamp": 1769340915572
},
{
"type": "CREATE",
"resource": "COLLECTION_BOOKMARK",
"data": {
"collection": "na6orcv0pbcomiphmkv0yhma",
"bookmark": "u54maufl0ftmarp73ei0hg64"
},
"timestamp": 1769340915575
},
{
"type": "DELETE",
"resource": "NOTE",
"resourceId": "his2lubkxxr3l102nqptmnur",
"data": {},
"timestamp": 1769341113173
}
],
"page": 1,
"limit": 100,
"total": 150,
"hasMore": true,
"lastMutationAt": 1731636500303
}
}
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
}
The request is unauthorized.
Schema
{
"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
}
Not Found. The resource being accessed does not exist.
Schema
{
"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."
}
}
{
"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.
Schema
error object
{
"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.
Schema
{
"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
}
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
}
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
}
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
}