---
title: Create Chat (Async)
description: "Creates a new chat with a user message and processes it in the background. Returns immediately with the chat ID and message ID. Poll for the assistant message by ID until `finishReason` is non-null."
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 processes it in the background. Returns immediately with the chat ID and message ID. Poll for the assistant message by ID until `finishReason` is non-null.

#### `POST /v2/chats/async`

> Use `attachments` to provide supporting context such as documents, images, or a few reference files. Each attachment's `url` can be a public HTTPS URL or a base64-encoded data URI.

## Usage

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

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

console.log(result)
```

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

### With inline attachment content

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

const content = Buffer.from('Use brand color #0070f3.').toString('base64')
const result = await v0.chats.createAsync({
  message: 'Use the attached requirements when building the application.',
  attachments: [{ url: 'data:text/plain;base64,' + content }],
})

console.log(result)
```

```bash
curl -X POST "https://api.v0.dev/v2/chats/async"   -H "Authorization: Bearer $V0_API_KEY"   -H "Content-Type: application/json"   -d '{
    "message": "Use the attached requirements when building the application.",
    "attachments": [
      {
        "url": "data:text/plain;base64,VXNlIGJyYW5kIGNvbG9yICMwMDcwZjMu"
      }
    ]
  }'
```

## 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

- `chatId: string` Unique chat identifier.
- `messageId: string` ID of the assistant message that will receive the response. Poll this message by ID and check its finishReason field to detect completion.

---

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)