Back to QuizStop

QuizStop API

AI-Powered Question Creation API

v1.0 Try Live Demo

QuizStop API Documentation

Welcome to the QuizStop API - the powerful AI-driven question creation platform designed specifically for AI agents, custom GPTs, and educational integrations.

AI-Powered Assessment

Advanced AI evaluates student responses through voice, drawing, or text input with intelligent feedback.

50+ Languages

Native multilingual support with high-quality TTS voices and speech recognition.

Rich Media Support

Create questions with images, audio, and multiple interaction modes for engaging learning.

Secure & Scalable

Enterprise-grade security with API key authentication and rate limiting.

Perfect for AI Agents

This API is specifically designed for OpenAI Custom GPTs, Claude Projects, and other AI agents that need to create educational content programmatically. The intuitive JSON interface and comprehensive documentation make integration seamless.

Key Features

Complete quiz management: Create, retrieve, and organize quizzes
Create questions with images, audio, and multiple answer modes
Support for base64 encoded files and multipart form uploads
12 predefined educational categories for organized content
1000+ AI voices across 50+ languages and dialects
Flexible answer modes: Voice, Multiple Choice, Drawing, Text

Authentication

The QuizStop API supports two authentication methods for maximum compatibility with different AI platforms and integration tools.

1. Bearer Token Authentication

Authorization: Bearer qz_abc123def456ghi789jkl012mno345pq

Recommended for OpenAI Custom GPTs and direct API calls

2. Basic Authentication

Authorization: Basic <base64-encoded-api-key>

Alternative method for systems requiring Basic auth format

Getting Your API Key

  1. 1. Open the QuizStop mobile/web application
  2. 2. Navigate to Account → API Keys
  3. 3. Click "Create API Key" and provide a name
  4. 4. Copy the generated key securely
  5. 5. API keys follow the format: qz_[32 random characters]

Get Quizzes

Retrieve all quizzes for the authenticated user

GET /get-quizzes

Request

This endpoint requires only authentication headers. No request body needed.

GET https://api.quizstop.ai/get-quizzes
Authorization: Bearer qz_your_api_key_here
Content-Type: application/json

Response

Returns all quizzes with their ID and name:

{
  "success": 1,
  "message": "Quizzes retrieved successfully",
  "data": {
    "quizzes": [
      {
        "bid": 123,
        "name": "Math Fundamentals"
      },
      {
        "bid": 124,
        "name": "Science Basics"
      }
    ],
    "total_count": 2
  },
  "user": {
    "email": "[email protected]",
    "name": "John Doe",
    "type": "pro"
  },
  "timestamp": "2023-12-03T12:00:00.000Z"
}

Create Quiz

Create a new quiz container for organizing questions

POST /create-quiz

Request Parameters

Parameter Type Required Description
name string Required Name of the quiz (1-100 characters)

Request Example

{
  "name": "Advanced Mathematics"
}

Response Example

{
  "success": 1,
  "message": "Quiz created successfully",
  "data": {
    "bid": 125,
    "name": "Advanced Mathematics"
  },
  "user": {
    "email": "[email protected]",
    "name": "John Doe",
    "type": "pro"
  },
  "timestamp": "2023-12-03T12:00:00.000Z"
}

Usage Notes

  • Quiz names must be unique within your account
  • The returned bid is used when creating questions with the Create Question endpoint
  • New quizzes start with 0 questions - use the Create Question endpoint to add content
  • Questions can be organized using the predefined categories (1-12)

Create Question

Create interactive questions with rich media content

POST /create-question

Question Categories

Each question must be assigned to one of these predefined categories for educational organization:

1: Motor Skills
2: Social-Emotional
3: Vocabulary
4: Shapes & Colors
5: Practical Life Skills
6: Arts & Music
7: Spatial Awareness
8: Letters / Phonemic
9: Numbers & Math
10: Science & Nature Exploration
11: Problem-Solving & Logic
12: Other

Request Format

The API accepts requests in two formats:

JSON Format

For base64-encoded files and simple integrations

Content-Type: application/json
Form Data

For binary file uploads and larger media

Content-Type: multipart/form-data

JSON Request Example

{
  "question_text": "What color is the sky?",
  "question_type": "multiple_choice",
  "category_id": 10,
  "bookId": 123,
  "voice": "en-US-Standard-C",
  "answer_modes": ["voice", "pick_choices"],
  "answers": [
    {
      "text": "Blue",
      "is_correct": true,
      "image_file": "data:image/png;base64,iVBORw0KGgo..."
    },
    {
      "text": "Red",
      "is_correct": false
    }
  ],
  "is_open_ended": false,
  "wait_time_seconds": 30,
  "reward_credits": 2,
  "image_file": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
  "evaluation_mode": "simple"
}

