Skip to main content
A Project is the top-level container for an AI-generated web application. Creating a project triggers the code-generation pipeline; subsequent prompts are sent as Messages.

​
POST /api/projects

Create a new project. ForgeAI stores the initial prompt as the first message, then fires an Inngest event (code-agent/codeAgent.run) to kick off AI code generation asynchronously.

​
Request body

​
message
string
required
The prompt describing the web app you want to build. Minimum 3 characters, maximum 1000 characters.
​
imageUrl
string
URL of a design screenshot to use as a visual reference. Pro only — requires the screenshot_upload feature flag. Omit this field if you do not have a Pro subscription.
Supplying imageUrl without a Pro subscription returns 403 Forbidden.

​
Response

Returns the newly created Project object.
​
id
string
required
Unique project identifier (UUID).
​
name
string
required
Auto-generated project name in the format Project-<timestamp>.
​
userId
string
required
Clerk user ID of the project owner.
​
sandboxId
string
E2B sandbox ID once the code-generation pipeline assigns one. null until generation completes.
​
imageUrl
string
The design screenshot URL, if one was provided.
​
createdAt
string
required
ISO 8601 timestamp of when the project was created.
​
updatedAt
string
required
ISO 8601 timestamp of the last update.

​
Example

curl --request POST \
  --url /api/projects \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <session_token>' \
  --data '{
    "message": "Build a to-do list app with a clean, minimal design"
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Project-1712345678000",
  "userId": "user_abc123",
  "sandboxId": null,
  "imageUrl": null,
  "createdAt": "2024-04-05T12:00:00.000Z",
  "updatedAt": "2024-04-05T12:00:00.000Z"
}

​
GET /api/projects

List all projects belonging to the authenticated user, ordered by most recently updated.

​
Query parameters

None.

​
Response

Returns an array of Project objects, ordered by updatedAt descending.
​
id
string
required
Unique project identifier (UUID).
​
name
string
required
Project name.
​
userId
string
required
Clerk user ID of the project owner.
​
sandboxId
string
E2B sandbox ID, or null if generation has not yet completed.
​
imageUrl
string
Design screenshot URL, or null.
​
createdAt
string
required
ISO 8601 creation timestamp.
​
updatedAt
string
required
ISO 8601 last-updated timestamp.

​
Example

curl --request GET \
  --url /api/projects \
  --header 'Authorization: Bearer <session_token>'

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Project-1712345678000",
    "userId": "user_abc123",
    "sandboxId": "sbx_xyz789",
    "imageUrl": null,
    "createdAt": "2024-04-05T12:00:00.000Z",
    "updatedAt": "2024-04-05T14:30:00.000Z"
  }
]

Build docs developers (and LLMs) love

Get started for freeTalk to us