Sharh

Ramadan Last 10 Nights Campaign

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

... / 150 members...
APIFlashcards

Flashcards

/cards

Individual flashcards (front / back) that belong to a flashcard collection and are scheduled with an SM-2 style spaced-repetition algorithm. Cards are private to their owner.

GETList cards in a collectionGETGet a cardPOSTCreate a cardPUTUpdate a cardPOSTRecord a review of a cardDELETEDelete a card
GET/cards/collection/:collectionId

List cards in a collection

Auth required

Returns every card in the collection, newest first (`createdAt` descending), including its spaced-repetition state. The collection must be owned by the authenticated user.

Path parameters

collectionId
string
CardCollection ObjectId

Errors

  • 401No token provided
  • 403Invalid token, or the collection belongs to another user
  • 404No collection with the given ID exists
  • 500Unexpected server error (including a malformed collection ID)
Request
curl -X GET "https://app.ummahspot.com/cards/collection/:collectionId" \
  -H "Authorization: Bearer $SHARH_TOKEN"
Response · 200
{
  "cards": [
    {
      "id": "66f2c1a4e0b1c2d3e4f5a6b7",
      "front": "What is the definition of kalam?",
      "back": "A composed, beneficial utterance by convention.",
      "easeFactor": 2.5,
      "interval": 0,
      "repetitions": 0,
      "nextReviewDate": "2026-09-18T10:30:02.117Z",
      "lastReviewDate": null,
      "tags": ["nahw"],
      "notes": "",
      "createdAt": "2026-09-18T10:30:02.117Z",
      "lastModified": "2026-09-18T10:30:02.120Z"
    }
  ]
}
GET/cards/:cardId

Get a card

Auth required

Returns a single card with its spaced-repetition state. The card must be owned by the authenticated user.

Path parameters

cardId
string
Card ObjectId

Errors

  • 401No token provided
  • 403Invalid token, or the card belongs to another user
  • 404No card with the given ID exists
  • 500Unexpected server error (including a malformed card ID)
Request
curl -X GET "https://app.ummahspot.com/cards/:cardId" \
  -H "Authorization: Bearer $SHARH_TOKEN"
Response · 200
{
  "id": "66f2c1a4e0b1c2d3e4f5a6b7",
  "front": "What is the definition of kalam?",
  "back": "A composed, beneficial utterance by convention.",
  "easeFactor": 2.5,
  "interval": 0,
  "repetitions": 0,
  "nextReviewDate": "2026-09-18T10:30:02.117Z",
  "lastReviewDate": null,
  "collectionId": "66f2c0ffe0b1c2d3e4f5a600",
  "tags": ["nahw"],
  "notes": "",
  "createdAt": "2026-09-18T10:30:02.117Z",
  "lastModified": "2026-09-18T10:30:02.120Z"
}
POST/cards

Create a card

Auth required

Creates a card in a collection owned by the authenticated user and adds the card reference to that collection. New cards start with `easeFactor` 2.5, `interval` 0, `repetitions` 0, `lastReviewDate` null and `nextReviewDate` set to the creation time, so they are immediately due.

Body parameters

frontrequired
string
Front (question) side of the card.
backrequired
string
Back (answer) side of the card.
collectionIdrequired
string
ObjectId of the collection to add the card to. Must be owned by the caller.
tags
string[]
Free-form tags.Default: []
notes
string
Extra notes stored with the card.Default: ''

Errors

  • 400`front`, `back` or `collectionId` is missing
  • 401No token provided
  • 403Invalid token, or the collection belongs to another user
  • 404No collection with the given ID exists
  • 500Unexpected server error (including a malformed collection ID)
Request
curl -X POST "https://app.ummahspot.com/cards" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"front":"string","back":"string","collectionId":"string"}'
Response · 201
{
  "id": "66f2c1a4e0b1c2d3e4f5a6b7",
  "front": "What is the definition of kalam?",
  "back": "A composed, beneficial utterance by convention.",
  "easeFactor": 2.5,
  "interval": 0,
  "repetitions": 0,
  "nextReviewDate": "2026-09-18T10:30:02.117Z",
  "lastReviewDate": null,
  "collectionId": "66f2c0ffe0b1c2d3e4f5a600",
  "tags": ["nahw"],
  "notes": "",
  "createdAt": "2026-09-18T10:30:02.117Z",
  "lastModified": "2026-09-18T10:30:02.120Z"
}
PUT/cards/:cardId

Update a card

Auth required

Updates the content of a card. Only the fields present in the body are changed; `tags` replaces the whole tag list. The spaced-repetition state is not affected and a card cannot be moved to another collection. The card must be owned by the authenticated user.

Path parameters

cardId
string
Card ObjectId

Body parameters

front
string
New front (question) side.
back
string
New back (answer) side.
tags
string[]
New tag list (replaces the existing one).
notes
string
New notes.

Errors

  • 401No token provided
  • 403Invalid token, or the card belongs to another user
  • 404No card with the given ID exists
  • 500Unexpected server error (including a malformed card ID or a validation failure such as an empty `front` / `back`)
Request
curl -X PUT "https://app.ummahspot.com/cards/:cardId" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"front":"string"}'
Response · 200
{
  "id": "66f2c1a4e0b1c2d3e4f5a6b7",
  "front": "Define kalam according to the grammarians",
  "back": "A composed, beneficial utterance by convention.",
  "easeFactor": 2.5,
  "interval": 0,
  "repetitions": 0,
  "nextReviewDate": "2026-09-18T10:30:02.117Z",
  "lastReviewDate": null,
  "collectionId": "66f2c0ffe0b1c2d3e4f5a600",
  "tags": ["nahw", "ajrumiyyah"],
  "notes": "",
  "lastModified": "2026-09-18T10:41:36.552Z"
}
POST/cards/:cardId/review

Record a review of a card

Auth required

Records a review and reschedules the card with an SM-2 style algorithm. Steps, in order: (1) `lastReviewDate` is set to now. (2) If `quality` is below 3 the card is reset: `repetitions` = 0 and `interval` = 1 day. Otherwise the new `interval` is 1 day when `repetitions` was 0, 6 days when it was 1, and `round(interval * easeFactor)` for later reviews (using the ease factor from before this review), and `repetitions` is incremented by 1. (3) The ease factor is then adjusted for every review, failed or not: `easeFactor = max(1.3, easeFactor + (0.1 - (5 - quality) * (0.08 + (5 - quality) * 0.02)))`. (4) `nextReviewDate` = now + `interval` days. The card must be owned by the authenticated user.

Path parameters

cardId
string
Card ObjectId

Body parameters

qualityrequired
number
Recall quality from 0 to 5 inclusive (0 = complete blackout, 5 = perfect response). Values below 3 count as a failed recall.

Errors

  • 400`quality` is missing, less than 0 or greater than 5
  • 401No token provided
  • 403Invalid token, or the card belongs to another user
  • 404No card with the given ID exists
  • 500Unexpected server error (including a malformed card ID)
Request
curl -X POST "https://app.ummahspot.com/cards/:cardId/review" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quality":0}'
Response · 200
{
  "id": "66f2c1a4e0b1c2d3e4f5a6b7",
  "easeFactor": 2.6,
  "interval": 1,
  "repetitions": 1,
  "nextReviewDate": "2026-09-19T10:45:10.308Z",
  "lastReviewDate": "2026-09-18T10:45:10.308Z",
  "message": "Review recorded successfully"
}
DELETE/cards/:cardId

Delete a card

Auth required

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

Path parameters

cardId
string
Card ObjectId

Errors

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