Multipart/Form-Data Request Example

For binary file uploads, use multipart/form-data instead of JSON:

POST /create-question
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary

------WebKitFormBoundary
Content-Disposition: form-data; name="question_text"

What color is the sky?
------WebKitFormBoundary
Content-Disposition: form-data; name="bookId"

123
------WebKitFormBoundary
Content-Disposition: form-data; name="category_id"

10
------WebKitFormBoundary
Content-Disposition: form-data; name="answers"

[{"text": "Blue", "is_correct": true}, {"text": "Red", "is_correct": false}]
------WebKitFormBoundary
Content-Disposition: form-data; name="main_image"; filename="question.jpg"
Content-Type: image/jpeg

[Binary image data...]
------WebKitFormBoundary--

File Format Support: Both base64-encoded strings (JSON) and binary files (multipart) are supported for image_file, audio_file, and main_image parameters.

Parameters

Parameter Type Required Description
question_text string Yes The main question text to be presented to learners
bookId number Yes ID of the quiz to add this question to (use Create Quiz endpoint first)
category_id number Yes Category ID (1=Motor Skills, 2=Social-Emotional, 3=Vocabulary, 4=Shapes & Colors, 5=Practical Life Skills, 6=Arts & Music, 7=Spatial Awareness, 8=Letters / Phonemic, 9=Numbers & Math, 10=Science & Nature Exploration, 11=Problem-Solving & Logic, 12=Other)
voice string No TTS voice ID (default: en-US-Standard-C)
answer_modes array No ["voice", "pick_choices", "draw", "type"]
answers array No Array of answer options with text, correctness, and optional media
image_file string/binary No Base64-encoded image OR binary file for the main question (JPEG, PNG, GIF, WebP)
audio_file string/binary No Base64-encoded audio OR binary file for the main question (MP3, WAV, OGG)

Response Format

{
  "success": 1,
  "message": "Question created successfully",
  "data": {
    "question_id": 12345,
    "bookId": 123,
    "category_id": 456,
    "image_url": "https://storage.quizstop.ai/images/user123/question_12345.jpg",
    "created_at": "2023-12-03T12:00:00.000Z"
  },
  "user": {
    "email": "[email protected]",
    "name": "John Doe",
    "type": "pro"
  },
  "timestamp": "2023-12-03T12:00:00.000Z"
}

Recommended API Workflow

  1. Create a Quiz first using the Create Quiz endpoint to get a bid
  2. Use the bid when creating questions with this Create Question endpoint
  3. Retrieve all quizzes anytime using the Get Quizzes endpoint to see your content

This workflow ensures proper organization of your educational content and enables better tracking and management.

POST /create-video-category

Create Video Category

Create a new video category to organize your educational content.

POST https://api.quizstop.ai/create-video-category
Content-Type: application/json
Authorization: Bearer qz_your_api_key

Request Body

{
  "name": "Science Videos"
}

Response

{
  "success": 1,
  "message": "Video category created successfully",
  "data": {
    "category": {
      "cid": 123,
      "name": "Science Videos",
      "courseId": "user123",
      "createdMs": 1640995200000
    }
  }
}
POST /add-video

Add Video

Add a video to a specific category with metadata and settings.

POST https://api.quizstop.ai/add-video
Content-Type: application/json
Authorization: Bearer qz_your_api_key

Request Body

{
  "title": "Introduction to Physics",
  "yid": "physics-intro-001",
  "cid": 1,
  "sourceType": "youtube",
  "videoUrl": "https://youtube.com/watch?v=abc123",
  "mute": false,
  "disabled": false,
  "isPortrait": false,
  "disableQuestions": false
}

Response

{
  "success": 1,
  "message": "Video added successfully",
  "data": {
    "video": {
      "yid": "physics-intro-001",
      "title": "Introduction to Physics",
      "cid": 1,
      "sourceType": "youtube"
    }
  }
}
POST /delete-video

Delete Video

Permanently remove a video from your collection using its video ID.

POST https://api.quizstop.ai/delete-video
Content-Type: application/json
Authorization: Bearer qz_your_api_key

Request Body

{
  "yid": "physics-intro-001"
}

Response

