Sharh

Ramadan Last 10 Nights Campaign

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

... / 150 members...
APINotes

Notes

/notes

Private, sectioned study notes that live inside folders. Section bodies are stored as strings (the Sharh editor stores BlockNote JSON in them). Also includes web clipping into a note and importing whole books from the usul.ai library as notes.

GETSearch the usul.ai book catalogueGETList notes in a folderGETGet a note with paginated sectionsPOSTClip text into an existing notePOSTCreate a notePUTUpdate a notePOSTAdd a section to a notePUTUpdate a sectionDELETEDelete a sectionDELETEDelete a notePOSTImport a usul.ai book as a note
GET/notes/search-books

Search the usul.ai book catalogue

Auth required

Proxies the search to the external usul.ai API (`GET https://api.usul.ai/search/books`) with the given `q`, `limit` and `locale`, and returns the upstream JSON body unchanged. Use the results to pick a book version for `POST /notes/import-book`.

Query parameters

qrequired
string
Search query.
limit
number
Maximum number of results; parsed with parseInt and forwarded to usul.ai.Default: 20
locale
string
Locale code forwarded to usul.ai.Default: en

Errors

  • 400Query parameter `q` is missing
  • 401No token provided
  • 403Invalid token
  • 500The request to the usul.ai API failed
Request
curl -X GET "https://app.ummahspot.com/notes/search-books" \
  -H "Authorization: Bearer $SHARH_TOKEN"
Response · 200
The JSON response of the usul.ai book search API, passed through unchanged. Its shape is defined by usul.ai, not by Sharh.
GET/notes/folder/:folderId

List notes in a folder

Auth required

Returns a summary of every note in the folder, sorted by `lastModified` descending. Section contents are not included, only a `sectionCount`. The folder must be owned by the authenticated user.

Path parameters

folderId
string
Folder ObjectId

Errors

  • 401No token provided
  • 403Invalid token, or the folder belongs to another user
  • 404No folder with the given ID exists
  • 500Unexpected server error (including a malformed folder ID)
Request
curl -X GET "https://app.ummahspot.com/notes/folder/:folderId" \
  -H "Authorization: Bearer $SHARH_TOKEN"
Response · 200
{
  "notes": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0d1",
      "title": "Al-Ajrumiyyah study notes",
      "sectionCount": 4,
      "createdAt": "2026-08-02T09:15:22.481Z",
      "lastModified": "2026-09-10T18:42:07.113Z"
    }
  ]
}
GET/notes/:noteId

Get a note with paginated sections

Auth required

Returns a single note. Sections are paginated in stored order: the response contains sections `(page - 1) * limit` up to `page * limit`, plus a `pagination` object. The note must be owned by the authenticated user.

Path parameters

noteId
string
Note ObjectId

Query parameters

page
number
1-based page of sections to return.Default: 1
limit
number
Number of sections per page.Default: 10

Errors

  • 401No token provided
  • 403Invalid token, or the note belongs to another user
  • 404No note with the given ID exists
  • 500Unexpected server error (including a malformed note ID)
Request
curl -X GET "https://app.ummahspot.com/notes/:noteId" \
  -H "Authorization: Bearer $SHARH_TOKEN"
Response · 200
{
  "id": "66f1a2b3c4d5e6f7a8b9c0d1",
  "title": "Al-Ajrumiyyah study notes",
  "sections": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0e1",
      "title": "Chapter 1: Kalam",
      "notes": "[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Kalam is a composed, beneficial utterance.\",\"styles\":{}}]}]"
    }
  ],
  "folderId": "66f19f00c4d5e6f7a8b9bf10",
  "createdAt": "2026-08-02T09:15:22.481Z",
  "lastModified": "2026-09-10T18:42:07.113Z",
  "pagination": {
    "currentPage": 1,
    "totalPages": 1,
    "totalSections": 4,
    "sectionsPerPage": 10,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}
POST/notes/clip

Clip text into an existing note

Auth required

Quick capture: converts the plain text in `body` to BlockNote paragraph blocks (one per non-empty line) and adds it to a note owned by the authenticated user. If a section whose title exactly equals `section` exists, the blocks are appended to it; otherwise a new section with that title is created. When `section` is omitted the section titled "Clips" is used (and created if missing). If `url` is given, a final "Source: <link>" paragraph is appended. If `isArabic` is true, paragraphs are right-aligned and marked with the `arabicText` style. Although the handler treats `noteId` as optional, a request without it is rejected with 400.

