Skip to main content
POST
/
api
/
generate-unified
Generate Study Guide
curl --request POST \
  --url https://api.example.com/api/generate-unified \
  --header 'Content-Type: application/json' \
  --data '
{
  "content": "<string>",
  "outputType": "<string>",
  "userId": "<string>",
  "customName": "<string>",
  "numQuestions": 123,
  "includeMultipleAnswer": true,
  "includeTrueFalse": true,
  "depthOfKnowledge": "<string>",
  "numFlashcards": 123,
  "numWritingPrompts": 123,
  "notesLength": "<string>"
}
'
{
  "success": true,
  "itemId": "<string>",
  "title": "<string>"
}

​
Endpoint

POST /api/generate-unified
The unified generation endpoint that creates various types of study materials with advanced customization options. Supports file uploads (PDF, DOCX, TXT), authentication, and database storage.
This endpoint requires authentication. The user must be logged in via Supabase authentication.

​
Request Body

​
content
string
required
The source content for generation. Can be:
  • Plain text content
  • A blob URL (starts with blob:) for uploaded files (PDF, DOCX, TXT)
For plain text, up to 6000 characters will be used.
​
outputType
string
required
The type of study material to generate. Must be one of:
  • quiz - Multiple-choice quiz questions
  • flashcards - Flashcard pairs
  • writing-prompt - Writing prompts with guidance
  • notes - Comprehensive study notes
​
userId
string
User ID for database storage. If not provided, uses authenticated user ID.
​
customName
string
Custom title for the generated material. If not provided, uses AI-generated title.

​
Quiz-Specific Parameters

​
numQuestions
number
default:"10"
Number of quiz questions to generate (quiz only).
​
includeMultipleAnswer
boolean
default:"true"
Include multiple-answer questions where multiple options can be correct (quiz only).
​
includeTrueFalse
boolean
default:"true"
Include true/false questions (quiz only).
​
depthOfKnowledge
string
default:"intermediate"
Difficulty level for quiz questions. Options:
  • beginner - Easy recall and recognition questions
  • intermediate - Application and understanding questions
  • advanced or expert - Analysis and critical thinking questions

​
Flashcard-Specific Parameters

​
numFlashcards
number
default:"15"
Number of flashcards to generate (flashcards only).

​
Writing Prompt-Specific Parameters

​
numWritingPrompts
number
default:"3"
Number of writing prompts to generate (writing-prompt only).

​
Notes-Specific Parameters

​
notesLength
string
default:"medium"
Length/detail level of notes. Options:
  • short - 5 sections
  • medium - 8 sections
  • long - 12 sections

​
Response

​
success
boolean
Whether the generation was successful.
​
itemId
string
Database ID of the created study item.
​
title
string
The title of the generated study material.

​
Example Request - Quiz

curl -X POST https://yourdomain.com/api/generate-unified \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "content": "The mitochondria is the powerhouse of the cell. It generates ATP through cellular respiration...",
    "outputType": "quiz",
    "customName": "Cell Biology Quiz",
    "numQuestions": 10,
    "depthOfKnowledge": "intermediate",
    "includeMultipleAnswer": true,
    "includeTrueFalse": true
  }'

​
Example Response - Quiz

{
  "success": true,
  "itemId": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Cell Biology Quiz"
}

​
Example Request - Flashcards

curl -X POST https://yourdomain.com/api/generate-unified \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "content": "Common Spanish verbs: hablar (to speak), comer (to eat), vivir (to live)...",
    "outputType": "flashcards",
    "numFlashcards": 15
  }'

​
Example Request - Notes

curl -X POST https://yourdomain.com/api/generate-unified \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "content": "The American Revolution was a colonial revolt that took place between 1765 and 1783...",
    "outputType": "notes",
    "notesLength": "long",
    "customName": "American Revolution Study Notes"
  }'

​
Example Request - File Upload

curl -X POST https://yourdomain.com/api/generate-unified \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "content": "blob:https://yourdomain.com/abc-123",
    "outputType": "quiz",
    "numQuestions": 15
  }'

​
Error Responses

​
401 Unauthorized

{
  "error": "Not authenticated"
}
Returned when the user is not authenticated.

​
400 Bad Request

{
  "error": "Content and output type are required"
}
Returned when required fields are missing. 
{
  "error": "Invalid output type"
}
Returned when outputType is not one of the valid options.

​
500 Internal Server Error

{
  "error": "API key not configured"
}
Returned when the Groq API key is not set. 
{
  "error": "Groq API error: [error details]"
}
Returned when the Groq API request fails. 
{
  "error": "Failed to parse generated content: [details]. The AI generated invalid JSON."
}
Returned when the AI response cannot be parsed as valid JSON. 
{
  "error": "No valid questions generated"
}
Returned when quiz generation produces no valid questions. 
{
  "error": "No valid flashcards generated"
}
Returned when flashcard generation produces no valid cards. 
{
  "error": "Failed to save to database: [error details]"
}
Returned when database insertion fails. 
{
  "error": "The uploaded file appears to be empty or unreadable. Please check the file and try again."
}
Returned when an uploaded file cannot be read or is empty.

​
File Upload Support

The endpoint supports parsing uploaded files:
  • PDF files: Parsed using pdf-parse
  • DOCX files: Parsed using officeparser
  • TXT files: Read as plain text
When a blob URL is provided, the endpoint:
  1. Fetches the file content
  2. Detects the file type from content-type or URL extension
  3. Parses the file appropriately
  4. Cleans up excessive whitespace
  5. Uses the extracted text for generation

​
Content Filtering

The endpoint includes critical instructions to prevent questions about file metadata:
  • Questions/cards about file names, authors, dates, or formats are filtered out
  • Only subject matter content is used for generation
  • This ensures high-quality, relevant study materials

​
Implementation Details

  • Uses Groq’s llama-3.1-8b-instant model
  • Temperature set to 0.5 for consistent output
  • Maximum 4096 tokens per response
  • Content truncated to first 6000 characters (vs. 500-1000 for simpler endpoints)
  • Results saved to study_items table in Supabase
  • Database type: quiz, flashcards, writing, or notes
  • Content stored as JSON string (except notes which store markdown directly)

​
Database Schema

Generated items are saved with:
  • user_id - The authenticated user’s ID
  • type - One of: quiz, flashcards, writing, notes
  • title - Custom name or AI-generated title
  • content - JSON string or markdown text

​
Quiz Response Format (Internal)

The actual quiz data stored in the database: 
{
  "questions": [
    {
      "question": "What is the powerhouse of the cell?",
      "type": "multiple-choice",
      "options": ["Mitochondria", "Nucleus", "Ribosome", "Chloroplast"],
      "correctAnswer": 0,
      "explanation": "The mitochondria generates ATP through cellular respiration."
    }
  ],
  "topic": "Cell Biology Quiz"
}

​
Flashcards Response Format (Internal)

{
  "flashcards": [
    {
      "front": "What is hablar in English?",
      "back": "to speak"
    }
  ],
  "topic": "Spanish Verbs"
}

​
Writing Prompts Response Format (Internal)

{
  "prompts": [
    {
      "prompt": "Analyze the causes of the American Revolution",
      "guidance": "Consider economic, political, and social factors"
    }
  ],
  "topic": "American Revolution"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us