Sharh

Ramadan Last 10 Nights Campaign

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

... / 150 members...
APIFolders

Folders

/folders

Folders organise a user's notes. Every note belongs to exactly one folder, and folders are private to their owner.

GETList your foldersGETGet a folderPOSTCreate a folderPUTUpdate a folderDELETEDelete a folder and its notes
GET/folders

List your folders

Auth required

Returns all folders owned by the authenticated user, sorted by `lastModified` descending. Each folder includes a summary (`id`, `title`, `lastModified`) of the notes it contains.

Errors

  • 401No token provided
  • 403Invalid token
  • 500Unexpected server error
Request
curl -X GET "https://app.ummahspot.com/folders" \
  -H "Authorization: Bearer $SHARH_TOKEN"
Response · 200
{
  "folders": [
    {
      "id": "66f19f00c4d5e6f7a8b9bf10",
      "name": "Nahw",
      "description": "Arabic grammar notes",
      "noteCount": 1,
      "notes": [
        {
          "id": "66f1a2b3c4d5e6f7a8b9c0d1",
          "title": "Al-Ajrumiyyah study notes",
          "lastModified": "2026-09-10T18:42:07.113Z"
        }
      ],
      "createdAt": "2026-08-01T07:30:00.000Z",
      "lastModified": "2026-09-10T18:40:51.006Z"
    }
  ]
}
GET/folders/:folderId

Get a folder

Auth required

Returns one folder with a summary of its notes. 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/folders/:folderId" \
  -H "Authorization: Bearer $SHARH_TOKEN"
Response · 200
{
  "id": "66f19f00c4d5e6f7a8b9bf10",
  "name": "Nahw",
  "description": "Arabic grammar notes",
  "notes": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0d1",
      "title": "Al-Ajrumiyyah study notes",
      "lastModified": "2026-09-10T18:42:07.113Z"
    }
  ],
  "createdAt": "2026-08-01T07:30:00.000Z",
  "lastModified": "2026-09-10T18:40:51.006Z"
}
POST/folders

Create a folder

Auth required

Creates an empty folder owned by the authenticated user.

Body parameters

namerequired
string
Folder name.
description
string
Folder description.Default: ''

Errors

  • 400`name` is missing
  • 401No token provided
  • 403Invalid token
  • 500Unexpected server error
Request
curl -X POST "https://app.ummahspot.com/folders" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"string"}'
Response · 201
{
  "id": "66f19f00c4d5e6f7a8b9bf10",
  "name": "Nahw",
  "description": "Arabic grammar notes",
  "notes": [],
  "createdAt": "2026-09-18T10:00:12.345Z",
  "lastModified": "2026-09-18T10:00:12.345Z"
}
PUT/folders/:folderId

Update a folder

Auth required

Renames a folder and/or changes its description. `name` is only applied when it is a non-empty value; `description` is applied whenever it is present (an empty string clears it). The folder must be owned by the authenticated user.

Path parameters

folderId
string
Folder ObjectId

Body parameters

name
string
New folder name. Ignored when empty.
description
string
New folder description.

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 PUT "https://app.ummahspot.com/folders/:folderId" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"string"}'
Response · 200
{
  "id": "66f19f00c4d5e6f7a8b9bf10",
  "name": "Nahw & Sarf",
  "description": "Arabic grammar and morphology notes",
  "lastModified": "2026-09-18T10:05:47.911Z"
}
DELETE/folders/:folderId

Delete a folder and its notes

Auth required

Permanently deletes the folder together with every note stored in it. 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 DELETE "https://app.ummahspot.com/folders/:folderId" \
  -H "Authorization: Bearer $SHARH_TOKEN"
Response · 200
{
  "message": "Folder and all its notes deleted successfully"
}