Create Chat | v0 Docs

POST /chats

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',
  modelConfiguration: {
    modelId: 'v0-1.5-sm',
    imageGenerations: false,
    thinking: false,
  },
})

console.log(result)

POST /chats

curl -X POST https://api.v0.dev/chats \
  -H "Authorization: Bearer $V0_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "system": "You are an expert coder",
    "message": "Create a landing page for a new product",
    "modelConfiguration": {
      "modelId": "v0-1.5-sm",
      "imageGenerations": false,
      "thinking": false
    }
  }'

Parameters

Request Body

message string Required

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.

Array items:

url string Required

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 enum

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.

Possible values:

public
private
team-edit
team
unlisted

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 enum Required

Possible values:

v0-1.5-sm
v0-1.5-md
v0-1.5-lg

imageGenerations boolean

thinking boolean

responseMode enum

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.

Possible values:

sync
async

Response

Response Body

id string Required

A unique identifier for the chat.

object string Required

Fixed value identifying this object as a chat.

shareable boolean Required

Indicates whether the chat can be shared via public link.

privacy enum Required

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

Possible values:

public
private
team
team-edit
unlisted

name string

An optional name assigned to the chat by the user.

title string

Deprecated title field preserved for backward compatibility.

createdAt string Required

The ISO timestamp representing when the chat was created.

updatedAt string

The ISO timestamp of the last update to the chat.

favorite boolean Required

Indicates whether the chat is marked as a favorite.

authorId string Required

The ID of the user who created the chat.

projectId string

Optional ID of the v0 project associated with this chat.

webUrl string Required

Web URL to view this chat in the browser.

apiUrl string Required

API URL to access this chat via the API.

latestVersion object

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

id string Required

A unique identifier for the version.

object string Required

Fixed value identifying this object as a version.

status enum Required

The current status of the version generation process.

Possible values:

pending
completed
failed

demoUrl string

Optional URL for previewing the generated output.

createdAt string Required

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[] Required

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

Array items:

object string Required

Fixed value identifying this object as a file.

name string Required

The name of the file, including its extension.

content string Required

The full contents of the file as a raw string.

locked boolean Required

Whether the file is locked to prevent AI from overwriting it during new version generation.

url string Required

The canonical URL to access this chat.

messages object[] Required

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

Array items:

id string Required

A unique identifier for the message.

object string Required

Fixed value identifying this object as a message.

content string Required

The main text content of the message.

createdAt string Required

The ISO timestamp representing when the message was created.

updatedAt string

The ISO timestamp representing when the message was last updated.

type enum Required

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

Possible values:

message
forked-block
forked-chat
open-in-v0
refinement
added-environment-variables
added-integration
deleted-file
moved-file
renamed-file
edited-file
replace-src
reverted-block
fix-with-v0
auto-fix-with-v0
sync-git

role enum Required

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

Possible values:

user
assistant

apiUrl string Required

API URL to access this message via the API.

files object[]

Optional array of files associated with the chat context.

Array items:

lang string Required

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

meta object Required

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

source string Required

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

demo string

Deprecated demo URL used for previewing the chat result.

text string Required

The main user prompt or instruction that started the chat.

modelConfiguration object Required

The configuration used to generate responses in this chat.

modelId enum Required

Possible values:

v0-1.5-sm
v0-1.5-md
v0-1.5-lg

imageGenerations boolean

thinking boolean