Project-based learning with draft creation, intake questions, and generation
The Projects API is a staged resource family. You create a project draft first, optionally gather intake questions, then generate the full project artifact and fetch it later by its encrypted public id.
Core routes
3 + 2 helpers
Create, list, get, plus questions and generate.
Best fit
Hands-on learning
Use projects when your product teaches through building and doing, not only reading or quizzing.
Lifecycle style
Staged
Draft -> intake questions -> full generation.
Why projects are staged
Projects are more sensitive to learner context than the other resource families, so the API supports a staged lifecycle. Draft creation establishes the resource boundary, intake questions collect higher-value steering data, and the generate route turns that into a full project artifact.
That staged model also keeps the public contract composable: simple callers can stop at draft creation, while richer products can layer on the questions and generate phases.
Routes
What this page actually points to
/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
Primary user request, learning goal, or topic for generation.
Optional typed context objects. Supported types today are `text`, `doc`, `pdf`, `quickhit`, `roadmap`, `quiz`, `exam`, `project`, and `vidbyte_project`.
High-level outcome the learner should ship or achieve.
Motivation, business reason, or learning importance steering.
Current learner level or baseline capability summary.
Desired depth or scope preference.
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.
/api/v1/projects/list
List projects owned by the authenticated API principal.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/sandbox/projects/list
Notes
Returns draft and generated project resources with public IDs only.
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`.
/api/v1/projects/get/{encrypted_id}
Fetch one project by encrypted public id.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/sandbox/projects/get/{encrypted_id}
Notes
This is the stable retrieval route once the project lifecycle is underway.
Request fields
Encrypted public identifier returned by a create or list route.
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`.
/api/v1/projects/questions
Generate intake questions for a draft project before full project generation.
Auth
API key via Authorization: Bearer or x-api-key
Maps to
/api/sandbox/generate_questions
Notes
Treat this as the steering phase between project draft creation and full project generation.
Request fields
Primary user request, learning goal, or topic for generation.
Encrypted public id returned by project create.
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 response returns generated intake questions and a questions-context block tied to the draft project.
/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
Project steering controls
These optional fields help shape the kind of project the learner should receive.
High-level outcome the learner should produce.
Why the project matters or what it should optimize for.
Current learner level or confidence summary.
Desired scope, ambition, or rigor.
How much scaffolding the learner wants.
Related pages
Roadmaps
Roadmaps turn a learning goal into a phased plan. The public API supports create, list, get, and module-specific retrieval, all using encrypted public ids.
Quizzes
The Quizzes API covers the full quiz lifecycle: create a quiz, batch-generate multiple quizzes, list and fetch saved quizzes, and progressively update an existing quiz by semantic action groups.
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.