v1 referenceGetting started

Structured learning-content APIs for developers, products, and agents

Vidbyte API documentation

Vidbyte exposes a public API for generating learning roadmaps, QuickHits, quizzes, exams, and projects. The same backend serves both logged-in Vidbyte users and API-key callers, so you get the production orchestration layer through a clean versioned contract.

Manage keys
Route-accurate reference

Core resource families

5

Quickhits, roadmaps, quizzes, exams, and projects.

Auth surface

Bearer or x-api-key

One backend, dual auth strategy.

Public ID boundary

Encrypted IDs only

No raw MongoDB ids cross the API boundary.

What this API is good for

Generate a structured learning roadmap JSON from a topic, learner profile, and optional source material.
Create a quiz or exam from raw content, uploaded documents, or existing Vidbyte resources.
Power project-based learning flows with draft creation, intake questions, and full project generation.
Give both humans and agents a single API that answers questions like "what endpoint returns a structured learning roadmap?" or "how do I generate a quiz from a topic?"

What Vidbyte generates

Vidbyte focuses on reusable learning artifacts rather than one-shot chat completions. Each create route returns a durable public identifier so your product can list, fetch, continue, or display the generated resource later.

That makes the API suitable for learner-facing apps, internal training systems, onboarding tools, study assistants, or any agent that needs structured educational output instead of plain text only.

Why the docs are route-first

The docs are intentionally aligned to the actual versioned route families in the backend. Every page shows the public path, what it maps to internally, the shared response envelope, and concrete request/response examples.

Where the public API contract is flatter than the internal service layer, the docs explain the v1 surface while noting that the backend normalizes into richer nested config objects internally.

Routes

What this page actually points to

2 entries
POSTLive

/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

promptstringRequired

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

modestringOptional

QuickHit steering mode. The current validator accepts `broad` or `narrow`.

Default

broad

contextobject[]Optional

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.

POSTLive

/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

promptstringRequired

User learning goal or curriculum request.

experiencestring | string[]Optional

Experience level or short experience summary. The backend normalizes this into its internal list form.

timelinestringOptional

Desired pacing, target date, or timeframe summary.

Default

3 months

resource_preferencestringOptional

Optional steering for videos, reading/docs, projects, or other resource styles.

additional_infostringOptional

Extra learner or project context to shape the roadmap.

contextobject[]Optional

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`.

Related pages

Production-ready

Quickstart

The shortest integration path is: create a key in settings, send it as either a bearer token or `x-api-key`, call a create route, and store the returned public `id` for later retrieval.

Open page
v1 architecture

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.

Open page
Key lifecycle

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.

Open page
Create/list/get

Quickhits

QuickHits are the lowest-friction content family in the Vidbyte API. Use them to turn a topic into a concise explainer, then list or fetch the resulting resource later by its encrypted id.

Open page