Skip to main content

Overview

The Library API enables users to manage their study materials including quizzes, flashcards, study guides, and writing prompts. All library items are user-scoped and support organization via folders.

Authentication

All library endpoints require authentication. Users can only access and manage their own library items.
Library items are automatically associated with the authenticated user. Attempting to access another user’s items will return a 404 error.

Save to Library

/api/library/save
Saves a new study item to the user’s library.

Request Body

title
string
required
Title of the study item
topic
string
required
The subject or topic of the study material
itemType
string
required
Type of study material. Must be one of:
  • quiz
  • flashcard
  • study_guide
  • writing_prompt
content
object
required
The study material content (structure varies by item type)
folderId
string
Optional UUID of the folder to save this item in

Example Request - Quiz

{
  "title": "World War II Quiz",
  "topic": "History",
  "itemType": "quiz",
  "content": {
    "questions": [
      {
        "question": "In what year did World War II begin?",
        "options": ["1937", "1939", "1941", "1945"],
        "correctAnswer": 1,
        "explanation": "World War II began in 1939 with Germany's invasion of Poland."
      }
    ]
  },
  "folderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Example Request - Flashcards

{
  "title": "Spanish Vocabulary",
  "topic": "Languages",
  "itemType": "flashcard",
  "content": {
    "cards": [
      {
        "front": "Hello",
        "back": "Hola"
      },
      {
        "front": "Goodbye",
        "back": "Adiós"
      }
    ]
  }
}

Response

success
boolean
required
Indicates whether the save operation was successful
item
object
required
The created library item

Example Response

{
  "success": true,
  "item": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "folder_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "item_type": "quiz",
    "title": "World War II Quiz",
    "topic": "History",
    "content": {
      "questions": [
        {
          "question": "In what year did World War II begin?",
          "options": ["1937", "1939", "1941", "1945"],
          "correctAnswer": 1,
          "explanation": "World War II began in 1939 with Germany's invasion of Poland."
        }
      ]
    },
    "created_at": "2026-03-07T10:30:00.000Z",
    "updated_at": "2026-03-07T10:30:00.000Z"
  }
}

Error Responses

401 Unauthorized
{
  "error": "Unauthorized"
}
500 Internal Server Error
{
  "error": "Failed to save"
}

Get Library Items

/api/dashboard/library
Retrieves all library items for the authenticated user, including study items with their scores and favorite status.

Response

items
array
required
Array of library items

Example Response

{
  "items": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "title": "World War II Quiz",
      "type": "quiz",
      "created_at": "2026-03-07T10:30:00.000Z",
      "is_favorite": true,
      "score": 85
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Spanish Vocabulary",
      "type": "flashcard",
      "created_at": "2026-03-06T14:20:00.000Z",
      "is_favorite": false,
      "score": 92
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "title": "Biology Study Guide",
      "type": "study_guide",
      "created_at": "2026-03-05T09:15:00.000Z",
      "is_favorite": false,
      "score": null
    }
  ]
}

Error Responses

401 Unauthorized
{
  "error": "Not authenticated"
}
500 Internal Server Error
{
  "error": "Internal server error"
}

Delete Library Item

/api/dashboard/library/[itemId]
Deletes a specific library item. Users can only delete their own items.

Path Parameters

itemId
string
required
UUID of the library item to delete

Response

success
boolean
required
Indicates whether the deletion was successful

Example Request

DELETE /api/dashboard/library/f47ac10b-58cc-4372-a567-0e02b2c3d479

Example Response

{
  "success": true
}

Error Responses

401 Unauthorized
{
  "error": "Not authenticated"
}
500 Internal Server Error
{
  "error": "Failed to delete item"
}

Get Study Item

/api/study-items/[id]
Retrieves a specific study item by ID with full content details.

Path Parameters

id
string
required
UUID of the study item

Response

Returns the complete study item object including all content.

Example Response

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "World War II Quiz",
  "type": "quiz",
  "content": {
    "questions": [
      {
        "question": "In what year did World War II begin?",
        "options": ["1937", "1939", "1941", "1945"],
        "correctAnswer": 1
      }
    ]
  },
  "created_at": "2026-03-07T10:30:00.000Z",
  "is_favorite": true
}

Error Responses

401 Unauthorized
{
  "error": "Not authenticated"
}
404 Not Found
{
  "error": "Item not found"
}

Update Study Item Title

/api/study-items/[id]
Updates the title of a study item. Only the title field can be updated.

Path Parameters

id
string
required
UUID of the study item to update

Request Body

title
string
required
New title for the study item (must not be empty)

Example Request

{
  "title": "WWII Quiz - Updated"
}

Response

Returns the updated study item object.

Example Response

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "WWII Quiz - Updated",
  "type": "quiz",
  "created_at": "2026-03-07T10:30:00.000Z"
}

Error Responses

400 Bad Request
{
  "error": "Valid title is required"
}
401 Unauthorized
{
  "error": "Not authenticated"
}
500 Internal Server Error
{
  "error": "Failed to update item"
}

Item Type Schemas

Quiz Content Structure

{
  questions: [
    {
      question: string,
      options: string[],
      correctAnswer: number, // index of correct option
      explanation?: string
    }
  ]
}

Flashcard Content Structure

{
  cards: [
    {
      front: string,
      back: string
    }
  ]
}

Study Guide Content Structure

{
  sections: [
    {
      heading: string,
      content: string
    }
  ]
}

Writing Prompt Content Structure

{
  prompt: string,
  guidelines?: string[],
  wordCount?: number
}

Build docs developers (and LLMs) love