Flashcards API

Generate Flashcards

Generate a flashcard deck from study content using AI. Supports text input and file uploads.

Authentication is optional. Authenticated users can save decks and track study progress with spaced repetition.

POST /api/flashcards/generate

curl -X POST https://api.inspir.uk/api/flashcards/generate \
  -H "Content-Type: multipart/form-data" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "content=Photosynthesis is the process..." \
  -F "deckName=Biology Chapter 5" \
  -F "sourceName=Textbook" \
  -F "cardCount=15"

Request Parameters

content

string

required

Text content to generate flashcards from. Can be provided directly or via file upload.

file

Optional file upload (PDF, DOCX, TXT). Maximum 10MB. File content takes precedence over text content.

deckName

string

Name for the flashcard deck. If not provided, AI will suggest a name based on content.

sourceName

string

Source of the content (e.g., “Chapter 5”, “Lecture Notes”)

cardCount

number

Number of flashcards to generate. Min: 5, Max: 50, Default: 10

Response

success

boolean

Whether the operation was successful

deck

object

The generated flashcard deck

Show Deck Object

string

Unique deck identifier (null for unauthenticated users)

deckName

string

Name of the deck

sourceName

string

Source name

cards

array

Array of flashcards

Show Card Object

string

Unique card identifier (UUID)

front

string

Question or prompt text

back

string

Answer text (2-4 sentences)

explanation

string

Optional context, mnemonic, or additional info

cardCount

number

Total number of cards in the deck

Error Responses

Show 400 Bad Request

{
  "error": "Content is required"
}

{
  "error": "Failed to process file",
  "details": "File format not supported"
}

{
  "error": "Invalid file type. Only PDF, DOCX, and TXT files are allowed."
}

Show 500 Internal Server Error

{
  "error": "Failed to generate flashcards",
  "details": "The AI returned an invalid format"
}

Get User Decks

Retrieve all flashcard decks for the authenticated user with study progress statistics.

This endpoint requires authentication.

GET /api/flashcards/decks

curl -X GET https://api.inspir.uk/api/flashcards/decks \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

success

boolean

Whether the operation was successful

decks

array

Array of flashcard decks with progress statistics

Show Deck Object

string

Deck ID

deck_name

string

Deck name

source_name

string

Source name

description

string

Deck description

card_count

number

Total number of cards

created_at

string

ISO 8601 timestamp

stats

object

Mastery statistics

Show Stats Object

mastered

number

Number of mastered cards

learning

number

Number of cards in learning phase

new

number

Number of cards not yet studied

averageEaseFactor

number

Average ease factor across all cards

dueCount

number

Number of cards due for review

newCount

number

Number of cards not yet studied

Get Deck by ID

Retrieve a specific flashcard deck with full card details.

GET /api/flashcards/deck/:id

curl -X GET https://api.inspir.uk/api/flashcards/deck/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

string

required

The unique identifier of the deck

Response

success

boolean

Whether the operation was successful

deck

object

Complete deck object including all cards

progress

array

Study progress for each card (only for authenticated users)

Show Progress Object

card_id

string

Card ID

mastery_level

number

Current mastery level (0-5)

ease_factor

number

Ease factor for spaced repetition algorithm

interval_days

number

Days until next review

review_count

number

Total number of reviews

correct_count

number

Number of correct answers

last_reviewed_at

string

ISO 8601 timestamp of last review

next_review_at

string

ISO 8601 timestamp of next scheduled review

stats

object

Mastery statistics (only for authenticated users)

Error Responses

Show 403 Forbidden

{
  "error": "Access denied"
}

Returned when trying to access another user’s private deck.

Show 404 Not Found

{
  "error": "Deck not found"
}

Get Study Session

Get cards to study in a session using spaced repetition algorithm.

This endpoint requires authentication.

GET /api/flashcards/deck/:id/study

curl -X GET "https://api.inspir.uk/api/flashcards/deck/123e4567-e89b-12d3-a456-426614174000/study?mode=flip&maxCards=25" \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

string

required

The unique identifier of the deck

Query Parameters

mode

string

Study mode. Options: flip (default), quiz, match

maxCards

number

Maximum number of cards in the session. Default: 25

Response

success

boolean

Whether the operation was successful

session

object

Study session details

Show Session Object

deckId

string

Deck ID

deckName

string

Deck name

mode

string

Study mode

cards

array

Cards to study (shuffled), each with progress info and isNew flag

totalCards

number

Total cards in this session

dueCards

number

Number of due cards in session

newCards

number

Number of new cards in session

stats

object

Current mastery statistics

recommendation

object

Study session recommendations based on progress

Record Study Progress

