---
title: Create Chat
description: Creates a new chat from a prompt, zip archive, or GitHub repository. Prompt chats block until the model response is complete and return the chat.
product: Platform API
type: reference
prerequisites:
  - /docs/api/platform/quickstart
---

# Create Chat



<EndpointDisplay method="post" path="/chats" versionPrefix="/v2" />

## Usage [#usage]

<CustomCodeBlock languages="['TypeScript', 'cURL']" defaultLanguage="TypeScript">
  <CodeVariant
    language="TypeScript"
    title="TypeScript Example"
    code="`import { v0 } from 'v0-sdk'

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

console.log(result)`"
  />

  <CodeVariant
    language="cURL"
    title="cURL Example"
    code="`curl -X POST &#x22;https://api.v0.dev/api/v2/chats&#x22; \
  -H &#x22;Authorization: Bearer $V0_API_KEY&#x22; \
  -H &#x22;Content-Type: application/json&#x22; \
  -d '{&#x22;message&#x22;:&#x22;Hello, world!&#x22;,&#x22;type&#x22;:&#x22;prompt&#x22;}'`"
  />
</CustomCodeBlock>

### From GitHub Repository [#from-github-repository]

<CustomCodeBlock languages="['TypeScript', 'cURL']" defaultLanguage="TypeScript">
  <CodeVariant
    language="TypeScript"
    title="TypeScript Example"
    code="`import { v0 } from 'v0-sdk'

const result = await v0.chats.create({
  type: 'repo',
  repo: {
    url: 'https://github.com/vercel/next.js',
    branch: 'canary',
  },
  title: 'Analyze Next.js repo',
})

console.log(result)`"
  />

  <CodeVariant
    language="cURL"
    title="cURL Example"
    code="`curl -X POST &#x22;https://api.v0.dev/api/v2/chats&#x22; \
  -H &#x22;Authorization: Bearer $V0_API_KEY&#x22; \
  -H &#x22;Content-Type: application/json&#x22; \
  -d '{
    &#x22;type&#x22;: &#x22;repo&#x22;,
    &#x22;repo&#x22;: {
      &#x22;url&#x22;: &#x22;https://github.com/vercel/next.js&#x22;,
      &#x22;branch&#x22;: &#x22;canary&#x22;
    },
    &#x22;title&#x22;: &#x22;Analyze Next.js repo&#x22;
  }'`"
  />
</CustomCodeBlock>

## API Signature [#api-signature]

### Request [#request]

#### Request Body [#request-body]