{
  "success": 1,
  "message": "Video deleted successfully"
}
GET /get-video-categories

Get Video Categories

Retrieve all video categories for organizing your educational content.

GET https://api.quizstop.ai/get-video-categories
Authorization: Bearer qz_your_api_key

Response

{
  "success": 1,
  "message": "Video categories retrieved successfully",
  "data": {
    "categories": [
      {
        "cid": 1,
        "name": "Math",
        "disabled": false,
        "courseId": "course-1",
        "createdMs": 1703000000000,
        "editedMs": 1703100000000
      },
      {
        "cid": 2,
        "name": "Science",
        "disabled": false,
        "courseId": "course-2", 
        "createdMs": 1703200000000,
        "editedMs": null
      }
    ],
    "totalCount": 2
  },
  "user": {
    "email": "[email protected]",
    "name": "Test User"
  },
  "timestamp": "2023-12-03T12:00:00.000Z"
}

Note: This endpoint supports both GET and POST methods. Use GET for simple retrieval or POST for consistency with other endpoints.

GET POST /get-videos-by-category-id

Get Videos by Category ID

Retrieve all videos within a specific category. Supports both query parameters (GET) and request body (POST).

GET https://api.quizstop.ai/get-videos-by-category-id?categoryId=1
Authorization: Bearer qz_your_api_key

Alternative POST Method

POST https://api.quizstop.ai/get-videos-by-category-id
Content-Type: application/json
Authorization: Bearer qz_your_api_key 
{
  "categoryId": 1
}

Response

{
  "success": 1,
  "message": "Found 2 videos in category 1",
  "data": {
    "category": {
      "id": 1,
      "name": "Math"
    },
    "videos": [
      {
        "yid": "video1",
        "title": "Algebra Basics",
        "cid": 1,
        "sourceType": "youtube",
        "courseId": "course-1",
        "createdMs": 1703000000000,
        "editedMs": 1703100000000,
        "mute": false,
        "disabled": false,
        "isPortrait": false,
        "disableQuestions": false,
        "localFilePath": "/path/to/video1",
        "thumbnailPath": "/path/to/thumb1",
        "thumbnailUrl": "https://example.com/thumb1.jpg",
        "videoUrl": "https://example.com/video1.mp4"
      },
      {
        "yid": "video2", 
        "title": "Geometry Intro",
        "cid": 1,
        "sourceType": "local",
        "courseId": "course-1",
        "createdMs": 1703200000000,
        "editedMs": null,
        "mute": false,
        "disabled": false,
        "isPortrait": false,
        "disableQuestions": false,
        "localFilePath": null,
        "thumbnailPath": null,
        "thumbnailUrl": null,
        "videoUrl": null
      }
    ],
    "totalCount": 2
  },
  "user": {
    "email": "[email protected]",
    "name": "Test User"
  },
  "timestamp": "2023-12-03T12:00:00.000Z"
}

Special Category: Use categoryId: 0 to retrieve videos in the default category. This endpoint also accepts cid as an alternative parameter name.

GET /get-profiles

Get Profiles

Retrieve all user profiles associated with your account.

GET https://api.quizstop.ai/get-profiles
Authorization: Bearer qz_your_api_key

Response

{
  "success": 1,
  "message": "Profiles retrieved successfully",
  "data": {
    "profiles": [
      {
        "id": 123,
        "name": "Default Profile",
        "credits": 100,
        "isDefault": true
      },
      {
        "id": 124,
        "name": "Student Profile",
        "credits": 50,
        "isDefault": false
      }
    ],
    "totalCount": 2
  }
}
GET/POST /get-profile

Get Profile

Retrieve a specific user profile by ID. Supports both GET (with query parameter) and POST (with request body) methods.

GET Method (Query Parameter)

GET https://api.quizstop.ai/get-profile?id=123
Authorization: Bearer qz_your_api_key

POST Method (Request Body)

POST https://api.quizstop.ai/get-profile
Content-Type: application/json
Authorization: Bearer qz_your_api_key 
{
  "id": 123
}

Response

{
  "success": 1,
  "data": {
    "profile": {
      "id": 123,
      "name": "Default Profile",
      "credits": 100
    }
  }
}
GET /get-schools

Get Schools

Retrieve all schools associated with your authenticated user account.

GET https://api.quizstop.ai/get-schools
Authorization: Bearer qz_your_api_key

Response

