Ramadan Last 10 Nights Campaign

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

... / 150 members...

Translations Audio Quizzes Commentary

APIFlashcard Collections

Flashcard Collections

/card-collections

Flashcard decks. A collection groups cards, carries per-deck daily review settings, and exposes study queues (due cards, new cards) and statistics. Collections are private to their owner.

GET/card-collectionsList your collections GET/card-collections/:collectionIdGet a collection GET/card-collections/:collectionId/statsGet collection statistics GET/card-collections/:collectionId/dueList cards due for review GET/card-collections/:collectionId/newList new (never reviewed) cards POST/card-collectionsCreate a collection PUT/card-collections/:collectionIdUpdate a collection DELETE/card-collections/:collectionIdDelete a collection and its cards

GET/card-collections

List your collections

Auth required

Returns all collections owned by the authenticated user, sorted by `lastModified` descending. Cards themselves are not included, only a `cardCount`.

Errors

401No token provided
403Invalid token
500Unexpected server error

Request

curl -X GET "https://app.ummahspot.com/card-collections" \
  -H "Authorization: Bearer $SHARH_TOKEN"

Response · 200

{
  "collections": [
    {
      "id": "66f2c0ffe0b1c2d3e4f5a600",
      "name": "Ajrumiyyah definitions",
      "description": "Key terms from the matn",
      "cardCount": 42,
      "settings": {
        "cardsPerDay": 20,
        "newCardsPerDay": 10
      },
      "createdAt": "2026-08-15T12:00:00.000Z",
      "lastModified": "2026-09-18T10:30:02.130Z"
    }
  ]
}

GET/card-collections/:collectionId

Get a collection

Auth required

Returns one collection (without its cards). 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/card-collections/:collectionId" \
  -H "Authorization: Bearer $SHARH_TOKEN"

Response · 200

{
  "id": "66f2c0ffe0b1c2d3e4f5a600",
  "name": "Ajrumiyyah definitions",
  "description": "Key terms from the matn",
  "cardCount": 42,
  "settings": {
    "cardsPerDay": 20,
    "newCardsPerDay": 10
  },
  "createdAt": "2026-08-15T12:00:00.000Z",
  "lastModified": "2026-09-18T10:30:02.130Z"
}

GET/card-collections/:collectionId/stats

Get collection statistics

Auth required

Returns card counts for the collection: `total`; `due` (cards whose `nextReviewDate` is now or earlier — this includes never-reviewed cards, which are due from creation); `new` (`repetitions` = 0 and never reviewed); `learning` (`repetitions` 1 or 2); `mature` (`repetitions` 3 or more). 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/card-collections/:collectionId/stats" \
  -H "Authorization: Bearer $SHARH_TOKEN"

Response · 200

{
  "collectionId": "66f2c0ffe0b1c2d3e4f5a600",
  "collectionName": "Ajrumiyyah definitions",
  "stats": {
    "total": 42,
    "due": 12,
    "new": 8,
    "learning": 14,
    "mature": 19
  }
}

GET/card-collections/:collectionId/due

List cards due for review

Auth required

Returns the cards in the collection whose `nextReviewDate` is now or earlier, most overdue first (`nextReviewDate` ascending). Never-reviewed cards are included because their `nextReviewDate` is their creation time. The number of cards is capped by `limit`, which defaults to the collection's `settings.cardsPerDay`. The cap is not tracked per day: it only limits the size of this response. A `limit` of 0 removes the cap. The collection must be owned by the authenticated user.

Path parameters

collectionId

string

CardCollection ObjectId

Query parameters

limit

number

Maximum number of cards to return; parsed with parseInt. 0 returns all due cards.Default: settings.cardsPerDay (20 unless changed)

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/card-collections/:collectionId/due" \
  -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.6,
      "interval": 6,
      "repetitions": 2,
      "nextReviewDate": "2026-09-17T08:12:44.000Z",
      "lastReviewDate": "2026-09-11T08:12:44.000Z",
      "tags": ["nahw"],
      "notes": ""
    }
  ],
  "count": 1
}

GET/card-collections/:collectionId/new

List new (never reviewed) cards

Auth required

Returns cards in the collection that have never been reviewed (`repetitions` = 0 and `lastReviewDate` null), oldest first (`createdAt` ascending). The number of cards is capped by `limit`, which defaults to the collection's `settings.newCardsPerDay`. The cap is not tracked per day: it only limits the size of this response. A `limit` of 0 removes the cap. The collection must be owned by the authenticated user.

Path parameters

collectionId

string

CardCollection ObjectId

Query parameters

limit

number

Maximum number of cards to return; parsed with parseInt. 0 returns all new cards.Default: settings.newCardsPerDay (10 unless changed)

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/card-collections/:collectionId/new" \
  -H "Authorization: Bearer $SHARH_TOKEN"

Response · 200

{
  "cards": [
    {
      "id": "66f2c1a4e0b1c2d3e4f5a6b7",
      "front": "What is the definition of kalam?",
      "back": "A composed, beneficial utterance by convention.",
      "tags": ["nahw"],
      "notes": "",
      "createdAt": "2026-09-18T10:30:02.117Z"
    }
  ],
  "count": 1
}

POST/card-collections

Create a collection

Auth required

Creates an empty collection owned by the authenticated user. Settings that are not supplied take their defaults.

Body parameters

`name`required string	Collection name.
`description` string	Collection description.Default: `''`
`settings` object	Study settings: `cardsPerDay` (number, default page size of the due queue) and `newCardsPerDay` (number, default page size of the new-card queue).Default: `{ cardsPerDay: 20, newCardsPerDay: 10 }`

Errors

400`name` is missing
401No token provided
403Invalid token
500Unexpected server error

Request

curl -X POST "https://app.ummahspot.com/card-collections" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"string"}'

Response · 201

{
  "id": "66f2c0ffe0b1c2d3e4f5a600",
  "name": "Ajrumiyyah definitions",
  "description": "Key terms from the matn",
  "cardCount": 0,
  "settings": {
    "cardsPerDay": 20,
    "newCardsPerDay": 10
  },
  "createdAt": "2026-09-18T10:28:40.019Z",
  "lastModified": "2026-09-18T10:28:40.019Z"
}

PUT/card-collections/:collectionId

Update a collection

Auth required

Updates the name, description and/or settings of a collection. Only the fields present in the body are changed; `settings` is shallow-merged into the existing settings, so a single setting can be sent on its own. The collection must be owned by the authenticated user.

Path parameters

collectionId

string

CardCollection ObjectId

Body parameters

`name` string	New collection name.
`description` string	New collection description.
`settings` object	Settings to merge: `cardsPerDay` (number) and/or `newCardsPerDay` (number).

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 or a validation failure such as an empty `name`)

Request

curl -X PUT "https://app.ummahspot.com/card-collections/:collectionId" \
  -H "Authorization: Bearer $SHARH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"string"}'

Response · 200

{
  "id": "66f2c0ffe0b1c2d3e4f5a600",
  "name": "Ajrumiyyah definitions",
  "description": "Key terms from the matn",
  "cardCount": 42,
  "settings": {
    "cardsPerDay": 30,
    "newCardsPerDay": 10
  },
  "lastModified": "2026-09-18T10:50:21.774Z"
}

DELETE/card-collections/:collectionId

Delete a collection and its cards

Auth required

Permanently deletes the collection together with every card in it. 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 DELETE "https://app.ummahspot.com/card-collections/:collectionId" \
  -H "Authorization: Bearer $SHARH_TOKEN"

Response · 200

{
  "message": "Collection and all associated cards deleted successfully"
}