Vidbyte

API documentation

Browse docs

Create an Exam

Keys
OverviewQuickstartAuth & KeysConnectorsContext adapterImport from connectorsDeveloper guidelinesRate limitsSecurityResponse ShapeQuickhitsRoadmapsQuizzesExamsProjectsBlogContactoverview/create/get/list
POSTLivePOSTFocused route reference

POST /api/v1/exams/create

Create an Exam

Create a new exam with pacing, difficulty, and organizational controls. The response includes the encrypted public id plus the generated assessment structure.

Manage keys
Stable public contract

Public endpoint

/api/v1/exams/create

Maps to

/api/sandbox/create_test

What to know first

The public route exists today. The docs describe the intended flat API contract while the service layer continues to normalize into exam settings internally.

Method

POST

Send this operation to /api/v1/exams/create on the versioned public host.

Authentication

API key

API key via Authorization: Bearer or x-api-key

Resource model

Direct

The public route exists today. The docs describe the intended flat API contract while the service layer continues to normalize into exam settings internally.

Highlights

What this operation does

Generate a structured exam from a topic, source content, and exam controls.
The public route exists today. The docs describe the intended flat API contract while the service layer continues to normalize into exam settings internally.
Store the encrypted `id` returned by create and list routes exactly as returned if you need to fetch the resource again later.

Request details

Request parameters

Request parameters

These are the parameters that shape /api/v1/exams/create. Path parameters and request-body fields are shown together because the docs stay focused on the public route contract.

promptstringRequired

Primary user request, learning goal, or topic for generation.

contentstringOptional

Optional raw source material to generate from when you want to bypass a separate upload step.

contextobject[]Optional

Optional typed context objects. Use this field to send source text, documents, prior Vidbyte resources, or content you imported from a connected provider into the request.

View supported values9 options
text

Inline plain text you want the route to read directly.

doc

A document payload or extracted document text normalized into the context layer.

pdf

A PDF payload or extracted PDF text normalized into the context layer.

quickhit

A previously generated QuickHit identified by its encrypted public id.

roadmap

A previously generated roadmap identified by its encrypted public id.

quiz

A previously generated quiz identified by its encrypted public id.

exam

A previously generated exam identified by its encrypted public id.

project

A previously generated project identified by its encrypted public id.

vidbyte_project

An alias for project-backed context in the current middleware.

time_densitystringOptional

Optional time-pressure control.

View supported values12 options
untimed

Remove time pressure and focus on understanding.

relaxed

Allow generous pacing.

moderate

Use a comfortable but noticeable pace.

standard

Use the normal exam pacing baseline.

brisk

Push quicker decision making.

intensive

Add meaningful pressure to each question.

rapid_fire

Favor quick recall and fast responses.

sprint

Use the highest-intensity short-burst pacing.

variable

Change pacing between sections.

endurance

Test sustained attention over a longer sitting.

analytical

Give more time for derivation and proof-like thinking.

adaptive

Adjust time pressure based on question complexity.

difficulty_levelstringOptional

Optional exam difficulty control such as foundational, progressive, or expert.

View supported values12 options
foundational

Stay close to core concepts and basic recall.

intermediate

Require solid understanding and light multi-step reasoning.

advanced

Require synthesis, judgment, and deeper reasoning.

expert

Bias toward nuance, edge cases, and subtle distinctions.

progressive

Ramp the difficulty upward as the exam continues.

regressive

Start hard and become easier later.

bell_curve

Peak difficulty in the middle sections.

bimodal

Oscillate between easy and hard with little middle ground.

fluctuating

Move up and down unpredictably.

plateau

Keep the same level throughout.

targeted

Tune difficulty to the stated learning objective.

diagnostic

Span a range so the exam can detect proficiency.

reasoning_lensstringOptional

Optional reasoning lens selector.

View supported values10 options
first_principles_thinking

Rebuild the idea from fundamental truths instead of pattern matching.

deductive_reasoning

Derive conclusions from stated rules or premises.

inductive_reasoning

Generalize from examples and observations.

analogical_reasoning

Map structure from one situation onto another.

systems_thinking

Reason about interactions across a larger system.

second_order_thinking

Consider downstream effects instead of the first visible outcome.

constraint_based_reasoning

Work from the limiting factors and boundaries in the problem.

bayesian_reasoning

Update beliefs as new evidence arrives.

inversion

Solve by flipping the frame and asking what would make the opposite happen.

opportunity_cost_analysis

Evaluate tradeoffs and what each choice gives up.

topic_organizationstringOptional

Optional topic ordering / section flow control.

View supported values12 options
sequential

Follow the order of the source material.

hierarchical

Move from foundations into specifics.

thematic

Group questions by shared theme.

spiral

Revisit topics with increasing depth.

interleaved

Mix topics together intentionally.

scaffolded

Fade support as the exam progresses.

case_based

Organize around scenarios or cases.

comparative

Contrast related concepts directly.

problem_centered

Organize around problems to solve.

randomized

Use an intentionally unpredictable order.

modular

Split the exam into distinct self-contained blocks.

integrated

Blend multiple topics together within sections.

question_mixobjectOptional

Relative mix of multiple choice, true/false, and open-ended questions.

question_countintegerOptional

Optional target question count.

section_countintegerOptional

Optional target section count.

target_duration_minutesintegerOptional

Optional target duration for the finished exam.

intentionsstring | string[]Optional

Pedagogical intent summary or list.

Response shape

What the response contract guarantees

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.