OpenAPI Specification
openapi: 3.1.0
info:
title: v0 App agent chats API
version: '0'
description: Full stack vibe coding API
termsOfService: https://vercel.com/legal/api-terms
servers:
- url: https://api.v0.dev/v1
tags:
- name: chats
description: Chats
paths:
/chats:
post:
summary: Create Chat
description: 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.
operationId: chats.create
tags:
- chats
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: 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:
description: 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.
type: array
items:
type: object
properties:
url:
type: string
description: The URL or data URI of the file or asset to include with the message.
required:
- url
additionalProperties: false
system:
description: Provides system-level context or background for the chat. This is typically used to specify frameworks, tools, or development environments relevant to the task.
type: string
chatPrivacy:
default: private
description: 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.
type: string
enum:
- public
- private
- team-edit
- team
- unlisted
projectId:
description: Associates the chat with a specific project in your workspace. Helps organize and group related chats under a common project context.
type: string
modelConfiguration:
description: Settings that control how the model behaves in the chat.
type: object
properties:
modelId:
default: v0-pro
type: string
enum:
- v0-auto
- v0-mini
- v0-pro
- v0-max
- v0-max-fast
description: Model to use for the generation.
imageGenerations:
default: false
type: boolean
description: Enables image generations to generate up to 5 images per version.
thinking:
default: false
type: boolean
description: Enables thinking to generate a response in multiple steps.
additionalProperties: false
responseMode:
default: sync
description: '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.'
type: string
enum:
- sync
- async
- experimental_stream
designSystemId:
description: The ID of a design system to apply to this chat. Design systems provide consistent styling and components for generated UI.
type:
- string
- 'null'
mcpServerIds:
description: Array of MCP server IDs to enable for this chat. When provided, only the specified servers will be used. When omitted, falls back to the user's enabled MCP servers.
type: array
items:
type: string
attachedSkillIds:
description: Array of skill IDs (from skills.sh) to attach to this chat. Skills provide domain-specific knowledge and instructions that guide the AI. Maximum 3 skills per chat.
type: array
items:
type: string
metadata:
default: {}
description: Arbitrary key-value data to attach to the chat. Useful for storing additional data about the chat, such as external user IDs.
type: object
propertyNames:
type: string
minLength: 1
maxLength: 40
additionalProperties:
type: string
maxLength: 500
required:
- message
additionalProperties: false
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ChatDetail'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'413':
description: Payload Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/PayloadTooLargeError'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityError'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
security:
- apiKey: []
get:
summary: Find Chats
description: Retrieves a list of existing chats, with support for pagination and filtering by favorite status, Vercel project, or Git branch. Helps manage and navigate chat history.
operationId: chats.find
tags:
- chats
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
object:
type: string
const: list
data:
type: array
items:
type: object
properties:
id:
type: string
description: A unique identifier for the chat.
object:
type: string
const: chat
description: Fixed value identifying this object as a chat.
shareable:
type: boolean
description: Indicates whether the chat can be shared via public link.
privacy:
type: string
enum:
- public
- private
- team
- team-edit
- unlisted
description: Defines the visibility of the chat—private, team-only, or public.
name:
description: An optional name assigned to the chat by the user.
type: string
title:
type: string
description: Deprecated title field preserved for backward compatibility.
deprecated: true
createdAt:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
description: The ISO timestamp representing when the chat was created.
updatedAt:
description: The ISO timestamp of the last update to the chat.
type: string
favorite:
type: boolean
description: Indicates whether the chat is marked as a favorite.
authorId:
type: string
description: The ID of the user who created the chat.
projectId:
description: Optional ID of the v0 project associated with this chat.
type: string
vercelProjectId:
description: Optional ID of the linked Vercel project, if connected.
type: string
webUrl:
type: string
description: Web URL to view this chat in the browser.
apiUrl:
type: string
description: API URL to access this chat via the API.
latestVersion:
description: The most recent generated version of the chat, if available.
type: object
properties:
id:
type: string
description: A unique identifier for the version.
object:
type: string
const: version
description: Fixed value identifying this object as a version.
status:
type: string
enum:
- pending
- completed
- failed
description: The current status of the version generation process.
demoUrl:
description: Optional URL for previewing the generated output.
type: string
screenshotUrl:
type: string
description: URL to retrieve a screenshot of this version.
createdAt:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
description: The date and time when the version was created, in ISO 8601 format.
updatedAt:
description: The date and time when the version was last updated, in ISO 8601 format.
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
required:
- id
- object
- status
- createdAt
additionalProperties: false
required:
- id
- object
- shareable
- privacy
- createdAt
- favorite
- authorId
- webUrl
- apiUrl
additionalProperties: false
description: Summary of a chat, including metadata like privacy, author, latest version, and URLs.
required:
- object
- data
additionalProperties: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'413':
description: Payload Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/PayloadTooLargeError'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityError'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
parameters:
- name: limit
in: query
required: false
schema:
default: 60
description: Specifies the maximum number of chat records to return in a single response. Useful for paginating results when there are many chats.
type: number
maximum: 60
description: Specifies the maximum number of chat records to return in a single response. Useful for paginating results when there are many chats.
- name: offset
in: query
required: false
schema:
default: 0
description: Determines the starting point for pagination. Used in conjunction with limit to retrieve a specific page of chat results.
type: number
description: Determines the starting point for pagination. Used in conjunction with limit to retrieve a specific page of chat results.
- name: isFavorite
in: query
required: false
schema:
description: 'Filters chats by their "favorite" status. Accepts `"true"` or `"false"` (as strings, not booleans).
- `"true"`: returns only chats marked as favorites.
- `"false"`: returns only non-favorite chats.'
type: string
enum:
- 'true'
- 'false'
description: 'Filters chats by their "favorite" status. Accepts `"true"` or `"false"` (as strings, not booleans).
- `"true"`: returns only chats marked as favorites.
- `"false"`: returns only non-favorite chats.'
- name: vercelProjectId
in: query
required: false
schema:
description: Filters chats by the linked Vercel project ID. Only returns chats associated with the specified Vercel project.
type: string
description: Filters chats by the linked Vercel project ID. Only returns chats associated with the specified Vercel project.
- name: branch
in: query
required: false
schema:
description: Filters chats by the Git branch name. Only returns chats that have an active Git connection with the specified branch as the head.
type: string
description: Filters chats by the Git branch name. Only returns chats that have an active Git connection with the specified branch as the head.
security:
- apiKey: []
/chats/init:
post:
summary: Initialize Chat
description: Initializes a new chat from source content such as files, repositories, registries, or zip archives. Enables context-rich conversations based on code or assets.
operationId: chats.init
tags:
- chats
requestBody:
required: true
content:
application/json:
schema:
allOf:
- type: object
properties:
name:
description: A user-defined name for the chat. Helps identify or describe the purpose of the chat session in the UI or API responses.
type: string
chatPrivacy:
default: private
description: Controls the visibility of the chat. Defines whether the chat is private, shared with a team, or publicly accessible.
type: string
enum:
- public
- private
- team-edit
- team
- unlisted
projectId:
description: Associates the chat with a specific project. Useful for organizing and grouping chats in a workspace.
type: string
metadata:
default: {}
description: Arbitrary key-value data to attach to the chat. Useful for storing additional data about the chat, such as external user IDs.
type: object
propertyNames:
type: string
minLength: 1
maxLength: 40
additionalProperties:
type: string
maxLength: 500
additionalProperties: false
- anyOf:
- type: object
properties:
type:
type: string
const: files
description: Specifies the initialization method. For this endpoint, it defines the source of content being used to initialize the chat.
files:
type: array
items:
anyOf:
- type: object
properties:
name:
type: string
url:
type: string
locked:
description: Whether to lock this file to prevent AI from overwriting it during generation
type: boolean
required:
- name
- url
additionalProperties: false
- type: object
properties:
name:
type: string
content:
type: string
locked:
description: Whether to lock this file to prevent AI from overwriting it during generation
type: boolean
required:
- name
- content
additionalProperties: false
description: An array of inline file objects used to initialize the chat. Each object must contain a file `name` and its `content`.
required:
- type
- files
additionalProperties: false
- type: object
properties:
type:
type: string
const: repo
description: Specifies the initialization method. For this endpoint, it defines the source of content being used to initialize the chat.
repo:
type: object
properties:
url:
type: string
branch:
type: string
maxLength: 250
required:
- url
additionalProperties: false
description: Specifies a repository source for initialization. Supports both public and private GitHub repositories. For private repositories, ensure your GitHub account is connected through Vercel.
lockAllFiles:
description: Whether to lock all files in the repository to prevent AI from overwriting them during generation
type: boolean
required:
- type
- repo
additionalProperties: false
- type: object
properties:
type:
type: string
const: registry
description: Specifies the initialization method. For this endpoint, it defines the source of content being used to initialize the chat.
registry:
type: object
properties:
url:
type: string
required:
- url
additionalProperties: false
description: Allows initialization from a predefined component or code registry. Includes the registry source and identifier for the desired component/module.
lockAllFiles:
description: Whether to lock all files from the registry to prevent AI from overwriting them during generation
type: boolean
required:
- type
- registry
additionalProperties: false
- type: object
properties:
type:
type: string
const: zip
description: Specifies the initialization method. For this endpoint, it defines the source of content being used to initialize the chat.
zip:
type: object
properties:
url:
type: string
format: uri
required:
- url
additionalProperties: false
description: Provides a zipped bundle of files as the input source. Typically includes a base64-encoded archive or a remote URL reference.
lockAllFiles:
description: Whether to lock all files from the zip archive to prevent AI from overwriting them during generation
type: boolean
required:
- type
- zip
additionalProperties: false
- type: object
properties:
type:
type: string
const: template
description: Specifies the initialization method. For this endpoint, it defines the source of content being used to initialize the chat.
templateId:
type: string
description: The ID of the template to initialize the chat from. This should be a valid template ID from the v0 template system.
required:
- type
- templateId
additionalProperties: false
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ChatDetail'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'413':
description: Payload Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/PayloadTooLargeError'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityError'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
security:
- apiKey: []
/chats/{chatId}:
delete:
summary: Delete Chat
description: Deletes a specific chat based on the provided chatId. This operation is irreversible and permanently removes the chat and its contents.
operationId: chats.delete
tags:
- chats
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
id:
type: string
object:
type: string
const: chat
deleted:
type: boolean
const: true
required:
- id
- object
- deleted
additionalProperties: false
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'413':
description: Payload Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/PayloadTooLargeError'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityError'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
parameters:
- name: chatId
in: path
required: true
schema:
type: string
description: The unique identifier of the chat to delete. This must be passed as a path parameter in the URL.
security:
- apiKey: []
get:
summary: Get Chat
description: Retrieves the full details of a specific chat using its `chatId`. Includes messages, metadata, and associated configuration.
operationId: chats.getById
tags:
- chats
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ChatDetail_AppApi'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'413':
description: Payload Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/PayloadTooLargeError'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityError'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
parameters:
- name: chatId
in: path
required: true
schema:
type: string
description: The unique identifier of the chat to retrieve. Must be provided as a path parameter.
- name: cursor
in: query
required: false
schema:
type: string
description: Query parameter "cursor"
- name: limit
in: query
required: false
schema:
type: number
description: Query parameter "limit"
security:
- apiKey: []
patch:
summary: Update Chat
description: Up
# --- truncated at 32 KB (266 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/v0/refs/heads/main/openapi/v0-chats-api-openapi.yml