<APISignature
  parameters="[
  {
    &#x22;name&#x22;: &#x22;body&#x22;,
    &#x22;type&#x22;: &#x22;'prompt' | 'zip' | 'repo'&#x22;,
    &#x22;required&#x22;: true,
    &#x22;description&#x22;: &#x22;Request body. Set `type` to select the initialization method.&#x22;,
    &#x22;deprecated&#x22;: false,
    &#x22;variants&#x22;: [
      {
        &#x22;name&#x22;: &#x22;prompt&#x22;,
        &#x22;description&#x22;: &#x22;Initialize the chat by sending a prompt to the model.&#x22;,
        &#x22;properties&#x22;: [
          {
            &#x22;name&#x22;: &#x22;message&#x22;,
            &#x22;type&#x22;: &#x22;string&#x22;,
            &#x22;required&#x22;: true,
            &#x22;description&#x22;: &#x22;The prompt or instruction to send to the model.&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;systemPrompt&#x22;,
            &#x22;type&#x22;: &#x22;string&#x22;,
            &#x22;required&#x22;: false,
            &#x22;description&#x22;: &#x22;System-level context for the chat, such as frameworks or development environment details.&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;modelConfiguration&#x22;,
            &#x22;type&#x22;: &#x22;object&#x22;,
            &#x22;required&#x22;: false,
            &#x22;description&#x22;: &#x22;Overrides for the model behavior.&#x22;,
            &#x22;deprecated&#x22;: false,
            &#x22;properties&#x22;: [
              {
                &#x22;name&#x22;: &#x22;modelId&#x22;,
                &#x22;type&#x22;: &#x22;'v0-auto' | 'v0-mini' | 'v0-pro' | 'v0-max' | 'v0-max-fast'&#x22;,
                &#x22;required&#x22;: true,
                &#x22;description&#x22;: &#x22;Model to use for the generation.&#x22;,
                &#x22;deprecated&#x22;: false
              },
              {
                &#x22;name&#x22;: &#x22;imageGenerations&#x22;,
                &#x22;type&#x22;: &#x22;boolean&#x22;,
                &#x22;required&#x22;: true,
                &#x22;description&#x22;: &#x22;Enables image generations to generate up to 5 images per version.&#x22;,
                &#x22;deprecated&#x22;: false
              }
            ]
          },
          {
            &#x22;name&#x22;: &#x22;attachments&#x22;,
            &#x22;type&#x22;: &#x22;object[]&#x22;,
            &#x22;required&#x22;: false,
            &#x22;description&#x22;: &#x22;Files or assets to include with the message.&#x22;,
            &#x22;deprecated&#x22;: false,
            &#x22;arrayItems&#x22;: {
              &#x22;name&#x22;: &#x22;item&#x22;,
              &#x22;type&#x22;: &#x22;object&#x22;,
              &#x22;required&#x22;: true,
              &#x22;description&#x22;: &#x22;&#x22;,
              &#x22;deprecated&#x22;: false,
              &#x22;properties&#x22;: [
                {
                  &#x22;name&#x22;: &#x22;url&#x22;,
                  &#x22;type&#x22;: &#x22;string&#x22;,
                  &#x22;required&#x22;: true,
                  &#x22;description&#x22;: &#x22;URL of the attachment.&#x22;,
                  &#x22;deprecated&#x22;: false
                }
              ]
            }
          },
          {
            &#x22;name&#x22;: &#x22;mcpServerIds&#x22;,
            &#x22;type&#x22;: &#x22;string[]&#x22;,
            &#x22;required&#x22;: false,
            &#x22;description&#x22;: &#x22;MCP server IDs to enable. When omitted, uses default enabled servers.&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;skillIds&#x22;,
            &#x22;type&#x22;: &#x22;string[]&#x22;,
            &#x22;required&#x22;: false,
            &#x22;description&#x22;: &#x22;Skill IDs (from skills.sh) to attach. Skills provide domain-specific knowledge to the AI. Maximum 3.&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;type&#x22;,
            &#x22;type&#x22;: &#x22;'prompt'&#x22;,
            &#x22;required&#x22;: true,
            &#x22;description&#x22;: &#x22;Initialize the chat by sending a prompt to the model.&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;privacy&#x22;,
            &#x22;type&#x22;: &#x22;'public' | 'private' | 'team' | 'team-edit' | 'unlisted'&#x22;,
            &#x22;required&#x22;: false,
            &#x22;description&#x22;: &#x22;Visibility setting for the new chat.&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;title&#x22;,
            &#x22;type&#x22;: &#x22;string&#x22;,
            &#x22;required&#x22;: false,
            &#x22;description&#x22;: &#x22;Title for the new chat.&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;metadata&#x22;,
            &#x22;type&#x22;: &#x22;Record<string, string>&#x22;,
            &#x22;required&#x22;: false,
            &#x22;description&#x22;: &#x22;Arbitrary key-value data to attach to the chat.&#x22;,
            &#x22;deprecated&#x22;: false
          }
        ]
      },
      {
        &#x22;name&#x22;: &#x22;zip&#x22;,
        &#x22;description&#x22;: &#x22;Initialize the chat from a zip archive.&#x22;,
        &#x22;properties&#x22;: [
          {
            &#x22;name&#x22;: &#x22;type&#x22;,
            &#x22;type&#x22;: &#x22;'zip'&#x22;,
            &#x22;required&#x22;: true,
            &#x22;description&#x22;: &#x22;Initialize the chat from a zip archive.&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;url&#x22;,
            &#x22;type&#x22;: &#x22;string&#x22;,
            &#x22;required&#x22;: true,
            &#x22;description&#x22;: &#x22;Zip archive used to seed the new chat.&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;privacy&#x22;,
            &#x22;type&#x22;: &#x22;'public' | 'private' | 'team' | 'team-edit' | 'unlisted'&#x22;,
            &#x22;required&#x22;: false,
            &#x22;description&#x22;: &#x22;Visibility setting for the new chat.&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;title&#x22;,
            &#x22;type&#x22;: &#x22;string&#x22;,
            &#x22;required&#x22;: false,
            &#x22;description&#x22;: &#x22;Title for the new chat.&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;metadata&#x22;,
            &#x22;type&#x22;: &#x22;Record<string, string>&#x22;,
            &#x22;required&#x22;: false,
            &#x22;description&#x22;: &#x22;Arbitrary key-value data to attach to the chat.&#x22;,
            &#x22;deprecated&#x22;: false
          }
        ]
      },
      {
        &#x22;name&#x22;: &#x22;repo&#x22;,
        &#x22;description&#x22;: &#x22;Initialize the chat from a GitHub repository.&#x22;,
        &#x22;properties&#x22;: [
          {
            &#x22;name&#x22;: &#x22;type&#x22;,
            &#x22;type&#x22;: &#x22;'repo'&#x22;,
            &#x22;required&#x22;: true,
            &#x22;description&#x22;: &#x22;Initialize the chat from a GitHub repository.&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;repo&#x22;,
            &#x22;type&#x22;: &#x22;object&#x22;,
            &#x22;required&#x22;: true,
            &#x22;description&#x22;: &#x22;Repository source for initialization. Supports public GitHub repositories and private repositories connected through Vercel.&#x22;,
            &#x22;deprecated&#x22;: false,
            &#x22;properties&#x22;: [
              {
                &#x22;name&#x22;: &#x22;url&#x22;,
                &#x22;type&#x22;: &#x22;string&#x22;,
                &#x22;required&#x22;: true,
                &#x22;description&#x22;: &#x22;GitHub repository URL, for example https://github.com/vercel/next.js.&#x22;,
                &#x22;deprecated&#x22;: false
              },
              {
                &#x22;name&#x22;: &#x22;branch&#x22;,
                &#x22;type&#x22;: &#x22;string&#x22;,
                &#x22;required&#x22;: false,
                &#x22;description&#x22;: &#x22;Branch to import. If omitted, v0 uses the repository default branch.&#x22;,
                &#x22;deprecated&#x22;: false
              }
            ]
          },
          {
            &#x22;name&#x22;: &#x22;privacy&#x22;,
            &#x22;type&#x22;: &#x22;'public' | 'private' | 'team' | 'team-edit' | 'unlisted'&#x22;,
            &#x22;required&#x22;: false,
            &#x22;description&#x22;: &#x22;Visibility setting for the new chat.&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;title&#x22;,
            &#x22;type&#x22;: &#x22;string&#x22;,
            &#x22;required&#x22;: false,
            &#x22;description&#x22;: &#x22;Title for the new chat.&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;metadata&#x22;,
            &#x22;type&#x22;: &#x22;Record<string, string>&#x22;,
            &#x22;required&#x22;: false,
            &#x22;description&#x22;: &#x22;Arbitrary key-value data to attach to the chat.&#x22;,
            &#x22;deprecated&#x22;: false
          }
        ]
      }
    ]
  }
]"
/>

