Parse one shape, then inspect resource-specific `data`
Vidbyte uses a standardized response envelope for public API routes. That makes it easier for product teams and agents to parse success state, ids, usage telemetry, pricing, and errors without special-casing every endpoint family.
Stable envelope
7 core keys
`success`, `id`, `message`, `data`, `token_stats`, `pricing`, and `error`.
Resource identity
Public id only
The `id` field always represents a public/encrypted identifier boundary.
Usage telemetry
Token + pricing aware
Generation routes can return token stats and pricing in the same envelope.
What to persist
Persist the public `id` and any resource-specific identifiers inside `data` that your app needs for later display or synchronization. Do not infer database ids or depend on internal field names that are not part of the public envelope.
For list/get flows, your code can often ignore `token_stats` and `pricing`. For generation flows, those fields are important for monitoring and billing analytics.
How to reason about errors
Authentication, permission, context-validation, not-found, rate-limit, and usage-accounting failures can all happen before or after route execution. The public response contract is designed to surface those failures without leaking raw internal exception details.
Routes
What this page actually points to
/api/v1/quickhits/create
Generate a QuickHit from a topic and optional context.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/quickhits/create
Notes
Best first integration if you want the smallest, fastest content-generation request.
Request fields
Primary user request, learning goal, or topic for generation.
QuickHit steering mode. The current validator accepts `broad` or `narrow`.
Default
broad
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`.
QuickHit create returns the encrypted QuickHit token as `id` so you can fetch it later.
/api/v1/quizzes/update
Apply progressive quiz update actions such as harder/easier, reasoning changes, and next-quiz progression.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/sandbox/edit_quiz
Notes
Actions can be passed as canonical slugs or grouped directives like `difficulty`, `reasoning`, `length`, `question_answers`, and `next_quiz`.
Request fields
Encrypted public id of the quiz to update.
Either an array of canonical update actions or a grouped object. Semantic phrases like `harder`, `expert`, or `next sequential topic` are normalized by the middleware.
Optional freeform semantic guidance for the update.
Optional raw source material to generate from when you want to bypass a separate upload step.
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`.
Quiz update returns the new quiz iteration as a sanitized public resource.
/api/v1/projects/generate
Generate the full project output for an existing draft project.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/sandbox/generate_project
Notes
Use this after project create and, optionally, after the intake questions phase.
Request fields
Primary user request, learning goal, or topic for generation.
Encrypted public id returned by project create.
Optional answers to the generated intake questions.
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`.
The generated project response reuses the standard public resource envelope and project object.
Request details
Envelope fields
These keys are the public contract to parse first, before inspecting resource-specific `data`.
Whether the request completed successfully.
Encrypted public id for the created or fetched resource.
Optional human-readable message.
Resource-specific DTO payload.
Usage telemetry for token-consuming generation routes.
Cost metadata for generation routes.
Error state or summary when the request fails.
Related pages
Core Concepts
The Vidbyte API is shaped around a few stable architectural patterns: the same backend serves app users and API users, public routes reuse the product service layer, encrypted ids protect the resource boundary, and `context` acts as the universal adapter for inputs.
Authentication
Vidbyte API keys are created through the authenticated settings UI, shown in plaintext once, and stored as hashed records with key prefix/suffix metadata. The public middleware accepts either `Authorization: Bearer vb_live_...` or `x-api-key`, then checks route permissions, subscription status, entitlements, and usage policy before a generation route runs.
Quickhits
QuickHits are the lowest-friction content family in the Vidbyte API. Use them to turn a topic into a concise explainer, then list or fetch the resulting resource later by its encrypted id.