---
title: "Create Chat"
method: POST
path: "/chats"
tags: ["chats"]
---

# Create Chat

`POST /chats`

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.

## Request body

- object
  - `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.
    - `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` '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 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` string, nullable — The ID of a design system to apply to this chat. Design systems provide consistent styling and components for generated UI.

## Response `200`

Success

- ChatDetail — Detailed representation of a chat, including its messages, files, versions, and model configuration.
  - `id` string, required — A unique identifier for the chat.
  - `object` 'chat', required — Fixed value identifying this object as a chat.
  - `shareable` boolean, required — Indicates whether the chat can be shared via public link.
  - `privacy` 'public' | 'private' | 'team' | 'team-edit' | 'unlisted', required — 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 title field preserved for backward compatibility.
  - `createdAt` string, date-time, 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` 'version', required — Fixed value identifying this object as a version.
    - `status` 'pending' | 'completed' | 'failed', required — The current status of the version generation process.
    - `demoUrl` string — Optional URL for previewing the generated output.
    - `createdAt` string, date-time, required — The date and time when the version was created, in ISO 8601 format.
    - `updatedAt` string, date-time — 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.
      - `object` 'file', 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.
    - `screenshotUrl` string — URL to retrieve a screenshot of this version.
  - `url` string, required — The canonical URL to access this chat.
  - `messages` object[], required — All messages exchanged in the chat, including user and assistant entries.
    - `id` string, required — A unique identifier for the message.
    - `object` 'message', required — Fixed value identifying this object as a message.
    - `content` string, required — The main text content of the message.
    - `experimental_content` union[] — The parsed content of the message as an array structure containing AST nodes. This is an experimental field that may change.
      - union
        - unknown[] — AST content section containing parsed markdown/MDX nodes
          - unknown
        - unknown[] — Metadata section containing title and other properties
          - unknown
    - `createdAt` string, required — The ISO timestamp representing when the message was created.
    - `updatedAt` string, date-time — The ISO timestamp representing when the message was last updated.
    - `type` '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', required — Indicates the format or category of the message, such as plain text or code.
    - `role` 'user' | 'assistant', required — Specifies whether the message was sent by the user or the assistant.
    - `finishReason` 'stop' | 'length' | 'content-filter' | 'tool-calls' | 'error' | 'other' | 'unknown' — The reason why the message generation finished.
    - `apiUrl` string, required — API URL to access this message via the API.
    - `parentId` string, nullable — The ID of the parent message.
  - `files` object[] — Optional array of files associated with the chat context.
    - `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 — 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 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, required
    - `write` boolean, required — If true, the user has write access to the chat.

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — Conflict
- `413` — Payload Too Large
- `422` — Unprocessable Entity
- `429` — Too Many Requests
- `500` — Internal Server Error

## Changes

- **2025-09-24** `fd6d8c3bee8a` — 1 info
  - added the optional property `latestVersion/screenshotUrl` to the response with the `200` status
- **2025-09-17** `71c04d617e58` — 2 info
  - the `modelId` request property default value `v0-1.5-md` was added
  - the `modelId` response's property default value `v0-1.5-md` was added for the status `200`
- **2025-09-12** `e9f83fb57a16` — 1 breaking, 5 info
  - the response property `modelConfiguration/modelId` became optional for the status `200`
  - the request property `modelConfiguration/modelId` became optional
  - request property `modelConfiguration/modelId` deprecated
  - added the optional property `messages/items/parentId` to the response with the `200` status
  - …2 more
- **2025-08-29** `90f1f1e3f7eb` — 1 info
  - added the new `experimental_stream` enum value to the request property `responseMode`
- **2025-08-24** `3521652a43a7` — 11 breaking, 12 warning, 25 info
  - the request property `modelConfiguration/modelId` became required
  - removed the enum value `experimental_stream` of the request property `responseMode`
  - removed the enum value `v0-auto` of the request property `modelConfiguration/modelId`
  - removed the enum value `v0-max` of the request property `modelConfiguration/modelId`
  - …44 more

[Change history](https://skmtc.dev/vercel/apis/v0-platform-api-beta/changes/chats/post.md)

---

[API](https://skmtc.dev/vercel/apis/v0-platform-api-beta.md) · [All operations](https://skmtc.dev/vercel/apis/v0-platform-api-beta/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/vercel/v0-platform-api-beta/revisions/fd6d8c3bee8a/schema)