Generate structured learning plans with modules, outcomes, and pacing
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.
Core routes
3 + module fetch
Create, list, get, plus module-specific retrieval.
Best fit
Curriculum + sequencing
Ideal when your product needs staged learning paths rather than short explainers.
Common steering
Experience + timeline
The route accepts learner level, pacing, and resource preference.
Why roadmaps are durable resources
A roadmap is not just a blob of text. It is a structured resource with modules and outcomes that your application can render, revisit, or slice into smaller subviews like per-module retrieval.
That makes roadmaps a strong fit for onboarding programs, certification prep, internal training plans, or agent workflows that need a stepwise plan before generating follow-up content.
Routes
What this page actually points to
/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/roadmaps/list
List roadmaps owned by the authenticated API principal.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/roadmap/list
Notes
Useful when your application treats Vidbyte as a backing generation system and needs to rehydrate state.
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`.
/api/v1/roadmaps/get/{encrypted_id}/{module_number}
Fetch a specific roadmap module by public roadmap id and module index.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/roadmap/get/{encrypted_id}/{module_number}
Notes
Helpful when you want resource-level views without pulling the entire roadmap repeatedly.
Request fields
Encrypted public identifier returned by a create or list route.
Zero-based module index within the roadmap.
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
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.
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.
Projects
The Projects API is a staged resource family. You create a project draft first, optionally gather intake questions, then generate the full project artifact and fetch it later by its encrypted public id.