{
  "success": 1,
  "data": {
    "schools": [
      {
        "schoolId": "school-123",
        "schoolName": "Lincoln Elementary",
        "teachingLanguage": "en"
      },
      {
        "schoolId": "school-456", 
        "schoolName": "Washington High School",
        "teachingLanguage": "es"
      }
    ],
    "totalCount": 2
  }
}
GET /get-insight

Get Insights

Retrieve learning analytics and insights showing question performance data for your users.

GET https://api.quizstop.ai/get-insight
Authorization: Bearer qz_your_api_key

Response

{
  "success": 1,
  "data": {
    "insights": [
      {
        "questionId": "q-123",
        "count": 5,
        "correct": 3,
        "wrong": 2
      },
      {
        "questionId": "q-456",
        "count": 8,
        "correct": 6,
        "wrong": 2
      }
    ],
    "totalQuestions": 10
  }
}
POST /delete-question

Delete Question

Permanently remove a question from your collection using its unique question ID.

POST https://api.quizstop.ai/delete-question
Content-Type: application/json
Authorization: Bearer qz_your_api_key

Request Body

{
  "id": "question-uuid-123"
}

Response

{
  "success": 1,
  "message": "Question deleted successfully"
}
GET/POST /get-questions-by-quiz-id

Get Questions by Quiz ID

Retrieve all questions associated with a specific quiz. This endpoint helps you access the complete question set for a quiz, including all metadata, answer options, and configuration settings.

GET Method (Query Parameter)

GET https://api.quizstop.ai/get-questions-by-quiz-id?quizId=123
Authorization: Bearer qz_your_api_key

POST Method (Request Body)

POST https://api.quizstop.ai/get-questions-by-quiz-id
Content-Type: application/json
Authorization: Bearer qz_your_api_key 
{
  "quizId": 123
}

Response

{
  "success": 1,
  "message": "Found 5 questions for quiz 123",
  "data": {
    "quiz": {
      "id": 123,
      "name": "European Geography Quiz"
    },
    "questions": [
      {
        "id": "q-12345",
        "questionText": "What is the capital of France?",
        "bookId": 123,
        "categoryId": 10,
        "imageUrl": "https://storage.quizstop.ai/images/question.jpg",
        "audioUrl": "https://storage.quizstop.ai/audio/question.mp3",
        "voice": "en-US-Standard-C",
        "answerModes": ["voice", "pick_choices"],
        "answers": [
          {
            "text": "Paris",
            "is_correct": true
          },
          {
            "text": "London",
            "is_correct": false
          },
          {
            "text": "Berlin",
            "is_correct": false
          }
        ],
        "isOpenEnded": false,
        "requireAllCorrect": false,
        "isStatement": false,
        "waitTimeSeconds": 30,
        "rewardCredits": 1,
        "evaluationMode": "simple",
        "customEvaluationPrompt": null,
        "createdAt": "2023-12-03T12:00:00.000Z"
      }
    ],
    "totalCount": 5
  },
  "user": {
    "email": "[email protected]",
    "name": "John Doe"
  },
  "timestamp": "2023-12-03T12:00:00.000Z"
}

Response Fields

Field Type Description
quiz.id integer The quiz ID that was queried
quiz.name string Name of the quiz
questions array Array of question objects belonging to this quiz
questions[].id string Unique question identifier
questions[].questionText string The main question text
questions[].categoryId integer Educational category ID (1-12)
questions[].answerModes array Allowed answer input methods
questions[].answers array Multiple choice answer options (if applicable)
totalCount integer Total number of questions found

Use Cases & Workflow

  • Quiz Review: Get all questions in a quiz to review content before publishing
  • Content Export: Extract question data for backup or migration purposes
  • Analytics Preparation: Collect question metadata for performance analysis
  • Question Management: List all questions to identify which ones need updates

This endpoint is perfect for quiz management dashboards and content review workflows.

Important Notes

  • Returns empty array if quiz exists but has no questions
  • Returns 404 error if the specified quiz ID doesn't exist
  • Questions include all metadata: images, audio, answers, and settings
  • Supports both GET (query param) and POST (request body) methods
  • All media URLs are fully qualified and accessible

Quick Start

Get up and running with the QuizStop API in minutes.

📝 Documentation in progress - Coming soon!

Code Examples

Implementation examples for popular programming languages and platforms.

📝 Documentation in progress - Coming soon!

Error Handling

Understanding API errors and how to handle them.

📝 Documentation in progress - Coming soon!

Rate Limits

API usage limits and best practices.

📝 Documentation in progress - Coming soon!