Documented as product direction while the live versioned routes remain mostly prompt-first
The product design describes a shared `context` array for learner data, source documents, and Vidbyte artifacts. That envelope is already present in some request models, but the current public routes still primarily map prompt-driven fields into the existing internal orchestrators.
Field name
context
Present in the versioned request models today.
Current posture
Reserved / limited
The live public flow does not yet fully materialize the envelope.
Future fit
Connector-ready
Design intent includes text, docs, quickhits, roadmaps, and external sources.
Why this page is marked preview
The backend request models already leave room for a `context` field, but the current versioned routes for quickhits and roadmaps still map directly into older internal create flows.
That means the envelope is important design direction, but not a fully shipped external contract yet.
Routes
What this page actually points to
/api/v1/quickhits/create
Create a QuickHit through the current versioned public API contract.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/quickhits/create
Notes
This is the main live API-key route for quickhit generation today.
Request fields
Topic or concept to explain.
Generation mode forwarded to the internal quickhits route.
Default
broad
Reserved in the versioned request model. The mapped backend flow is still prompt-first.
Response shape
Returns `success`, `quickhit_id`, `encrypted_token`, and `data`.
The `encrypted_token` is the durable external reference for later app retrieval flows.
/api/v1/roadmaps/create
Create a roadmap through the current versioned public API contract.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/roadmap/create
Notes
The versioned route creates the record, then forwards into the internal roadmap orchestrator.
Request fields
Learning objective or curriculum request.
Preferred pacing string passed into roadmap generation.
Default
3 months
Learner experience level. Strings are normalized into the backend list form.
Optional bias toward a resource style.
Reserved in the versioned request model while the live route remains primarily prompt-driven.
Response shape
Returns `success`, `roadmap_id`, `message`, `data.modules`, `token_stats`, and `pricing`.
The public versioned surface currently ships create only. Versioned list/get routes are still pending.
Request details
Proposed context object fields
Stable enough to design against, but still preview until the public routes consume them end-to-end.
Source type such as `text`, `doc`, `quickhit`, `roadmap`, or future connector types.
Human-readable label for debugging or analytics.
Inline context payload.
Encrypted identifier when referencing a Vidbyte-owned object.
Connector or learner-profile metadata.
Related pages
Authentication
The backend accepts API keys through either `Authorization: Bearer vb_live_...` or `x-api-key`. Once a key is resolved, the request still has to pass permission checks, subscription validation, entitlement checks, and rate limiting.
Roadmaps
Roadmaps currently expose a live public create route under `/api/v1/roadmaps/create`. Assistant-style follow-up interactions and resource-level quiz retrieval exist in the backend, but they remain internal app-authenticated routes for now.
Projects
Project Studio already has backend generation primitives, but the public API-key surface does not yet expose a clean versioned project create route. The docs therefore show the current internal routes and the planned public direction separately.