Build Stream

POST /api/v1/vibe/stream is the primary endpoint. It creates or continues a build session and returns an SSE (Server-Sent Events) stream of progress events.

Request

POST /api/v1/vibe/stream
Authorization: Bearer <token>
Content-Type: application/json
Accept: text/event-stream

Create a new project

{
  "prompt": "Build a task management app with Supabase auth and team-based boards",
  "app_platform": "web"
}

Continue an existing project

{
  "project_id": "abc123",
  "prompt": "Add due dates and email notifications to tasks"
}

Fields

Field names are snake_case. The full schema is VibeRequestSchema in src/routes/vibe.ts.

Field	Type	Required	Description
`prompt`	string	always	Natural language description of what to build. Trimmed; must be non-empty even when continuing a project
`project_id`	string	subsequent turns	Existing project to continue. Omit to create one
`app_platform`	`"web"` \| `"mobile"`	first turn	Which build target to scaffold (default: `"web"`)
`mode`	`"build"` \| `"chat"` \| `"plan"` \| `"agent"` \| `"discuss"`	no	Turn mode (default: `"build"`)
`model` / `provider`	string	no	Override the model preset for this turn
`images`	array	no	`{ data, mimeType, name? }` — images carried by the turn
`documents`	array	no	`{ data, mimeType, name }` — up to 10 files carried by the turn, 20 MB of base64 each
`interrupt`	boolean	no	Kill the in-flight turn and run this message instead, rather than queueing behind it
`auto_fix`	boolean	no	Let the agent self-heal build errors without asking

Answering a question from the agent

Answers do not go to this endpoint. When the stream emits ask_user_question, reply on its own endpoint:

POST /api/v1/vibe/answer

{
  "project_id": "abc123",
  "question_id": "q_xyz",
  "answers": { "auth_provider": "Supabase" }
}

All three fields are required. Plan approvals are a separate endpoint again — POST /api/v1/vibe/plan/approve with { project_id, approved, feedback?, edited_plan? }.

Response

The response is an SSE stream (text/event-stream). Each event is a JSON object with a type field.

Event types

Each event’s type is a member of StreamChunkType (src/types/index.ts). The common ones:

Type	Description
`status`	Build progress update
`text`	Streaming model text
`tool_start`	Agent invoked a tool
`tool_end`	Tool returned a result
`file`	A file was written in the sandbox
`file_streaming_chunk`	A file write in progress, chunk by chunk
`preview_url`	Live preview URL is ready
`ask_user_question`	Agent is asking the user a question
`error`	Build encountered an error
`complete`	Build completed successfully

The V1 stream then closes with a literal data: [DONE]\n\n. POST /api/v1/vibe/stream_v2 carries the same type on the SSE event: line and closes with event: done instead.

Error event

{
  "type": "error",
  "data": {
    "message": "You're out of credits for this plan.",
    "code": "OUT_OF_CREDITS",
    "error_ref": "3F9A2C11"
  }
}

Completion event

{
  "type": "complete",
  "data": {
    "project_id": "abc123",
    "preview_url": "https://abc123.vibelyagent.com",
    "files_created": 42,
    "tool_calls": 118,
    "tokens_in": 91204,
    "tokens_out": 13877
  }
}

Non-stream responses

If the backend can’t open a stream (queued, or answering a pending question), it returns a JSON response instead:

{
  "code": "message_queued",
  "hint": "Build queued — reconnect to receive the stream"
}

Status 202 with code: "message_queued" means the build was accepted and will start when a worker is available. Reconnect to the same endpoint to receive the stream.

Build engine

MCP client

API

Request

Create a new project

Continue an existing project

Fields

Answering a question from the agent

Response

Event types

Error event

Completion event

Non-stream responses

​Request

​Create a new project

​Continue an existing project

​Fields

​Answering a question from the agent

​Response

​Event types

​Error event

​Completion event

​Non-stream responses

Request

Create a new project

Continue an existing project

Fields

Answering a question from the agent

Response

Event types

Error event

Completion event

Non-stream responses