---
title: Create Chat
description: Creates a new chat from a prompt. The request blocks until the model response is complete and returns the chat.
docs_index: /docs/llms.txt
lastUpdated: 2026-10-20
badge: "POST"
---

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

#### `POST/v2/chats`

> 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.create({
  message: 'Hello, world!',
})

console.log(result)
```

```bash
curl -X POST "https://api.v0.dev/v2/chats"   -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.create({
  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"   -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'` Model to use for the generation.
  - `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

- `chat: object`
  - `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.
- `usage: object` Model, token usage, and credit cost for the prompt.
  - `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.

---

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)