Projects API
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.
Projects are staged because they depend more heavily on learner context
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.
Model the family as draft first, enrichment second, generation last
Use `/create` to establish the draft project resource.
Use `/questions` if you want extra learner-specific intake prompts.
Use `/generate` once you have the draft `project_id` and optional answers.
Use `/list` and `/get` to surface saved project resources later.
Projects work best when the brief is grounded in the learner's real goal
Project goal
Anchor the artifact around what the learner should actually build or ship.
Current level
Current level helps the project stay appropriately scoped instead of drifting too easy or too ambitious.
Guidance preference
Use depth and guidance controls to decide whether the project should feel scaffolded or open-ended.
Endpoints
/create
/api/v1/projects/create
Create the initial project draft and establish the public project resource boundary. This is the first step in the staged Projects API lifecycle.
/get
/api/v1/projects/get/{encrypted_id}
Fetch one project by encrypted public id. Use this route to rehydrate the current project state after draft creation or downstream generation steps.
/list
/api/v1/projects/list
List the projects owned by the authenticated principal. This route is useful when your application needs to browse or reconcile the project inventory for an account.
/questions
/api/v1/projects/questions
Fetch the intake questions associated with a project draft. This lets your application gather the extra learner context Vidbyte uses to improve the generated project output.
/generate
/api/v1/projects/generate
Generate the full project artifact after the draft and optional intake phases. This route is the final generation step in the staged Projects API lifecycle.