### Response [#response]

<APISignature
  parameters="[
  {
    &#x22;name&#x22;: &#x22;chat&#x22;,
    &#x22;type&#x22;: &#x22;object&#x22;,
    &#x22;required&#x22;: true,
    &#x22;description&#x22;: &#x22;&#x22;,
    &#x22;deprecated&#x22;: false,
    &#x22;properties&#x22;: [
      {
        &#x22;name&#x22;: &#x22;id&#x22;,
        &#x22;type&#x22;: &#x22;string&#x22;,
        &#x22;required&#x22;: true,
        &#x22;description&#x22;: &#x22;Unique chat identifier.&#x22;,
        &#x22;deprecated&#x22;: false
      },
      {
        &#x22;name&#x22;: &#x22;title&#x22;,
        &#x22;type&#x22;: &#x22;string&#x22;,
        &#x22;required&#x22;: false,
        &#x22;description&#x22;: &#x22;Chat title, if generated.&#x22;,
        &#x22;deprecated&#x22;: false
      },
      {
        &#x22;name&#x22;: &#x22;privacy&#x22;,
        &#x22;type&#x22;: &#x22;'public' | 'private' | 'team' | 'team-edit' | 'unlisted'&#x22;,
        &#x22;required&#x22;: true,
        &#x22;description&#x22;: &#x22;Visibility setting of the chat.&#x22;,
        &#x22;deprecated&#x22;: false
      },
      {
        &#x22;name&#x22;: &#x22;createdAt&#x22;,
        &#x22;type&#x22;: &#x22;string&#x22;,
        &#x22;required&#x22;: true,
        &#x22;description&#x22;: &#x22;ISO timestamp of when the chat was created.&#x22;,
        &#x22;deprecated&#x22;: false
      },
      {
        &#x22;name&#x22;: &#x22;updatedAt&#x22;,
        &#x22;type&#x22;: &#x22;string&#x22;,
        &#x22;required&#x22;: false,
        &#x22;description&#x22;: &#x22;ISO timestamp of when the chat was last updated.&#x22;,
        &#x22;deprecated&#x22;: false
      },
      {
        &#x22;name&#x22;: &#x22;authorId&#x22;,
        &#x22;type&#x22;: &#x22;string&#x22;,
        &#x22;required&#x22;: true,
        &#x22;description&#x22;: &#x22;ID of the user who created the chat.&#x22;,
        &#x22;deprecated&#x22;: false
      },
      {
        &#x22;name&#x22;: &#x22;vercelProjectId&#x22;,
        &#x22;type&#x22;: &#x22;string&#x22;,
        &#x22;required&#x22;: false,
        &#x22;description&#x22;: &#x22;Associated Vercel project ID, if any.&#x22;,
        &#x22;deprecated&#x22;: false
      },
      {
        &#x22;name&#x22;: &#x22;metadata&#x22;,
        &#x22;type&#x22;: &#x22;Record<string, string>&#x22;,
        &#x22;required&#x22;: true,
        &#x22;description&#x22;: &#x22;User-defined key-value metadata.&#x22;,
        &#x22;deprecated&#x22;: false
      },
      {
        &#x22;name&#x22;: &#x22;writePermission&#x22;,
        &#x22;type&#x22;: &#x22;boolean&#x22;,
        &#x22;required&#x22;: true,
        &#x22;description&#x22;: &#x22;Whether the caller has write access to this chat.&#x22;,
        &#x22;deprecated&#x22;: false
      }
    ]
  },
  {
    &#x22;name&#x22;: &#x22;usage&#x22;,
    &#x22;type&#x22;: &#x22;object&#x22;,
    &#x22;required&#x22;: true,
    &#x22;description&#x22;: &#x22;Token usage and credit cost for prompt.&#x22;,
    &#x22;deprecated&#x22;: false,
    &#x22;properties&#x22;: [
      {
        &#x22;name&#x22;: &#x22;tokens&#x22;,
        &#x22;type&#x22;: &#x22;object&#x22;,
        &#x22;required&#x22;: true,
        &#x22;description&#x22;: &#x22;Token counts for this message.&#x22;,
        &#x22;deprecated&#x22;: false,
        &#x22;properties&#x22;: [
          {
            &#x22;name&#x22;: &#x22;input&#x22;,
            &#x22;type&#x22;: &#x22;number&#x22;,
            &#x22;required&#x22;: true,
            &#x22;description&#x22;: &#x22;Prompt input value (non-cached).&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;output&#x22;,
            &#x22;type&#x22;: &#x22;number&#x22;,
            &#x22;required&#x22;: true,
            &#x22;description&#x22;: &#x22;Completion output value.&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;cacheRead&#x22;,
            &#x22;type&#x22;: &#x22;number&#x22;,
            &#x22;required&#x22;: true,
            &#x22;description&#x22;: &#x22;Cache-read input value.&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;cacheWrite&#x22;,
            &#x22;type&#x22;: &#x22;number&#x22;,
            &#x22;required&#x22;: true,
            &#x22;description&#x22;: &#x22;Cache-write input value.&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;total&#x22;,
            &#x22;type&#x22;: &#x22;number&#x22;,
            &#x22;required&#x22;: true,
            &#x22;description&#x22;: &#x22;Sum of input, output, cacheRead, and cacheWrite.&#x22;,
            &#x22;deprecated&#x22;: false
          }
        ]
      },
      {
        &#x22;name&#x22;: &#x22;creditsCost&#x22;,
        &#x22;type&#x22;: &#x22;object&#x22;,
        &#x22;required&#x22;: true,
        &#x22;description&#x22;: &#x22;Credit cost for this message.&#x22;,
        &#x22;deprecated&#x22;: false,
        &#x22;properties&#x22;: [
          {
            &#x22;name&#x22;: &#x22;input&#x22;,
            &#x22;type&#x22;: &#x22;number&#x22;,
            &#x22;required&#x22;: true,
            &#x22;description&#x22;: &#x22;Prompt input value (non-cached).&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;output&#x22;,
            &#x22;type&#x22;: &#x22;number&#x22;,
            &#x22;required&#x22;: true,
            &#x22;description&#x22;: &#x22;Completion output value.&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;cacheRead&#x22;,
            &#x22;type&#x22;: &#x22;number&#x22;,
            &#x22;required&#x22;: true,
            &#x22;description&#x22;: &#x22;Cache-read input value.&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;cacheWrite&#x22;,
            &#x22;type&#x22;: &#x22;number&#x22;,
            &#x22;required&#x22;: true,
            &#x22;description&#x22;: &#x22;Cache-write input value.&#x22;,
            &#x22;deprecated&#x22;: false
          },
          {
            &#x22;name&#x22;: &#x22;total&#x22;,
            &#x22;type&#x22;: &#x22;number&#x22;,
            &#x22;required&#x22;: true,
            &#x22;description&#x22;: &#x22;Sum of input, output, cacheRead, and cacheWrite.&#x22;,
            &#x22;deprecated&#x22;: false
          }
        ]
      }
    ]
  }
]"
/>