Key lifecycleGetting started

Keys are shown once, stored as hashes, and validated before work begins

API keys, permissions, and request gating

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.

Manage keys

Route-accurate reference

Shown once

Plaintext only on create

The settings UI displays the full key only at creation time.

Stored server-side

Hashed only

Stored fields include name, prefix, suffix, hash, permissions, timestamps, and schema version.

Permission model

Scoped route checks

Middleware resolves required permissions by route prefix and then validates the key.

Auth flow

The middleware first detects whether the request is using an API key. If not, normal Vidbyte auth continues untouched. If a key is present, the API-key chain verifies the hash, resolves the principal, checks route permissions, validates subscription/entitlements, and only then lets the request proceed.

This is the chain-of-responsibility pattern described in the design memo: fail fast on missing or invalid credentials, preserve route handler simplicity, and keep usage accounting consistent after successful work.

What callers should assume

A successful key is necessary but not sufficient. Requests can still fail on permission mismatch, expired/disabled keys, exhausted balance, or rate-limit windows.

Keys also carry business meaning: over time, key-level spend tiering can unlock higher rate limits and token windows without changing the calling contract.

Routes

What this page actually points to

4 entries

POSTLive

/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

promptstringRequired

Primary user request, learning goal, or topic for generation.

modestringOptional

QuickHit steering mode. The current validator accepts `broad` or `narrow`.

Default

broad

contextobject[]Optional

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.

POSTLive

/api/v1/roadmaps/create

Generate a learning roadmap and return its public id plus structured module data.

Auth

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

Maps to

/api/roadmap/create

Notes

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

Request fields

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.

timelinestringOptional

Desired pacing, target date, or timeframe summary.

Default

3 months

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

Roadmap create returns modules, course summary, and course outcomes in `data`.

POSTLive

/api/v1/quizzes/create

Generate a quiz resource from a topic, source content, and quiz controls.

Auth

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

Maps to

/api/sandbox/create_quiz

Notes

The route is live today. The docs use the flat v1 contract language even though the service layer still normalizes into richer nested quiz attributes internally.

Request fields

titlestringOptional

Optional title for the generated quiz resource.

promptstringRequired

Primary user request, learning goal, or topic for generation.

contentstringOptional

Optional raw source material to generate from when you want to bypass a separate upload step.

quiz_typestringOptional

Quiz type selector. Common values include `multiple_choice`, `true_false`, and `open_ended`.

Default

multiple_choice

reasoning_lensstringOptional

Optional reasoning lens selector. Exact accepted values come from the quiz service/validator layer.

difficultystringOptional

Optional quiz difficulty steering. Use values accepted by the quiz validator layer.

lengthstringOptional

Optional quiz length control such as micro, short, medium, long, or comprehensive.

assessment_intentstringOptional

Optional assessment intent such as formative, summative, diagnostic, or predictive.

explanation_lengthstringOptional

Optional explanation depth selector.

question_stylestringOptional

Optional question style / directness control.

content_focusstringOptional

Optional control for how tightly the quiz should stay tied to source material.

contextobject[]Optional

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 create returns a sanitized quiz resource with `quiz_data`, quiz type, public id, and usage metadata.

POSTLive

/api/v1/projects/create

Create a project draft from a learner topic and steering inputs.

Auth

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

Maps to

/api/sandbox/projects/create

Notes

The public route returns the draft project id. Supporting `questions` and `generate` routes continue the project lifecycle.

Request fields

promptstringRequired

Primary user request, learning goal, or topic for generation.

contextobject[]Optional

Optional typed context objects. Supported types today are `text`, `doc`, `pdf`, `quickhit`, `roadmap`, `quiz`, `exam`, `project`, and `vidbyte_project`.

project_goalstringOptional

High-level outcome the learner should ship or achieve.

why_this_mattersstringOptional

Motivation, business reason, or learning importance steering.

current_levelstringOptional

Current learner level or baseline capability summary.

depth_preferencestringOptional

Desired depth or scope preference.

guidance_levelstringOptional

Preferred amount of guidance or scaffolding.

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

Project create returns the draft project resource boundary. Use that public id for later questions/generate/get calls.

Request details

Required headers

Either bearer auth or `x-api-key` works for the public API surface.

AuthorizationstringOptional

Bearer token containing a Vidbyte API key.

Default

Bearer vb_live_your_api_key

x-api-keystringOptional

Alternative plaintext API key header accepted by the auth middleware.

Default

vb_live_your_api_key

Content-TypestringRequired

JSON request bodies are required on the current public routes.

Default

application/json

Key record metadata

The persisted key record is metadata-first and avoids storing plaintext secrets.

namestringRequired

Human-readable label for the key.

key_prefixstringRequired

Short visible prefix used for masking and debugging.

key_suffixstringRequired

Short visible suffix used for masking and debugging.

key_hashstringRequired

HMAC/SHA-based hashed representation of the plaintext key.

permissionsstring[]Required

Granted scopes or admin-style permissions for the key.

created_atdatetimeRequired

Creation timestamp.

expires_atdatetime | nullOptional

Optional expiration time.

disabled_atdatetime | nullOptional

Timestamp used to disable a key.

last_used_atdatetime | nullOptional

Updated when the key is used.

schema_versionintegerRequired

Versioned schema marker for migrations.

Production-ready

Quickstart

The shortest integration path is: create a key in settings, send it as either a bearer token or `x-api-key`, call a create route, and store the returned public `id` for later retrieval.

Open page

v1 architecture

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.

Open page

Shared adapter

Context Objects

Every create route can accept an optional `context` array. Context objects let you pass inline text, uploaded docs/PDFs, or public ids of other Vidbyte resources without changing the route contract for each endpoint family.

Open page