> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibely.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Build Stream

> POST /api/v1/vibe/stream — build web and mobile apps

`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.

<Frame>
  <img src="https://cdn.vibely.sh/doc/v1/api-reference-vibe-stream.webp" alt="Build stream: request and events" width="1200" height="675" />
</Frame>

## Request

```http theme={"system"}
POST /api/v1/vibe/stream
Authorization: Bearer <token>
Content-Type: application/json
Accept: text/event-stream
```

### Create a new project

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

### Continue an existing project

```json theme={"system"}
{
  "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:

```http theme={"system"}
POST /api/v1/vibe/answer
```

```json theme={"system"}
{
  "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

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

### Completion event

```json theme={"system"}
{
  "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:

```json theme={"system"}
{
  "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.


## Related topics

- [Start a build from outside Vibely](/guides/build-from-chat.md)
- [Streaming](/reference/engine/streaming.md)
- [API Overview](/api-reference/overview.md)
- [Agent Loop](/reference/engine/agent-loop.md)
- [Build Mode Overview](/reference/engine/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.