V1 Documentation

QuizCore API Reference

Empower your educational applications with our robust Assessment Engine. Programmatically access high-quality shared questions or manage your internal private question bank with total control.

Base URL

https://app.quizcore.org/api/v1

Response Format

All responses are returned as application/json.

Postman Documentation

Prefer using Postman? We have a comprehensive collection with pre-configured requests and environments.

View Collections

Authentication

The QuizCore API uses API Keys to authenticate requests. You can view and manage your API keys in the Organization Settings > API Keys section of your dashboard.

# Authenticate using the Bearer token strategy
Authorization: Bearer your_api_key_here

Security Warning

Your API keys carry significant privileges. Keep them secure and never expose them in client-side code (browsers, mobile apps). Always perform API requests from your backend server.

Rate Limits

We enforce rate limits to ensure stability for all customers. Limits are applied based on your organization and are tracked across different time windows.

Header	Description
X-RateLimit-Limit	Total requests allowed within the current window.
X-RateLimit-Remaining	Number of requests remaining in the current window.
Retry-After	The number of seconds to wait before making a new request.

Shared Question Pool

Monthly Question Cap

By default, organizations can access up to 10% of the total shared question pool per month. Exceeding this cap will return a 403 Forbidden response until the next month cycle.

GET/v1/questions

Retrieve a list of shared, published questions with filtering capabilities.

Query Parameters

per_page

Results per page (max 100). Default: 25

page

Pagination page number.

level_id

Filter by level ID.

subject_id

Filter by subject ID.

topic_id

Filter by topic ID.

difficulty

Filter: easy, intermediate, advanced

question_type

Filter: mcq, short_answer, long_answer

exclude_ids

Comma-separated IDs to skip.

GET/v1/questions/:id

Retrieve details for a single shared question.

Private Question Vault

GET/v1/private-questions

Retrieve questions owned by your organization.

Supports: per_page, topic_id, difficulty, question_type.

GET/v1/private-questions/:id

Get full details for a single private question.

POST/v1/private-questions

Add a new question to your organization's private vault. Questions are automatically assigned to your organization ID.

Example Request Body

{
  "topic_id": 142,
  "body": "What is the capital of Nigeria?",
  "question_type": "mcq",
  "options": ["Lagos", "Abuja", "Kano", "Ibadan"],
  "difficulty": "easy",
  "correct_answer": "Abuja",
  "solution_summary": "Abuja became capital in 1991."
}

PUT/v1/private-questions/:id

Update an existing private question. You can partially update fields like body, options, or difficulty.

DELETE/v1/private-questions/:id

Permanently remove a private question. This action cannot be undone.

Taxonomy

Browse the shared public taxonomy or manage your organization's private curriculum structure (levels, subjects, topics) via these endpoints.

Public Taxonomy (Read-Only)

GET/v1/taxonomy/tree

Returns the full nested taxonomy tree (levels → subjects → topics) for the shared/global question bank.

Params: per_page (default 10, max 50), page

GET/v1/taxonomy/levels

List all public levels.

Params: per_page

GET/v1/taxonomy/subjects

List public subjects.

Params: level_id, per_page

GET/v1/taxonomy/topics

List public topics.

Params: subject_id, per_page

Private Taxonomy (CRUD)

Manage your organization's own curriculum structure. These endpoints mirror the public taxonomy paths but operate on your private data with full CRUD support.

GET/v1/private-taxonomy/tree

Returns the full nested tree of your organization's private taxonomy. Useful for building navigation menus or curriculum maps.

Params: per_page (default 10, max 50), page

Resource: Levels

GET/v1/private-taxonomy/levels

List organization levels.

POST/v1/private-taxonomy/levels

Create a new level.

PUT/v1/private-taxonomy/levels/:id

Update a level.

DELETE/v1/private-taxonomy/levels/:id

Delete a level (must have no subjects).

Example: POST /v1/private-taxonomy/levels

{
  "name": "Senior Secondary 1",
  "sort_order": 1
}

Resource: Subjects

GET/v1/private-taxonomy/subjects

List subjects. Supports filtering by level_id.

POST/v1/private-taxonomy/subjects

Create a subject under a specific level.

PUT/v1/private-taxonomy/subjects/:id

Update a subject.

DELETE/v1/private-taxonomy/subjects/:id

Delete a subject (must have no topics).

Example: POST /v1/private-taxonomy/subjects

{
  "name": "Mathematics",
  "level_id": 12
}

Resource: Topics

GET/v1/private-taxonomy/topics

List topics. Supports filtering by subject_id.

POST/v1/private-taxonomy/topics

Create a topic under a subject.

PUT/v1/private-taxonomy/topics/:id

Update a topic.

DELETE/v1/private-taxonomy/topics/:id

Delete a topic (must have no questions).

Example: POST /v1/private-taxonomy/topics

{
  "name": "Trigonometry",
  "subject_id": 45
}

Error Handling

Standard HTTP response codes are used to indicate the success or failure of an API request.

200/201

Success

Request completed successfully.

400

Bad Request

Missing required parameters.

401

Unauthorized

Invalid or missing API key.

403

Forbidden

Monthly cap reached or no plan access.

404

Not Found

Resource does not exist.

422

Validation failed

Input data formatting errors.

429

Too Many Requests

Slow down! Rate limit exceeded.