Record the results of a study session using the SM-2 spaced repetition algorithm.

This endpoint requires authentication.

POST /api/flashcards/deck/:id/progress

curl -X POST https://api.inspir.uk/api/flashcards/deck/123e4567-e89b-12d3-a456-426614174000/progress \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "results": [
      {
        "cardId": "card-uuid-1",
        "quality": 4,
        "correct": true
      },
      {
        "cardId": "card-uuid-2",
        "quality": 2,
        "correct": false
      }
    ],
    "mode": "flip",
    "durationSeconds": 300
  }'

Path Parameters

string

required

The unique identifier of the deck

Request Parameters

results

array

required

Array of card results from the study session

Show Result Object

cardId

string

required

Card ID

quality

number

required

Quality of recall (0-5):

0: Complete blackout
1: Incorrect, but familiar
2: Incorrect, but close
3: Correct with difficulty
4: Correct with hesitation
5: Perfect recall

correct

boolean

required

Whether the answer was correct

mode

string

Study mode used

durationSeconds

number

Duration of the study session in seconds

Response

success

boolean

Whether the operation was successful

updates

array

Array of updated progress for each card with new review intervals

stats

object

Updated mastery statistics

summary

object

Session summary

Show Summary Object

cardsStudied

number

Total cards studied

cardsCorrect

number

Number of correct answers

accuracy

number

Accuracy percentage (0-100)

Generate a shareable link for a flashcard deck.

This endpoint requires authentication. You can only share your own decks.

POST /api/flashcards/deck/:id/share

curl -X POST https://api.inspir.uk/api/flashcards/deck/123e4567-e89b-12d3-a456-426614174000/share \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

string

required

The unique identifier of the deck to share

Response

success

boolean

Whether the operation was successful

Complete shareable URL

Unique share token

Get Shared Deck

Retrieve a publicly shared flashcard deck using its share token.

GET /api/flashcards/shared/:token

curl -X GET https://api.inspir.uk/api/flashcards/shared/abc123def456

Path Parameters

token

string

required

The share token for the deck

Response

success

boolean

Whether the operation was successful

deck

object

Complete deck object with all cards

Error Responses

Show 404 Not Found

{
  "error": "Deck not found or not shared"
}

Delete Deck

Delete a flashcard deck and all associated progress.

This endpoint requires authentication. You can only delete your own decks. This action cannot be undone.

DELETE /api/flashcards/deck/:id

curl -X DELETE https://api.inspir.uk/api/flashcards/deck/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

string

required

The unique identifier of the deck

Response

{
  "success": true,
  "message": "Deck deleted successfully"
}

Spaced Repetition Algorithm

The flashcards feature uses the SM-2 (SuperMemo 2) spaced repetition algorithm to optimize learning:

Quality Ratings (0-5): After each review, rate how well you recalled the answer
Ease Factor: Adjusts based on performance (easier cards have longer intervals)
Intervals: Time between reviews increases exponentially for well-known cards
Mastery Levels: Cards progress through learning stages as you review them correctly

This ensures you review cards at optimal intervals for long-term retention.

Overview

Endpoints

Flashcards API

Generate Flashcards

Request Parameters

Response

Error Responses

Get User Decks

Response

Get Deck by ID

Path Parameters

Response

Error Responses

Get Study Session

Path Parameters

Query Parameters

Response

Record Study Progress

Path Parameters

Request Parameters

Response

Path Parameters

Response

Get Shared Deck

Path Parameters

Response

Error Responses

Delete Deck

Path Parameters

Response

Spaced Repetition Algorithm

Build docs developers (and LLMs) love

Overview

Endpoints

​Generate Flashcards

​Request Parameters

​Response

​Error Responses

​Get User Decks

​Response

​Get Deck by ID

​Path Parameters

​Response

​Error Responses

​Get Study Session

​Path Parameters

​Query Parameters

​Response

​Record Study Progress

​Path Parameters

​Request Parameters

​Response

​Share Deck

​Path Parameters

​Response

​Get Shared Deck

​Path Parameters

​Response

​Error Responses

​Delete Deck

​Path Parameters

​Response

​Spaced Repetition Algorithm

Build docs developers (and LLMs) love

Generate Flashcards

Request Parameters

Response

Error Responses

Get User Decks

Response

Get Deck by ID

Path Parameters

Response

Error Responses

Get Study Session

Path Parameters

Query Parameters

Response

Record Study Progress

Path Parameters

Request Parameters

Response

Share Deck

Path Parameters

Response

Get Shared Deck

Path Parameters

Response

Error Responses

Delete Deck

Path Parameters

Response

Spaced Repetition Algorithm