Body parameters

bodyrequired
string
Plain text to clip. Split on newlines into paragraphs.
noteIdrequired
string
ObjectId of the note to add the clip to.
section
string
Title of the section to append to (exact match); created if it does not exist.Default: Clips
url
string
Source URL, appended as a "Source:" link paragraph.
isArabic
boolean
Right-align the text and apply the Arabic text style.Default: false

Errors

  • 400`body` is missing, or `noteId` is missing
  • 401No token provided
  • 403Invalid token, or the note belongs to another user
  • 404No note with the given ID exists
  • 500Unexpected server error (including a malformed note ID)
Request
curl -X POST "https://app.ummahspot.com/notes/clip" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body":"string","noteId":"string"}'
Response · 200
{
  "message": "Clip added successfully",
  "noteId": "66f1a2b3c4d5e6f7a8b9c0d1",
  "noteTitle": "Al-Ajrumiyyah study notes"
}
POST/notes

Create a note

Auth required

Creates a note inside a folder owned by the authenticated user and adds the note reference to that folder. The caller becomes the note owner.

Body parameters

titlerequired
string
Note title.
folderIdrequired
string
ObjectId of the folder to create the note in. Must be owned by the caller.
sections
array
Initial sections, each an object `{ title: string, notes: string }` (both default to an empty string).Default: []

Errors

  • 400`title` or `folderId` is missing
  • 401No token provided
  • 403Invalid token, or the folder belongs to another user
  • 404No folder with the given ID exists
  • 500Unexpected server error (including a malformed folder ID)
Request
curl -X POST "https://app.ummahspot.com/notes" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"string","folderId":"string"}'
Response · 201
{
  "id": "66f1a2b3c4d5e6f7a8b9c0d1",
  "title": "Al-Ajrumiyyah study notes",
  "sections": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0e1",
      "title": "Chapter 1: Kalam",
      "notes": ""
    }
  ],
  "folderId": "66f19f00c4d5e6f7a8b9bf10",
  "createdAt": "2026-09-18T10:03:41.220Z",
  "lastModified": "2026-09-18T10:03:41.220Z"
}
PUT/notes/:noteId

Update a note

Auth required

Updates the note title and/or existing sections. Each entry in `sections` is matched to an existing section by `id`; only the `title` / `notes` fields present on that entry are changed. Entries whose `id` does not match an existing section are silently ignored, so this endpoint cannot add or remove sections (use the section endpoints). Sections not mentioned are left untouched. The response contains all sections of the note. The note must be owned by the authenticated user.

Path parameters

noteId
string
Note ObjectId

Body parameters

title
string
New note title.
sections
array
Partial section updates: objects `{ id: string, title?: string, notes?: string }` where `id` is an existing section ID.

Errors

  • 401No token provided
  • 403Invalid token, or the note belongs to another user
  • 404No note with the given ID exists
  • 500Unexpected server error (including a malformed note ID)
Request
curl -X PUT "https://app.ummahspot.com/notes/:noteId" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"string"}'
Response · 200
{
  "id": "66f1a2b3c4d5e6f7a8b9c0d1",
  "title": "Al-Ajrumiyyah study notes (revised)",
  "sections": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0e1",
      "title": "Chapter 1: Kalam",
      "notes": "[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Kalam is a composed, beneficial utterance.\",\"styles\":{}}]}]"
    }
  ],
  "folderId": "66f19f00c4d5e6f7a8b9bf10",
  "lastModified": "2026-09-18T10:12:09.874Z"
}
POST/notes/:noteId/sections

Add a section to a note

Auth required

Appends a new section to the end of the note and returns only the new section. The note must be owned by the authenticated user.

Path parameters

noteId
string
Note ObjectId

Body parameters

title
string
Section title.Default: ''
notes
string
Section body (the Sharh editor stores a BlockNote JSON string here).Default: ''

Errors

  • 401No token provided
  • 403Invalid token, or the note belongs to another user
  • 404No note with the given ID exists
  • 500Unexpected server error (including a malformed note ID)
Request
curl -X POST "https://app.ummahspot.com/notes/:noteId/sections" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"string"}'
Response · 201
{
  "id": "66f1a2b3c4d5e6f7a8b9c0e5",
  "title": "Chapter 2: I'rab",
  "notes": ""
}
PUT/notes/:noteId/sections/:sectionId

Update a section

Auth required

