Preview contractGetting started

Documented as product direction while the live versioned routes remain mostly prompt-first

Context objects are the next shared request envelope

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.

Manage keys
Route-accurate reference

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

2 entries
POSTLive

/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

promptstringRequired

Topic or concept to explain.

modestringOptional

Generation mode forwarded to the internal quickhits route.

Default

broad

contextobject[]Optional

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.

POSTLive

/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

promptstringRequired

Learning objective or curriculum request.

timelinestringOptional

Preferred pacing string passed into roadmap generation.

Default

3 months

experiencestring | string[]Optional

Learner experience level. Strings are normalized into the backend list form.

resource_preferencestringOptional

Optional bias toward a resource style.

contextobject[]Optional

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.

typestringRequired

Source type such as `text`, `doc`, `quickhit`, `roadmap`, or future connector types.

labelstringOptional

Human-readable label for debugging or analytics.

bodystring | objectOptional

Inline context payload.

idstringOptional

Encrypted identifier when referencing a Vidbyte-owned object.

metadataobjectOptional

Connector or learner-profile metadata.

Related pages