Create a key, send JSON, persist the returned public ids
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.
Fastest route
POST /api/v1/quickhits/create
Smallest payload and fastest way to validate auth + usage accounting.
Best durable pattern
create -> list/get
Every generated resource can be rehydrated later by its encrypted id.
Context support
Inline + resource refs
You can pass text, docs, PDFs, or existing Vidbyte resources.
Integration sequence
Create an API key in `/settings/api`
The key is displayed in plaintext exactly once. Copy it into a secret manager or environment variable immediately.
Choose a create route
For a minimal first request use QuickHits. For a richer structured output, start with roadmaps or quizzes.
Send JSON with your key
Use either `Authorization: Bearer vb_live_...` or `x-api-key: vb_live_...`, plus `Content-Type: application/json`.
Store the returned `id`
That public id is the lookup key for the corresponding `list` and `get` routes and should be stored alongside your own records.
Recommended first resources
QuickHits are ideal for smoke-testing your integration because the request is small and the output is immediately inspectable.
Roadmaps are the best first structured resource if your product needs learning plans, staged modules, or curriculum sequencing rather than a short explainer.
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/quickhits/get/{encrypted_id}
Fetch one QuickHit by encrypted public id.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/quickhits/get/{encrypted_id}
Notes
Always persist the returned public id from create/list. Raw database ids are never part of the public contract.
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/roadmaps/get/{encrypted_id}
Fetch one roadmap by encrypted public id.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/roadmap/get/{encrypted_id}
Notes
Returns the full roadmap resource boundary rather than a raw database document.
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`.
Related pages
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.
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.
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.
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.