Updates the title and/or body of one section and returns the updated section. Only the fields provided are changed. The note must be owned by the authenticated user.

Path parameters

noteId
string
Note ObjectId
sectionId
string
Section ObjectId within the note

Body parameters

title
string
New section title.
notes
string
New section body (replaces the existing body).

Errors

  • 401No token provided
  • 403Invalid token, or the note belongs to another user
  • 404No note with the given ID exists, or no section with the given ID exists in the note
  • 500Unexpected server error (including a malformed note ID)
Request
curl -X PUT "https://app.ummahspot.com/notes/:noteId/sections/:sectionId" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"string"}'
Response · 200
{
  "id": "66f1a2b3c4d5e6f7a8b9c0e5",
  "title": "Chapter 2: I'rab",
  "notes": "[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"I'rab is the change at the end of words.\",\"styles\":{}}]}]"
}
DELETE/notes/:noteId/sections/:sectionId

Delete a section

Auth required

Removes the section from the note. The handler does not check that the section exists: a `sectionId` that is not in the note still returns the success message. The note must be owned by the authenticated user.

Path parameters

noteId
string
Note ObjectId
sectionId
string
Section ObjectId within the note

Errors

  • 401No token provided
  • 403Invalid token, or the note belongs to another user
  • 404No note with the given ID exists
  • 500Unexpected server error (including a malformed ID)
Request
curl -X DELETE "https://app.ummahspot.com/notes/:noteId/sections/:sectionId" \
  -H "Authorization: Bearer $SHARH_TOKEN"
Response · 200
{
  "message": "Section deleted successfully"
}
DELETE/notes/:noteId

Delete a note

Auth required

Permanently deletes the note and removes its reference from the parent folder. The note must be owned by the authenticated user.

Path parameters

noteId
string
Note ObjectId

Errors

  • 401No token provided
  • 403Invalid token, or the note belongs to another user
  • 404No note with the given ID exists
  • 500Unexpected server error (including a malformed note ID)
Request
curl -X DELETE "https://app.ummahspot.com/notes/:noteId" \
  -H "Authorization: Bearer $SHARH_TOKEN"
Response · 200
{
  "message": "Note deleted successfully"
}
POST/notes/import-book

Import a usul.ai book as a note

Auth required

Downloads the book content from `https://assets.usul.ai/book-content/{versionSource}/{versionValue}.json` and saves it as a new note in a folder owned by the authenticated user (the note reference is also added to the folder). Page text is split into sections at every `<span data-type="title">` heading (text before the first heading becomes an untitled section); pages without such headings become one section each, titled from the book's heading index or "Vol X, Page Y". HTML tags are stripped and every line becomes a right-aligned BlockNote paragraph with the Arabic text style. Other upstream layouts (a top-level array, `parts` / `chapters`, or a single `content` / `text` field) are handled similarly. The response contains every section of the created note and can be very large.

Body parameters

folderIdrequired
string
ObjectId of the folder to create the note in. Must be owned by the caller.
versionSourcerequired
string
Book version source as reported by usul.ai; used as the first path segment of the content URL.
versionValuerequired
string
Book version value as reported by usul.ai; used as the file name of the content URL.
bookTitle
string
Title for the created note.Default: Imported Book - {versionSource}/{versionValue}

Errors

  • 400`folderId`, `versionSource` or `versionValue` is missing
  • 401No token provided
  • 403Invalid token, or the folder belongs to another user
  • 404No folder with the given ID exists, or the book content could not be fetched from usul.ai
  • 500Unexpected server error (including a malformed folder ID)
Request
curl -X POST "https://app.ummahspot.com/notes/import-book" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folderId":"string","versionSource":"string","versionValue":"string"}'
Response · 201
{
  "id": "66f1b7d0c4d5e6f7a8b9c3a2",
  "title": "متن الآجرومية",
  "sections": [
    {
      "id": "66f1b7d0c4d5e6f7a8b9c3a3",
      "title": "باب الكلام",
      "notes": "[{\"type\":\"paragraph\",\"props\":{\"textAlignment\":\"right\"},\"content\":[{\"type\":\"text\",\"text\":\"الكلام هو اللفظ المركب المفيد بالوضع\",\"styles\":{\"arabicText\":true}}]}]"
    }
  ],
  "folderId": "66f19f00c4d5e6f7a8b9bf10",
  "createdAt": "2026-09-18T10:20:55.602Z",
  "lastModified": "2026-09-18T10:20:55.602Z"
}