Sync local mutations

An endpoint to sync local mutations to the server.

Query Parameters

lastSyncedAt 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, READING_SESSION, PREFERENCE, NOTE]
The resource the mutation has been applied to.
resourceId string
The server's id of the resource the mutation will be applied to. This will be required for some resources when updating/deleting and is used by the server to find the relevant resource.
data object
The data or the resource. The format of the data will depend on the resource type.
]

Responses

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

---

Request has been handled successfully.

application/json

Schema

Example (from schema)

---

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, READING_SESSION, PREFERENCE, NOTE]

The resource the mutation was applied to.

resourceId string

The id of the resource the mutation was applied to. Will not be present if the mutation was applied to certain resource without specific ID e.g. Preference.

data object

The latest version of the data of the resource that was mutated

timestamp float required

Unix timestamp when the latest mutation of the resource occurred

]

newLastSyncedAt float required

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": "lqc794i0qnxq4pdlfanfbd2r",
        "data": {
          "bookmarkType": "ayah",
          "bookmarkGroup": "verses_6236",
          "key": 6,
          "verseNumber": 3
        },
        "timestamp": 1731636500303
      }
    ],
    "newLastSyncedAt": 1731636500303
  }
}

The request is missing required parameters or is invalid.

application/json

Schema

Example (from schema)

---

Schema

message string
type string
success boolean

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

---

Schema

message string
type string
success boolean

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

---

Schema

message string
type string
success boolean

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

---

Schema

message string
type string
success boolean

{
  "message": "The requested resource could not be found",
  "type": "not_found",
  "success": false
}

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

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

---

Schema

message string
type string
success boolean

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

Out of sync

---

Schema

success boolean
error object
code string
message string

{
  "success": false,
  "error": {
    "code": "OutOfSyncError",
    "message": "Invalid lastSyncedAt, please re-sync your data and try again."
  }
}

{
  "success": false,
  "error": {
    "code": "OutOfSyncError",
    "message": "Invalid lastSyncedAt, please re-sync your data and try again."
  }
}

Invalid response from the upstream server

application/json

Schema

Example (from schema)

---

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
}

The server is currently unable to handle the request due to a temporary overload or scheduled maintenance

application/json

Schema

Example (from schema)

---

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
}

The server did not receive a timely response from the upstream server.

application/json

Schema

Example (from schema)

---

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
}

Loading...