Skip to main content
POST
Create a project

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
name
string | null

Display name. Defaults to 'Untitled project', or for a copy to 'Copy of {source}' (same kind), '{source} Template' (a project saved as a template) or the template's name without ' Template' (a project made from a template).

Maximum string length: 255
​
render_request
RenderRequest · object | null

Seed composition. An empty project is created when omitted.

​
source_project_id
string | null

Copy this project's head into version 1 of the new one: your own project or template, or a published template from GET /v1/templates. Element ids are kept. Not together with render_request.

Maximum string length: 64
​
kind
enum<string>
default:project

template creates a template (a project used as a copy source).

Available options:
project,
template
​
author
enum<string>
default:user

Who is creating this project, for version provenance — user or agent. Name the values here because MCP advertises this body as an opaque object: a caller sees the key but not its enum, so anything else is learned only from the 422.

Available options:
user,
agent

Response

Successful Response

A freshly created project, plus the advisory lint of its seed composition.

Returned only by POST /v1/projects. A subclass rather than two more fields on :class:ProjectOut, because ProjectOut also backs GET /v1/projects, which would then have to either carry permanently-null fields or lint every project on the page.

​
id
string
required

Unique project id.

Example:

"proj_01J8QR2K5VKDGN2T4FBM3CZYX7"

​
name
string
required

Display name.

Example:

"Launch teaser"

​
version
integer
required

Head version. Bumped on every applied ops batch.

Example:

3

​
workspace_id
string
required

Owning workspace id.

​
editor_url
string
required

Open this project in the authenticated console.

​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required
​
summary
ProjectSummary · object
required

Compact, always-present view of the head composition.

​
ok
boolean
required

Advisory — the project was still created and stored at version 1. False means the seed composition has error-severity findings; a project is allowed to hold an invalid head while you repair it with ops.

Example:

true

​
kind
enum<string>
default:project

project, or template: a project used as a copy source.

Available options:
project,
template
​
source_project_id
string | null

The project or template this one was copied from.

​
source_kind
enum<string> | null

What the source was: project (a duplicate), template (one of your templates) or public_template (a published template from the gallery).

Available options:
project,
template,
public_template
​
thumbnail_url
string | null

A poster image of the head; null until one is generated.

​
thumbnail_version
integer | null

The head version the thumbnail shows. It is stale while this is below version.

​
render_request
RenderRequest · object | null

The full head composition. Present only when requested with view=full.

​
direction
ProjectDirection · object | null

The direction the user accepted for this project, with its computed state; null when none is recorded. Follow it when editing. Set or clear it with the set_direction op.

​
violations
Violation · object[]

Advisory — the project was still created and stored at version 1. The same findings POST /v1/projects/{id}/ops returns after an edit, so you can see what needs repairing without a round trip.Truncated to the first 36 findings (errors first) on very large compositions, with a VIOLATIONS_TRUNCATED marker carrying the full count; the free dry run is never truncated.