---
title: Create Chat (Streaming)
description: "Creates a new chat with a user message and returns a Server-Sent Events stream. Events include initial chat state, title deltas, content chunk deltas, and final chat state. The response is `text/event-stream`; each event is `data: <JSON>\\n\\n` where the JSON conforms to ChatStreamEvent. If the stream disconnects before the final event, reconnect with `POST /chats/{chatId}/resume` instead of sending the message again."
docs_index: /docs/llms.txt
lastUpdated: 2026-10-23
badge: "POST"
---

> For an index of all documentation, see [/docs/llms.txt](/docs/llms.txt).

Creates a new chat with a user message and returns a Server-Sent Events stream. Events include initial chat state, title deltas, content chunk deltas, and final chat state. The response is `text/event-stream`; each event is `data: <JSON>\n\n` where the JSON conforms to ChatStreamEvent. If the stream disconnects before the final event, reconnect with `POST /chats/{chatId}/resume` instead of sending the message again.

#### `POST /v2/chats/stream`

## Usage

```typescript
import { v0 } from 'v0'

const result = await v0.chats.createStream({
  message: 'Hello, world!',
})

console.log(result)
```

```bash
curl -X POST "https://api.v0.dev/v2/chats/stream"   -H "Authorization: Bearer $V0_API_KEY"   -H "Content-Type: application/json"   -d '{"message":"Hello, world!"}'
```

## API Signature

### Request

#### Request Body

- `message: string` The prompt or instruction to send to the model.
  - **Minimum length:** 1
- `systemPrompt?: string` System-level context for the chat, such as frameworks or development environment details.
- `modelConfiguration?: object` Overrides for the model behavior.
  - `modelId: 'v0-mini' | 'v0-pro' | 'v0-max' | 'v0-max-fast' | string` Model to use for the generation. Use a v0 model ID, or an [AI Gateway](https://vercel.com/ai-gateway/models) model ID in `creator/model` format. Gateway models must support tool calling and Zero Data Retention, and are subject to team model policy; unsupported IDs are rejected.
  - `imageGenerations: boolean` Enables image generations to generate up to 5 images per version.
- `attachments?: (object | object)[]` Files or assets to include with the message. Provide either a URL or data URI, or inline UTF-8 text content.
- `mcpServerIds?: string[]` MCP server IDs to enable. When omitted, uses default enabled servers.
- `skills?: ('remote' | 'memory' | 'project')[]` Skills to force-attach to the chat. Supports skills.sh (`remote`), user/team memory (`memory`), and project (`project`) skills. Maximum 3.
  - **Maximum items:** 3
  - **remote**
    - `type: 'remote'` Discriminator: a skills.sh skill.
    - `id: string` Skill ID from skills.sh.
  - **memory**
    - `type: 'memory'` Discriminator: a user- or team-scoped memory skill.
    - `scope: 'user' | 'team'` Whether the skill lives in user or team memory.
    - `skillName: string` Name of the memory skill to attach.
  - **project**
    - `type: 'project'` Discriminator: a skill defined in the project repo.
    - `skillName: string` Name of the project skill to attach.
- `privacy?: 'public' | 'private' | 'team' | 'team-edit' | 'unlisted'` Visibility setting for the new chat.
- `title?: string` Title for the new chat.
- `metadata?: Record<string, string>` Arbitrary key-value data to attach to the chat.
- `credentialAccess?: object` Credentials the chat's sandbox may use. Not supported for Vercel OIDC principals.
  - `sharedNpm?: boolean` Let the chat's sandbox install private packages with the team's shared npm credentials (`NPM_RC` / `NPM_TOKEN`). Defaults to `false`.
  - `vercel?: boolean` Let the chat's sandbox use the requesting user's Vercel credentials instead of a project-only token. Defaults to `false`.
  - `github?: boolean` Let the chat's sandbox use the requesting user's GitHub credentials. Defaults to `false`.

### Response (Stream)

The response is a `text/event-stream`. Each event is `data: <JSON>\n\n` where the JSON conforms to one of the following event types:

- `event: 'chat' | 'chat.title' | 'message.parts.chunk' | 'message.usage' | 'error'` A single Server-Sent Events payload emitted by streaming chat endpoints. Each SSE event is `data: <JSON>\n\n` where the JSON conforms to one of the union members.
  - **chat** Initial and final chat-state event. Emitted once at stream open with the freshly-created chat, and once at stream close with the chat including the completed assistant message.
    - `id: string` Unique chat identifier.
    - `title?: string` Chat title, if generated.
    - `privacy: 'public' | 'private' | 'team' | 'team-edit' | 'unlisted'` Visibility setting of the chat.
    - `createdAt: string` ISO timestamp of when the chat was created.
    - `updatedAt?: string` ISO timestamp of when the chat was last updated.
    - `authorId: string` ID of the user who created the chat.
    - `vercelProjectId?: string` Associated Vercel project ID, if any.
    - `metadata: Record<string, string>` User-defined key-value metadata.
    - `writePermission: boolean` Whether the caller has write access to this chat.
    - `object: 'chat'` Discriminator: a chat-state snapshot.
  - **chat.title** Emitted when the chat title is (re)generated.
    - `id: string` Chat ID.
    - `object: 'chat.title'` Discriminator.
    - `delta: string` Full title string at this point in the stream.
  - **message.parts.chunk** Incremental update to the assistant message content.
    - `id: string` Assistant message ID.
    - `object: 'message.parts.chunk'` Discriminator.
    - `delta: unknown` jsondiffpatch delta to apply against the running public `Message.parts` array. Apply each delta in order to reconstruct the complete current parts snapshot.
  - **message.usage** Final model, token usage, and credit cost for the assistant message produced by this stream. Emitted once after the message finishes generating, before the closing state event.
    - `id: string` Assistant message ID this usage applies to.
    - `object: 'message.usage'` Discriminator.
    - `usage: object` Model identifier, token usage, and credit cost. Token and credit values are zero on user messages and on assistant messages that have not generated tokens.
      - `model: string | null` Model identifier used for the assistant message, or null when not applicable or unavailable.
      - `tokens: object` Token counts for this message.
        - `input: number` Prompt input value (non-cached).
        - `output: number` Completion output value.
        - `cacheRead: number` Cache-read input value.
        - `cacheWrite: number` Cache-write input value.
        - `total: number` Sum of input, output, cacheRead, and cacheWrite.
      - `creditsCost: object` Credit cost for this message.
        - `input: number` Prompt input value (non-cached).
        - `output: number` Completion output value.
        - `cacheRead: number` Cache-read input value.
        - `cacheWrite: number` Cache-write input value.
        - `total: number` Sum of input, output, cacheRead, and cacheWrite.
  - **error** Emitted when a stream error occurs after the SSE response begins.
    - `id: string` Assistant message ID or chat ID, depending on what is in scope when the error is raised.
    - `object: 'error'` Discriminator.
    - `message: string` Human-readable stream error message.
    - `code?: string` Optional machine-readable stream error code.

---

For a semantic overview of all documentation, see [/docs/sitemap.md](/docs/sitemap.md)

For an index of all available documentation, see [/docs/llms.txt](/docs/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/docs/agents.md](/docs/agents.md)