One field, many input sources
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.
Supported types
9
text, doc, pdf, quickhit, roadmap, quiz, exam, project, vidbyte_project.
Document handling
Base64 payloads
Docs and PDFs are parsed server-side before being appended to model context.
Resource references
Encrypted ids only
Referenced resources must use the same public ids returned by the API.
Resource-backed context
When you reference a QuickHit, Roadmap, quiz, exam, or project in `context`, the backend resolves that resource by encrypted public id, verifies ownership, and injects a condensed representation into the request context.
That means you can chain Vidbyte artifacts together: for example, generate a roadmap from a QuickHit, or generate a quiz from a roadmap module and a PDF in the same request.
Connector direction
The design direction is for `context` to remain the stable public contract while helper/provider adapters grow behind it. That is where future Notion, Google Drive, and other provider integrations fit: new resolvers under the same `context` boundary rather than new route shapes for every connector.
Routes
What this page actually points to
/api/v1/quickhits/create
Generate a QuickHit from a topic and optional context.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/quickhits/create
Notes
Best first integration if you want the smallest, fastest content-generation request.
Request fields
Primary user request, learning goal, or topic for generation.
QuickHit steering mode. The current validator accepts `broad` or `narrow`.
Default
broad
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`.
QuickHit create returns the encrypted QuickHit token as `id` so you can fetch it later.
/api/v1/roadmaps/create
Generate a learning roadmap and return its public id plus structured module data.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/roadmap/create
Notes
The public route reuses the existing roadmap orchestrator while attaching API-key auth and response sanitization.
Request fields
User learning goal or curriculum request.
Experience level or short experience summary. The backend normalizes this into its internal list form.
Desired pacing, target date, or timeframe summary.
Default
3 months
Optional steering for videos, reading/docs, projects, or other resource styles.
Extra learner or project context to shape the roadmap.
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`.
Roadmap create returns modules, course summary, and course outcomes in `data`.
/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/projects/create
Create a project draft from a learner topic and steering inputs.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/sandbox/projects/create
Notes
The public route returns the draft project id. Supporting `questions` and `generate` routes continue the project lifecycle.
Request fields
Primary user request, learning goal, or topic for generation.
Optional typed context objects. Supported types today are `text`, `doc`, `pdf`, `quickhit`, `roadmap`, `quiz`, `exam`, `project`, and `vidbyte_project`.
High-level outcome the learner should ship or achieve.
Motivation, business reason, or learning importance steering.
Current learner level or baseline capability summary.
Desired depth or scope preference.
Preferred amount of guidance or scaffolding.
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`.
Project create returns the draft project resource boundary. Use that public id for later questions/generate/get calls.
Request details
Common context object fields
Different context types use different subsets of these fields.
Context type such as `text`, `pdf`, `quickhit`, or `roadmap`.
Inline text payload for `text` context.
Encrypted public id for resource-backed context types.
Base64-encoded document payload for `doc` and `pdf` context types.
Helpful descriptor for uploaded documents.
Optional roadmap module selector when the context type is `roadmap`.
Related pages
Core Concepts
The Vidbyte API is shaped around a few stable architectural patterns: the same backend serves app users and API users, public routes reuse the product service layer, encrypted ids protect the resource boundary, and `context` acts as the universal adapter for inputs.
Authentication
Vidbyte API keys are created through the authenticated settings UI, shown in plaintext once, and stored as hashed records with key prefix/suffix metadata. The public middleware accepts either `Authorization: Bearer vb_live_...` or `x-api-key`, then checks route permissions, subscription status, entitlements, and usage policy before a generation route runs.
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.
Roadmaps
Roadmaps turn a learning goal into a phased plan. The public API supports create, list, get, and module-specific retrieval, all using encrypted public ids.