---
title: "Create Project"
method: POST
path: "/projects"
tags: ["projects"]
---

# Create Project

`POST /projects`

Creates a new v0 project with an optional description, icon, environment variables, and instructions. Projects help organize chats and manage context.

## Request body

- object
  - `name` string, required — The name of the project.
  - `description` string — A brief summary of the project’s purpose.
  - `icon` string — An icon identifier to visually represent the project.
  - `environmentVariables` object[] — A list of key-value pairs used to define runtime variables for the project.
    - `key` string, required
    - `value` string, required
  - `instructions` string — Guidance or goals that provide context for the model when working within the project.
  - `vercelProjectId` string — The ID of an existing Vercel project to link to. If not provided, a new Vercel project will be created.
  - `privacy` 'private' | 'team' — The privacy setting for the project. For user accounts, this is always "private". For team/enterprise accounts, this can be either "private" or "team".

## Response `200`

Success

- ProjectDetail — Full representation of a project, including its associated chats.
  - `id` string, required — A unique identifier for the project.
  - `object` 'project', required — Fixed value identifying this object as a project.
  - `name` string, required — The name of the project as defined by the user.
  - `privacy` 'private' | 'team', required — The privacy setting for the project - either private or team.
  - `vercelProjectId` string — Optional ID of the linked Vercel project, if connected.
  - `createdAt` string, date-time, required — The ISO timestamp representing when the project was created.
  - `updatedAt` string, date-time — The ISO timestamp of the most recent update, if available.
  - `apiUrl` string, uri, required — The API endpoint URL for accessing this project programmatically.
  - `webUrl` string, uri, required — The web URL where the project can be viewed or managed.
  - `description` string — The description of the project.
  - `instructions` string — The instructions for the project.
  - `chats` object[], required — List of all chats that are associated with this project.
    - `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.
    - `vercelProjectId` string — Optional ID of the linked Vercel project, if connected.
    - `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 — The most recent generated version of the chat, 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.
      - `screenshotUrl` string — URL to retrieve a screenshot of this version.
      - `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.

## 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

- **2026-05-11** `95c713e70ec3` — 1 info
  - the `instructions` request property's maxLength was increased from `1000` to `2000`
- **2026-04-30** `670c302548ec` — 1 info
  - added the optional property `chats/items/vercelProjectId` to the response with the `200` status
- …earlier changes not shown

[Full history](https://skmtc.dev/vercel/apis/v0-platform-api-beta/changes/projects/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/b53921245779/schema)