A Message is a single turn in the conversation attached to a project. User messages contain prompts; assistant messages contain the AI-generated response. Each assistant message may include a CodeFragment — the generated code and its live sandbox URL.
GET /api/messages Retrieve all messages for a project, ordered by updatedAt ascending (oldest first). Each message includes its associated CodeFragment if one exists.
Query parameters The ID of the project whose messages you want to retrieve. Minimum 3 characters.
Response Returns an array of Message objects with codeFragment included.
Unique message identifier (UUID).
The text content of the message.
Who authored the message. One of USER or ASSISTANT.
Message outcome. One of RESULT or ERROR.
Clerk user ID associated with the message.
Design screenshot URL attached to this message, or null.
The project this message belongs to.
ISO 8601 creation timestamp.
ISO 8601 last-updated timestamp.
The code artifact produced by an assistant message. Present only on ASSISTANT messages that completed successfully. Show CodeFragment properties
Unique fragment identifier (UUID).
ID of the parent message.
Public URL of the live E2B sandbox where the generated app is running.
E2B sandbox identifier. Used by the fragments API to write files directly.
Human-readable title for the fragment.
Map of relative file paths to their contents, e.g. { "app/page.tsx": "..." }.
Screenshot of the generated app, or null.
Structured design specification extracted from the uploaded screenshot, or null.
ISO 8601 creation timestamp.
ISO 8601 last-updated timestamp.
Example curl --request GET \ --url '/api/messages?projectId=a1b2c3d4-e5f6-7890-abcd-ef1234567890' \ --header 'Authorization: Bearer <session_token>'
[ { "id" : "msg_111" , "content" : "Build a to-do list app with a clean, minimal design" , "role" : "USER" , "type" : "RESULT" , "userId" : "user_abc123" , "imageUrl" : null , "projectId" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "createdAt" : "2024-04-05T12:00:00.000Z" , "updatedAt" : "2024-04-05T12:00:00.000Z" , "codeFragment" : null }, { "id" : "msg_222" , "content" : "Here is your to-do list app." , "role" : "ASSISTANT" , "type" : "RESULT" , "userId" : "user_abc123" , "imageUrl" : null , "projectId" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "createdAt" : "2024-04-05T12:00:45.000Z" , "updatedAt" : "2024-04-05T12:00:45.000Z" , "codeFragment" : { "id" : "frag_333" , "messageId" : "msg_222" , "sandboxUrl" : "https://sbx_xyz789.e2b.dev" , "sandboxId" : "sbx_xyz789" , "title" : "To-Do List App" , "files" : { "app/page.tsx" : "export default function Page() { ... }" }, "imageUrl" : null , "designSpec" : null , "createdAt" : "2024-04-05T12:00:45.000Z" , "updatedAt" : "2024-04-05T12:00:45.000Z" } } ]
POST /api/messages Send a follow-up prompt to a project. ForgeAI stores the message, then fires an Inngest event (code-agent/codeAgent.run) to continue AI code generation asynchronously.
Request body The follow-up prompt. Minimum 3 characters, maximum 1000 characters.
The ID of the project to send the message to. Minimum 3 characters.
URL of a design screenshot to include with this message. Pro only — requires the screenshot_upload feature flag.
Supplying imageUrl without a Pro subscription returns 403 Forbidden.
Response Returns the newly created Message object (the user turn, before AI generation completes).
Unique message identifier (UUID).
The prompt text as stored.
Always USER for messages created via this endpoint.
Always RESULT for messages created via this endpoint.
Clerk user ID of the sender.
The design screenshot URL, or null.
The project this message was sent to.
ISO 8601 creation timestamp.
ISO 8601 last-updated timestamp.
Example curl --request POST \ --url /api/messages \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <session_token>' \ --data '{ "message": "Add a dark mode toggle to the header", "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }'
{ "id" : "msg_444" , "content" : "Add a dark mode toggle to the header" , "role" : "USER" , "type" : "RESULT" , "userId" : "user_abc123" , "imageUrl" : null , "projectId" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "createdAt" : "2024-04-05T13:00:00.000Z" , "updatedAt" : "2024-04-05T13:00:00.000Z" }
The AI-generated response arrives asynchronously. Poll GET /api/messages?projectId=... to check for the new assistant message and its CodeFragment.
