v1 architectureArchitecture

One backend, reusable orchestrators, public IDs, and a universal context layer

The design patterns behind the API

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.

Manage keys

Route-accurate reference

Auth strategy

Single backend / dual auth

The middleware chooses API-key auth or normal Vidbyte auth based on the incoming headers.

Contract style

Flat public request layer

The API stays ergonomic even when service-layer configs are richer internally.

Context pattern

Adapter + facade

Typed context objects let any endpoint consume text, files, or Vidbyte resources through one field.

Key architecture patterns

Single backend / dual auth strategy: the difference between app traffic and external API traffic is the auth path in middleware, not a separate product backend.

Encrypted id boundary: create, list, and get routes use public encrypted ids so the API never exposes raw database identifiers.

Shared service-layer pattern: public routes keep reusing the same orchestrators that power the product experience.

Flat API contract pattern: endpoint payloads stay ergonomic even when the downstream service layer is nested or preset-driven.

Tiered rate limiting pattern: authentication resolves identity first, then rate limits and token windows are applied by plan and, eventually, by API-key spend tier.

How context works

Every create route can accept `context`, an array of typed context objects. That lets callers inject learner notes, source docs, PDFs, previous QuickHits, Roadmaps, quizzes, exams, or projects without changing the route shape itself.

This is the API-layer version of the context adapter/facade pattern described in the design memo: callers keep one stable field, while the backend resolves inline text, uploaded documents, internal Vidbyte resources, and future connector sources through helper classes behind that boundary.

What request state the middleware appends

When authentication succeeds on an API-key request, middleware resolves the authenticated principal and attaches API-key state such as `request.state.user_id`, `request.state.auth_mode = "api_key"`, `request.state.is_api_key_request = true`, and `request.state.api_key_principal`.

That keeps route handlers consistent with the normal product auth path while still allowing public response shaping, permission checks, and usage accounting to behave differently for API callers.

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/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

promptstringRequired

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

project_idstringRequired

Encrypted public id returned by project create.

answersstring[]Optional

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.

Key lifecycle

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.

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

Shared envelope

Response Shape

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.

Open page

v1 reference

Overview

Vidbyte exposes a public API for generating learning roadmaps, QuickHits, quizzes, exams, and projects. The same backend serves both logged-in Vidbyte users and API-key callers, so you get the production orchestration layer through a clean versioned contract.

Open page