Sharh

Ramadan Last 10 Nights Campaign

Used by thousands of students worldwide - help us reach 150 members

... / 150 members...
APIBookmarks

Bookmarks

/bookmarks

Per-user bookmarks on book lines, with an optional note. A bookmark points at a line by its zero-based position (lineId) within the book, and is unique per user, book and line. All routes require authentication and only ever touch the caller's own bookmarks.

GETList my bookmarks in a bookGETList all my bookmarksPOSTCreate a bookmarkPUTUpdate a bookmark noteDELETEDelete a bookmark
GET/bookmarks/:bookId

List my bookmarks in a book

Auth required

Returns the authenticated user's bookmarks for one book as raw bookmark documents, sorted by lineId ascending. Returns an empty array if there are none (the book itself is not looked up).

Path parameters

bookId
string
Book ObjectId

Errors

  • 401Unauthorized: No token provided
  • 403Forbidden: Invalid token, or the user does not have one of the allowed roles
  • 404User not found (the token's user no longer exists)
  • 500Internal Server Error (also returned for a malformed bookId)
Request
curl -X GET "https://app.ummahspot.com/bookmarks/:bookId" \
  -H "Authorization: Bearer $SHARH_TOKEN"
Response · 200
{
  "bookmarks": [
    {
      "_id": "6501a3b4c5d6e7f8a9b0c1d2",
      "user": "64e0b7f2a1c3d4e5f6a7b8c9",
      "book": "64f1c2a9e4b0a1d2c3e4f567",
      "lineId": 12,
      "notes": "Review the definition of kalam",
      "createdAt": "2026-09-01T09:30:00.000Z",
      "__v": 0
    }
  ]
}
GET/bookmarks/user/all

List all my bookmarks

Auth required

Returns every bookmark of the authenticated user across all books, newest first, each joined with its book title and the content of the bookmarked line. The line is resolved by using the stored lineId as a zero-based index into the book's lines. Note that in this response "lineId" is the ObjectId of the resolved line, not the numeric index that was stored. No pagination.

Errors

  • 401Unauthorized: No token provided
  • 403Forbidden: Invalid token, or the user does not have one of the allowed roles
  • 404User not found (the token's user no longer exists)
  • 500Internal Server Error (also returned when a bookmark's book no longer exists or its lineId no longer points at a line)
Request
curl -X GET "https://app.ummahspot.com/bookmarks/user/all" \
  -H "Authorization: Bearer $SHARH_TOKEN"
Response · 200
{
  "bookmarks": [
    {
      "_id": "6501a3b4c5d6e7f8a9b0c1d2",
      "bookId": "64f1c2a9e4b0a1d2c3e4f567",
      "bookTitle": "Al-Ajrumiyyah",
      "lineId": "64f1c2a9e4b0a1d2c3e4f570",
      "notes": "Review the definition of kalam",
      "createdAt": "2026-09-01T09:30:00.000Z",
      "line": {
        "Arabic": "الكلام هو اللفظ المركب المفيد بالوضع",
        "English": "Speech is a composed utterance that conveys a complete meaning by convention.",
        "commentary": "The author begins with the definition of kalam.",
        "rootwords": "ك ل م"
      }
    }
  ]
}
POST/bookmarks

Create a bookmark

Auth required

Bookmarks a line of a book for the authenticated user. Only one bookmark may exist per user, book and lineId. The book and line are not checked for existence. Returns the created bookmark document.

Body parameters

bookIdrequired
string
Book ObjectId.
lineIdrequired
number
Zero-based index of the line within the book's lines array.
notes
string
Optional note attached to the bookmark.Default: ""

Errors

  • 400{ "message": "Bookmark already exists" } — the user already bookmarked this line of this book
  • 401Unauthorized: No token provided
  • 403Forbidden: Invalid token, or the user does not have one of the allowed roles
  • 404User not found (the token's user no longer exists)
  • 500Internal Server Error (also returned when bookId or lineId is missing or invalid)
Request
curl -X POST "https://app.ummahspot.com/bookmarks" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bookId":"string","lineId":0}'
Response · 201
{
  "_id": "6501a3b4c5d6e7f8a9b0c1d2",
  "user": "64e0b7f2a1c3d4e5f6a7b8c9",
  "book": "64f1c2a9e4b0a1d2c3e4f567",
  "lineId": 12,
  "notes": "Review the definition of kalam",
  "createdAt": "2026-09-01T09:30:00.000Z",
  "__v": 0
}
PUT/bookmarks/:bookmarkId

Update a bookmark note

Auth required

Replaces the note on one of the authenticated user's bookmarks and returns the updated bookmark document. Bookmarks belonging to other users are treated as not found.

Path parameters

bookmarkId
string
Bookmark ObjectId

Body parameters

notes
string
New note text.

Errors

  • 401Unauthorized: No token provided
  • 403Forbidden: Invalid token, or the user does not have one of the allowed roles
  • 404{ "message": "Bookmark not found" } — no such bookmark owned by the caller (or plain text "User not found")
  • 500Internal Server Error (also returned for a malformed bookmarkId)
Request
curl -X PUT "https://app.ummahspot.com/bookmarks/:bookmarkId" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"notes":"string"}'
Response · 200
{
  "_id": "6501a3b4c5d6e7f8a9b0c1d2",
  "user": "64e0b7f2a1c3d4e5f6a7b8c9",
  "book": "64f1c2a9e4b0a1d2c3e4f567",
  "lineId": 12,
  "notes": "Memorise this definition",
  "createdAt": "2026-09-01T09:30:00.000Z",
  "__v": 0
}
DELETE/bookmarks/:bookmarkId

Delete a bookmark

Auth required

Permanently deletes one of the authenticated user's bookmarks. Bookmarks belonging to other users are treated as not found.

Path parameters

bookmarkId
string
Bookmark ObjectId

Errors

  • 401Unauthorized: No token provided
  • 403Forbidden: Invalid token, or the user does not have one of the allowed roles
  • 404{ "message": "Bookmark not found" } — no such bookmark owned by the caller (or plain text "User not found")
  • 500Internal Server Error (also returned for a malformed bookmarkId)
Request
curl -X DELETE "https://app.ummahspot.com/bookmarks/:bookmarkId" \
  -H "Authorization: Bearer $SHARH_TOKEN"
Response · 204
No content — the response body is empty.