Assessment generation plus progressive updates
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.
Core routes
5
Create, batch create, list, get, and update.
Request style
Flat public knobs
The docs present the intended ergonomic v1 contract while the backend normalizes to richer quiz attributes.
Update model
Action-driven
Adjust difficulty, reasoning, length, focus, structure, and sequential progression.
Two ways to think about quiz generation
For most callers, the public v1 mental model should stay flat: prompt, content, quiz type, context, and a handful of top-level steering knobs.
For power users, Vidbyte's quiz engine also has a richer internal attribute system covering question design, content relationship, answer-choice architecture, and quiz info. The public route normalizes into those structures behind the scenes.
Why update matters
Quiz update turns a single generated quiz into a progressive assessment workflow. That is how you can start with a baseline quiz, then make it harder, more inferential, more diagnostic, or more sequential without rebuilding your product-side logic around a separate route family.
Routes
What this page actually points to
/api/v1/quizzes/create
Generate a quiz resource from a topic, source content, and quiz controls.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/sandbox/create_quiz
Notes
The route is live today. The docs use the flat v1 contract language even though the service layer still normalizes into richer nested quiz attributes internally.
Request fields
Optional title for the generated quiz resource.
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.
Quiz type selector. Common values include `multiple_choice`, `true_false`, and `open_ended`.
Default
multiple_choice
Optional reasoning lens selector. Exact accepted values come from the quiz service/validator layer.
Optional quiz difficulty steering. Use values accepted by the quiz validator layer.
Optional quiz length control such as micro, short, medium, long, or comprehensive.
Optional assessment intent such as formative, summative, diagnostic, or predictive.
Optional explanation depth selector.
Optional question style / directness control.
Optional control for how tightly the quiz should stay tied to source material.
Optional typed context objects. Supported types today are `text`, `doc`, `pdf`, `quickhit`, `roadmap`, `quiz`, `exam`, `project`, and `vidbyte_project`.
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`.
Quiz create returns a sanitized quiz resource with `quiz_data`, quiz type, public id, and usage metadata.
/api/v1/quizzes/batch_create
Generate multiple quizzes sequentially in one request envelope.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/sandbox/create_quiz
Notes
Best for cohort-style workloads or when you want several quiz variants returned together.
Request fields
Array of quiz create payloads. The current backend supports 1 to 20 items per batch.
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`.
Batch create returns one result object per requested quiz plus aggregated `token_stats` and `pricing`.
/api/v1/quizzes/list
List quizzes generated by the authenticated user.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/sandbox/quizzes/list
Notes
The list endpoint returns sanitized quiz resources only.
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/quizzes/get/{encrypted_id}
Fetch one quiz by encrypted public id.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/sandbox/quizzes/get/{encrypted_id}
Notes
The returned payload includes sanitized `quiz_data` only for the owned resource.
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`.
/api/v1/quizzes/update
Apply progressive quiz update actions such as harder/easier, reasoning changes, and next-quiz progression.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/sandbox/edit_quiz
Notes
Actions can be passed as canonical slugs or grouped directives like `difficulty`, `reasoning`, `length`, `question_answers`, and `next_quiz`.
Request fields
Encrypted public id of the quiz to update.
Either an array of canonical update actions or a grouped object. Semantic phrases like `harder`, `expert`, or `next sequential topic` are normalized by the middleware.
Optional freeform semantic guidance for the update.
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`.
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`.
Quiz update returns the new quiz iteration as a sanitized public resource.
Request details
Recommended top-level quiz controls
These are the main v1 knobs to think about when designing quiz calls.
Quiz type such as `multiple_choice`, `true_false`, or `open_ended`.
Difficulty steering. The exact accepted values live in the validator/service layer.
Length control for the quiz.
Reasoning lens selector.
Formative, summative, diagnostic, predictive, or similar intent.
How direct, scenario-based, or case-driven the questions should feel.
How tightly the quiz should stay tied to the provided source material.
Related pages
Exams
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.
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.
Response Shape
Vidbyte uses a standardized response envelope for public API routes. That makes it easier for product teams and agents to parse success state, ids, usage telemetry, pricing, and errors without special-casing every endpoint family.