Longer-form assessments with sectioning, pacing, and difficulty controls
Use the Exams API when you need a heavier-weight assessment than a quiz: larger question sets, section planning, difficulty shaping, and duration-aware output.
Core routes
3
Create, list, and get.
Best fit
Higher-stakes assessment
Use exams when you need sectioned or longer-form evaluation.
Steering model
Exam parameters
Time density, difficulty, topic organization, question mix, and intentions.
Quiz vs. exam
Choose quizzes when you want diagnostic or study-oriented checks. Choose exams when you need larger, more deliberate assessment structures with pacing, longer duration, and a clearer sense of section planning.
The backend already treats exam generation as its own orchestration path, which is why the public contract deserves its own route family rather than being framed as just "a bigger quiz."
Routes
What this page actually points to
/api/v1/exams/create
Generate a structured exam from a topic, source content, and exam controls.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/sandbox/create_test
Notes
The public route exists today. The docs describe the intended flat API contract while the service layer continues to normalize into exam settings internally.
Request fields
Primary user request, learning goal, or topic for generation.
Optional raw source material to generate from when you want to bypass a separate upload step.
Optional typed context objects. Supported types today are `text`, `doc`, `pdf`, `quickhit`, `roadmap`, `quiz`, `exam`, `project`, and `vidbyte_project`.
Optional time-pressure control.
Optional exam difficulty control such as foundational, progressive, or expert.
Optional reasoning lens selector.
Optional topic ordering / section flow control.
Relative mix of multiple choice, true/false, and open-ended questions.
Optional target question count.
Optional target section count.
Optional target duration for the finished exam.
Pedagogical intent summary or list.
Response shape
Public responses use the shared envelope: `success`, `id`, `message`, `data`, `token_stats`, `pricing`, and `error`.
The `id` field is always a public/encrypted identifier boundary, never a raw MongoDB `_id`.
Exam create returns a sanitized exam resource with `exam_data` and usage metadata.
/api/v1/exams/list
List exams owned by the authenticated API principal.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/sandbox/exams/list
Notes
Returns only sanitized public exam resources.
Response shape
Public responses use the shared envelope: `success`, `id`, `message`, `data`, `token_stats`, `pricing`, and `error`.
The `id` field is always a public/encrypted identifier boundary, never a raw MongoDB `_id`.
/api/v1/exams/get/{encrypted_id}
Fetch one exam by encrypted public id.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/sandbox/exams/get/{encrypted_id}
Notes
Use the `id` returned by create/list, never an internal database id.
Request fields
Encrypted public identifier returned by a create or list route.
Response shape
Public responses use the shared envelope: `success`, `id`, `message`, `data`, `token_stats`, `pricing`, and `error`.
The `id` field is always a public/encrypted identifier boundary, never a raw MongoDB `_id`.
Request details
Recommended top-level exam controls
The public v1 design keeps exam steering understandable at the route layer.
Time-pressure control for the exam.
Exam difficulty control.
Reasoning lens selector.
Topic ordering and grouping control.
Relative mix of multiple choice, true/false, and open-ended items.
Target number of questions.
Target number of sections.
Approximate intended completion time.
Related pages
Quizzes
The Quizzes API covers the full quiz lifecycle: create a quiz, batch-generate multiple quizzes, list and fetch saved quizzes, and progressively update an existing quiz by semantic action groups.
Context Objects
Every create route can accept an optional `context` array. Context objects let you pass inline text, uploaded docs/PDFs, or public ids of other Vidbyte resources without changing the route contract for each endpoint family.
Projects
The Projects API is a staged resource family. You create a project draft first, optionally gather intake questions, then generate the full project artifact and fetch it later by its encrypted public id.