Create Chat | v0 Docs

POST/v1/chats

Usage

TypeScript Example

import { v0 } from 'v0-sdk'

const result = await v0.chats.create({
  system: 'You are an expert coder',
  message: 'Create a landing page for a new product',
  projectId: 'proj_123',
})

console.log(result)

API Signature

Request

Body

message: string

Creates a new chat using a user message, optional system context, and model configuration. Useful for prompting the model within the scope of a specific project.

attachments?: object[]

A list of files or assets to be included in the conversation context. Useful when the chat or task requires referencing documents, images, or other resources.

url: string

system?: string

Provides system-level context or background for the chat. This is typically used to specify frameworks, tools, or development environments relevant to the task.

chatPrivacy?: 'public' | 'private' | 'team-edit' | 'team' | 'unlisted'

Determines the privacy setting of the chat. This can control whether the chat is visible only to the user, to team members, or is public.

projectId?: string

Associates the chat with a specific project in your workspace. Helps organize and group related chats under a common project context.

modelConfiguration?: object

Settings that control how the model behaves in the chat.

modelId?: 'v0-1.5-sm' | 'v0-1.5-md' | 'v0-1.5-lg' | 'v0-gpt-5'

deprecated

Deprecated Model ID field preserved for backward compatibility.

imageGenerations?: boolean

Enables image generations to generate up to 5 images per version.

thinking?: boolean

Enables thinking to generate a response in multiple steps.

responseMode?: 'sync' | 'async' | 'experimental_stream'

Controls how the response is delivered.

"sync": The response is returned immediately with the HTTP request.
"async": Returns a message placeholder immediately; use getById to poll for completion status and final output.
"experimental_stream": Returns content parts as Server-Sent Events for real-time streaming.

designSystemId?: stringnull

The ID of a design system to apply to this chat. Design systems provide consistent styling and components for generated UI.

Response

id: string

A unique identifier for the chat.

object: 'chat'

Fixed value identifying this object as a chat.

shareable: boolean

Indicates whether the chat can be shared via public link.

privacy: 'public' | 'private' | 'team' | 'team-edit' | 'unlisted'

Defines the visibility of the chat—private, team-only, or public.

name?: string

An optional name assigned to the chat by the user.

title?: string

deprecated

Deprecated title field preserved for backward compatibility.

createdAt: string

The ISO timestamp representing when the chat was created.

updatedAt?: string

The ISO timestamp of the last update to the chat.

favorite: boolean

Indicates whether the chat is marked as a favorite.

authorId: string

The ID of the user who created the chat.

projectId?: string

Optional ID of the v0 project associated with this chat.

webUrl: string

Web URL to view this chat in the browser.

apiUrl: string

API URL to access this chat via the API.

latestVersion?: object

Full details of the most recent generated version, if available.

id: string

A unique identifier for the version.

object: 'version'

Fixed value identifying this object as a version.

status: 'pending' | 'completed' | 'failed'

The current status of the version generation process.

demoUrl?: string

Optional URL for previewing the generated output.

createdAt: string

The date and time when the version was created, in ISO 8601 format.

updatedAt?: string

The date and time when the version was last updated, in ISO 8601 format.

files: object[]

A list of files that were generated or included in this version.

url: string

deprecated

The canonical URL to access this chat.

messages: object[]

All messages exchanged in the chat, including user and assistant entries.

id: string

A unique identifier for the message.

object: 'message'

Fixed value identifying this object as a message.

content: string

The main text content of the message.

experimental_content?: string[]

The parsed content of the message as an array structure containing AST nodes. This is an experimental field that may change.

createdAt: string

The ISO timestamp representing when the message was created.

updatedAt?: string

The ISO timestamp representing when the message was last updated.

Indicates the format or category of the message, such as plain text or code.

role: 'user' | 'assistant'

Specifies whether the message was sent by the user or the assistant.

The reason why the message generation finished.

apiUrl: string

API URL to access this message via the API.

parentId?: stringnull

The ID of the parent message.

files?: object[]

Optional array of files associated with the chat context.

lang: string

Programming language used in the file (e.g., JavaScript, Python).

meta: object

A key-value map of metadata associated with the file (e.g., path, type).

source: string

The origin or identifier of the file source (e.g., path or upload label).

demo?: string

deprecated

Deprecated demo URL used for previewing the chat result.

text: string

The main user prompt or instruction that started the chat.

modelConfiguration?: object

The configuration used to generate responses in this chat.

modelId?: 'v0-1.5-sm' | 'v0-1.5-md' | 'v0-1.5-lg' | 'v0-gpt-5'

deprecated

Deprecated Model ID field preserved for backward compatibility.

imageGenerations?: boolean

Enables image generations to generate up to 5 images per version.

thinking?: boolean

Enables thinking to generate a response in multiple steps.

permissions: object

write: boolean

If true, the user has write access to the chat.