The middleware validates identity before generation work begins
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.
Accepted headers
2
Bearer and `x-api-key` are both supported.
Permissions
full_access
Current API keys ship with a single broad permission value.
Fail-closed checks
subscription + credits
Invalid balance or disabled keys stop the request before orchestration.
What the middleware does
API-key requests are only allowed on paths explicitly approved by `is_api_key_route`, which currently means the versioned quickhits and roadmaps prefixes.
After the key resolves, middleware validates the subscription, checks endpoint entitlements, attaches the resolved user to request state, and only then allows the route handler to run.
What callers should expect
Disabled or expired keys return authentication errors. Valid keys with no remaining credits fail with payment-style errors before any generation begins.
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
Headers
Minimum headers for the current public API-key routes.
Bearer token containing a Vidbyte API key. Supported for the public API-key surface.
Default
Bearer vb_live_your_api_key
Alternative plaintext API key header accepted by the backend middleware.
Default
vb_live_your_api_key
JSON request bodies are required on the current public routes.
Default
application/json
Related pages
Quickstart
The fastest path is: create a key in settings, send it as a bearer token or `x-api-key`, then call the live quickhits or roadmaps create route under `/api/v1`.
Context Objects
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.
Overview
Vidbyte's API docs now separate what is live today from what is still product direction. The public API-key surface currently ships versioned create routes for quickhits and roadmaps, while quizzes, exams, and projects remain internal or preview-only.