Vidbyte

API documentation

Browse docs

Create a Roadmap

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

POST /api/v1/roadmaps/create

Create a Roadmap

Create a new roadmap with learner context, pacing, and resource preferences. The response includes the encrypted public id plus the generated roadmap structure.

Manage keys
Stable public contract

Public endpoint

/api/v1/roadmaps/create

Maps to

/api/roadmap/create

What to know first

The public route reuses the existing roadmap orchestrator while attaching API-key auth and response sanitization.

Method

POST

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

Authentication

API key

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

Resource model

Direct

The public route reuses the existing roadmap orchestrator while attaching API-key auth and response sanitization.

Highlights

What this operation does

Generate a learning roadmap and return its public id plus structured module data.
The public route reuses the existing roadmap orchestrator while attaching API-key auth and response sanitization.
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/roadmaps/create. Path parameters and request-body fields are shown together because the docs stay focused on the public route contract.

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.

View supported values8 options
Total Beginner

Assume no working background and start from the floor.

Beginner

Use accessible language and foundational sequencing.

Intermediate

Skip the very first principles and move faster into execution.

Advanced

Assume strong baseline knowledge and prioritize depth.

Expert

Aim for nuanced tradeoffs, edge cases, and mastery-level pacing.

Professional

Bias toward practical delivery and workplace applicability.

Hobbyist

Keep the plan motivated by curiosity and self-directed learning.

Student

Optimize for structured progression and deliberate practice.

timelinestringOptional

Desired pacing, target date, or timeframe summary.

Default

3 months

View supported values8 options
1 Month

A compressed plan for immediate skill ramp-up.

3 Months

A balanced short-term roadmap and the default backend pace.

6 Months

A medium-horizon plan with more room for repetition and projects.

9 Months

A longer runway for stronger coverage and reinforcement.

1 Year

A durable year-long plan with substantial breadth and depth.

2 Years

A long-horizon roadmap for serious professional growth.

3 Years

A slow-burn path designed around mastery over time.

5+ Years

A very long horizon that treats the topic as an extended discipline.

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

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`.
Roadmap create returns modules, course summary, and course outcomes in `data`.