[metadata]
color-scheme: dark light
description: Creates a new deployment for the authenticated team or user. For non-git deployments, upload files first via the file upload API, then reference them here by SHA — or inline small files directly in the request body. To redeploy an existing deployment, provide its `deploymentId`; all settings are inherited unless explicitly overridden. The deployment begins building immediately and transitions through `QUEUED` → `INITIALIZING` → `BUILDING` before reaching `READY` or `ERROR`.
googlebot: index, max-video-preview:-1, max-image-preview:large, max-snippet:-1
initiator-trace: 00-6864a36f14ac8acb63ba5fc939e182bf-b9715327262e82c8-01
robots: index, follow
theme-color: #0a0a0a
trace-attributes: {"next.appdir":true}
viewport: width=device-width, initial-scale=1, maximum-scale=1, viewport-fit=cover

[canonical-links]
https://vercel.com/docs/rest-api/deployments/create-a-new-deployment

[document-links]
/home
AI Apps: /solutions/ai-apps
AI Gateway: /ai-gateway
AI Gateway: /docs/ai-gateway
AI Integrations: /docs/agent-resources/integrations-for-models
AI SDK: /ai-sdk
AI SDK: /docs/ai-sdk
APIs & SDKs: /docs/rest-api
About: /about
Academy: /academy
Acceptable Use Policy: /legal/acceptable-use-policy
Agent Skills: https://skills.sh
All frameworks: /docs/frameworks
Articles: /i
Blog ↗: https://vercel.com/blog
Blog: /blog
Bot ID: /botid
Bot Management: /docs/bot-management
Bot Management: /security/bot-management
BotID: /docs/botid
CI/CD: /products/previews
CLI: /docs/cli
Careers: /careers
Changelog ↗: https://vercel.com/changelog
Changelog: /changelog
Chat SDK New: /chat
Commerce: /solutions/composable-commerce
Community ↗: https://community.vercel.com
Community: https://community.vercel.com
Compliance: /docs/security/compliance
Connect New: /connect
Container Registry: /docs/container-registry
Content Delivery: /cdn
Cookie Policy: /legal/cookie-policy
Customers: /customers
DEL Delete a Deployment: /docs/rest-api/deployments/delete-a-deployment
DPA: /legal/dpa
Delivery Network: /docs/cdn
Deployment Protection: /docs/deployment-protection
Deployments: /docs/deployments
Design Engineers: /solutions/design-engineering
Docs: /docs
Domains: /docs/domains
Domains: /domains
Enterprise: /enterprise
Errors: /docs/rest-api/errors
Events: /events
FastAPI: /docs/frameworks/backend/fastapi
Feature Flags: /docs/flags
Firewall: /docs/vercel-firewall
Flags SDK: /docs/flags/flags-sdk-reference
Fluid Compute: /fluid
Functions: /docs/functions
GET Get Deployment Events: /docs/rest-api/deployments/get-deployment-events
GET Get Deployment File Contents: /docs/rest-api/deployments/get-deployment-file-contents
GET Get a Deployment by ID or URL: /docs/rest-api/deployments/get-a-deployment-by-id-or-url
GET List Deployment Files: /docs/rest-api/deployments/list-deployment-files
GET List Deployments: /docs/rest-api/deployments/list-deployments
Getting Started: /docs/getting-started-with-vercel
GitHub: https://github.com/vercel
Help: /help
Instagram: https://www.instagram.com/vercel/
Integrations: /docs/integrations
Knowledge Base: /kb
Legal (all documents): /legal
LinkedIn: https://linkedin.com/company/vercel
Log In: /login
Marketing Sites: /solutions/marketing-sites
Marketplace: /marketplace
Microfrontends: /docs/microfrontends
Next.js: /frameworks/nextjs
Nitro: /docs/frameworks/backend/nitro
Nuxt: /docs/frameworks/full-stack/nuxt
Observability: /docs/observability
Observability: /products/observability
Open Source Program: /open-source-program
OpenAPI Specification: https://openapi.vercel.sh/
Overview: /docs/rest-api
PATCH Cancel a Deployment: /docs/rest-api/deployments/cancel-a-deployment
PATCH Update Deployment Integration Action: /docs/rest-api/deployments/update-deployment-integration-action
POST Create a New Deployment: /docs/rest-api/deployments/create-a-new-deployment
POST Upload Deployment Files: /docs/rest-api/deployments/upload-deployment-files
Partner Finder: /partners/solution-partners
Passport New: /passport
Platform Engineers: /solutions/platform-engineering
Platform Security: /security
Platforms: /solutions/multi-tenant-saas
Press: /press
Pricing: /pricing
Privacy Policy: /legal/privacy-policy
Queues SDK New: /docs/queues/sdk
Sandbox: /docs/sandbox
Sandbox: /sandbox
Shipped on Vercel: /shipped
Sign Up: /signup
Startups: /startups
Status: https://vercel-status.com
Storage: /docs/storage
Streamdown: https://streamdown.ai
SvelteKit: /docs/frameworks/full-stack/sveltekit
Tanstack Start: /docs/frameworks/full-stack/tanstack-start
Templates: /templates
Terms of Service: /legal/terms
Toolbar: /docs/vercel-toolbar
Trust Center: https://security.vercel.com
Turborepo: /solutions/turborepo
Vercel + AWS: /partners/aws
Vercel Agent: /agent
Vercel Agent: /docs/agent
Vercel Drop New: /drop
Vercel MCP: /docs/mcp
Vercel Plugin New: /plugin
Vercel REST API: /docs
Vercel REST API: /docs/rest-api
Vercel SDK: /docs/rest-api/sdk
WAF: /security/web-application-firewall
Web Apps: /solutions/web-apps
Workflow SDK New: /workflows
Workflow: /docs/workflows
Workflows: /workflows
X: https://x.com/vercel
YouTube: https://youtube.com/@VercelHQ
eve New: /eve
eve New: https://eve.dev/
v0 ↗: https://v0.app
v0: https://v0.app
xmcp: /docs/frameworks/backend/xmcp

[structured-data]
{"@context":"https://schema.org","@type":"WebSite","name":"Vercel Documentation","publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"https://lishhsx6kmthaacj.public.blob.vercel-storage.com/vercel-wordmark.svg"},"name":"Vercel Inc.","sameAs":["https://x.com/vercel","https://github.com/vercel/vercel","https://www.linkedin.com/company/vercel/","https://bsky.app/profile/vercel.com"],"url":"https://vercel.com/"},"url":"https://vercel.com/docs"}

[content]
Create a new deployment | Vercel REST API
Skip to content
Copy Logo as SVG
Copy Wordmark as SVG
Brand Guidelines
Docs
Build
Build with AI
AI Gateway
AI SDK
Sandbox
Container Registry
Workflow
Vercel Agent
v0
↗
Vercel MCP
AI Integrations
Deploy & scale
Deployments
CLI
Functions
Delivery Network
Storage
Integrations
Microfrontends
Domains
Operate & protect
Firewall
Observability
Feature Flags
Toolbar
Bot Management
BotID
Deployment Protection
Compliance
Learn
Resources
Changelog
↗
Blog
↗
Community
↗
Knowledge Base
APIs & SDKs
Templates
Getting Started
Ask AI
Log In
Sign Up
Build
Build with AI
AI Gateway
AI SDK
Sandbox
Container Registry
Workflow
Vercel Agent
v0
↗
Vercel MCP
AI Integrations
Deploy & scale
Deployments
CLI
Functions
Delivery Network
Storage
Integrations
Microfrontends
Domains
Operate & protect
Firewall
Observability
Feature Flags
Toolbar
Bot Management
BotID
Deployment Protection
Compliance
Learn
Resources
Changelog
↗
Blog
↗
Community
↗
Knowledge Base
APIs & SDKs
Templates
Getting Started
Ask AI
Sign Up
Log In
Vercel REST API
Overview
Errors
Access Groups
Ai Gateway
Aliases
Artifacts
Authentication
Billing
Bulk Redirects
Certs
Checks V2
Connect
Deployments
GET
Get Deployment Events
PATCH
Update Deployment Integration Action
GET
Get a Deployment by ID or URL
POST
Create a New Deployment
PATCH
Cancel a Deployment
POST
Upload Deployment Files
GET
List Deployment Files
GET
Get Deployment File Contents
GET
List Deployments
DEL
Delete a Deployment
DNS
Domains
Domains Registrar
Drains
Edge Cache
Environment
Feature Flags
Global Config
Integrations
Logs
Marketplace
Microfrontends
Networking
Observability
Project Routes
Projectmembers
Projects
Rolling Release
Sandboxes
Security
Static Ips
Storage
Teams
User
VCR
Web Analytics
Webhooks
APIs & SDKs
Vercel REST API
Create a new deployment
Create a new deployment
POST
https://api.vercel.com/v13/deployments
Creates a new deployment for the authenticated team or user. For non-git deployments, upload files first via the file upload API, then reference them here by SHA — or inline small files directly in the request body. To redeploy an existing deployment, provide its
deploymentId
; all settings are inherited unless explicitly overridden. The deployment begins building immediately and transitions through
QUEUED
→
INITIALIZING
→
BUILDING
before reaching
READY
or
ERROR
.
TypeScript
Next.js
cURL
https://api.vercel.com/v13/deployments
1
const
response
=
await
fetch
(
'https://api.vercel.com/v13/deployments?forceNew=value&skipAutoDetectionConfirmation=value&teamId=string&slug=string'
,
{
2
method
:
'POST'
,
3
headers
:
{
4
'Authorization'
:
'Bearer YOUR_ACCESS_TOKEN'
,
5
'Content-Type'
:
'application/json'
,
6
}
,
7
body
:
JSON
.
stringify
(
{
8
"customEnvironmentSlugOrId"
:
"staging"
,
9
"deploymentId"
:
"dpl_2qn7PZrx89yxY34vEZPD31Y9XVj6"
,
10
"files"
:
[
11
{
12
"data"
:
"string"
,
13
"encoding"
:
"base64"
,
14
"file"
:
"folder/file.js"
15
}
16
]
,
17
"gitMetadata"
:
{
18
"remoteUrl"
:
"https://github.com/vercel/next.js"
,
19
"commitAuthorName"
:
"kyliau"
,
20
"commitAuthorEmail"
:
"kyliau@example.com"
,
21
"commitMessage"
:
"add method to measure Interaction to Next Paint (INP) (#36490)"
,
22
"commitRef"
:
"main"
,
23
"commitSha"
:
"dc36199b2234c6586ebe05ec94078a895c707e29"
,
24
"dirty"
:
"true"
,
25
"ci"
:
"true"
,
26
"ciType"
:
"github-actions"
,
27
"ciGitProviderUsername"
:
"rauchg"
,
28
"ciGitRepoVisibility"
:
"private"
,
29
"rootDirectory"
:
"apps/web"
30
}
,
31
"gitSource"
:
{
32
"type"
:
"vercel"
,
33
"sha"
:
"a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
34
}
,
35
"meta"
:
"[object Object]"
,
36
"monorepoManager"
:
"string"
,
37
"name"
:
"my-instant-deployment"
,
38
"project"
:
"my-deployment-project"
,
39
"projectSettings"
:
{
40
"buildCommand"
:
"next build"
,
41
"commandForIgnoringBuildStep"
:
"string"
,
42
"devCommand"
:
"string"
,
43
"framework"
:
"null"
,
44
"installCommand"
:
"pnpm install"
,
45
"nodeVersion"
:
"24.x"
,
46
"outputDirectory"
:
"string"
,
47
"rootDirectory"
:
"string"
,
48
"serverlessFunctionRegion"
:
"string"
,
49
"skipGitConnectDuringLink"
:
"true"
,
50
"sourceFilesOutsideRootDirectory"
:
"true"
51
}
,
52
"target"
:
"production"
,
53
"withLatestCommit"
:
"true"
54
}
)
,
55
}
)
;
56
57
const
data
=
await
response
.
json
(
)
;
58
console
.
log
(
data
)
;
Response
1
{
2
"alias"
:
[
]
,
3
"aliasAssigned"
:
"false"
,
4
"id"
:
"dpl_89qyp1cskzkLrVicDaZoDbjyHuDJ"
,
5
"target"
:
"null"
,
6
"readyState"
:
"READY"
,
7
"aliasError"
:
{
8
"code"
:
"string"
,
9
"message"
:
"string"
10
}
,
11
"aliasWarning"
:
{
12
"code"
:
"string"
,
13
"message"
:
"string"
,
14
"link"
:
"string"
,
15
"action"
:
"string"
16
}
,
17
"errorCode"
:
"string"
,
18
"errorMessage"
:
"string"
19
}
Authentication
Authorization
bearerToken
Default authentication mechanism
Query parameters
forceNew
any
Optional
Forces a new deployment even if there is a previous similar deployment. Set to
1
to bypass deployment deduplication and always trigger a fresh build.
+
Show
2
enum values
skipAutoDetectionConfirmation
any
Optional
Set to
1
to skip framework auto-detection and proceed without confirmation. By default, if Vercel detects a framework that differs from the project setting, the API returns a
400
asking you to confirm. Use this to suppress that check in automated pipelines.
+
Show
2
enum values
teamId
string
Optional
The Team identifier to perform the request on behalf of.
slug
string
Optional
The Team slug to perform the request on behalf of.
Body
application/json
customEnvironmentSlugOrId
string
Optional
The slug or ID of a custom environment to deploy to, overriding the default target environment. When omitted, the deployment targets the environment inferred from the branch (production or preview).
deploymentId
string
Optional
The ID of an existing deployment to redeploy. All project settings and environment variables are inherited from the original unless explicitly overridden in this request. The redeployment gets a new ID, URL, and build.
files
array
Optional
The files to include in the deployment. Each entry is either an inlined file (with
data
and
encoding
) or a reference to a previously uploaded file (with
sha
and
size
). Required for non-git deployments. Cannot be used together with
gitSource
.
+
Show
3
properties
gitMetadata
object
Optional
Populates initial git metadata for different git providers.
+
Show
12
properties
gitSource
object
Optional
9
variants
+
Show
9
variants
meta
object
Optional
An object containing the deployment's metadata. Multiple key-value pairs can be attached to a deployment
monorepoManager
string
Optional
The monorepo manager that is being used for this deployment. When
null
is used no monorepo manager is selected
name
string
Required
A string with the project name used in the deployment URL
project
string
Optional
The target project identifier in which the deployment will be created. When defined, this parameter overrides name
projectSettings
object
Optional
Project settings that will be applied to the deployment. It is required for the first deployment of a project and will be saved for any following deployments
+
Show
11
properties
target
string
Optional
Either not defined,
staging
,
production
, or a custom environment identifier. If
staging
, a staging alias in the format
<project>-<team>.vercel.app
will be assigned. If
production
, any aliases defined in
alias
will be assigned. If omitted, the target will be
preview
.
withLatestCommit
boolean
Optional
When
true
and
deploymentId
is passed in, the sha from the previous deployment's
gitSource
is removed forcing the latest commit to be used.
Response
200
Returns the newly created deployment object. Poll `readyState` to track build progress. See https://vercel.com/docs/deployments/deployment-states for possible states. Returns the reduced deployment view for anonymous (`vcn_`) callers. Pool-team details are withheld.
Variant 1
Variant 2
alias
array
Optional
aliasAssigned
boolean
Required
+
Show
2
enum values
id
string
Required
A string holding the unique ID of the deployment
target
string
Optional
If defined, either
staging
if a staging alias in the format
<project>.<team>.now.sh
was assigned upon creation, or
production
if the aliases from
alias
were assigned.
null
value indicates the "preview" deployment.
+
Show
3
enum values
readyState
string
Required
The state of the deployment depending on the process of deploying, or if it is ready or in an error state
+
Show
7
enum values
aliasError
object
Optional
An object that will contain a
code
and a
message
when the aliasing fails, otherwise the value will be
null
+
Show
2
properties
aliasWarning
object
Optional
+
Show
4
properties
errorCode
string
Optional
errorMessage
string
Optional
Errors
400
One of the provided values in the request body is invalid. One of the provided values in the request query is invalid.
401
The request is not authorized.
402
The account is missing a payment so payment method must be updated Pro customers are allowed to deploy Serverless Functions to up to `proMaxRegions` regions, or if the project was created before the limit was introduced. Deploying to Serverless Functions to multiple regions requires a plan update
403
You do not have permission to access this resource.
404
Error
409
The deployment project is being transferred
410
Error
426
Error
429
Error
500
Error
503
Error
TypeScript
Next.js
cURL
https://api.vercel.com/v13/deployments
1
const
response
=
await
fetch
(
'https://api.vercel.com/v13/deployments?forceNew=value&skipAutoDetectionConfirmation=value&teamId=string&slug=string'
,
{
2
method
:
'POST'
,
3
headers
:
{
4
'Authorization'
:
'Bearer YOUR_ACCESS_TOKEN'
,
5
'Content-Type'
:
'application/json'
,
6
}
,
7
body
:
JSON
.
stringify
(
{
8
"customEnvironmentSlugOrId"
:
"staging"
,
9
"deploymentId"
:
"dpl_2qn7PZrx89yxY34vEZPD31Y9XVj6"
,
10
"files"
:
[
11
{
12
"data"
:
"string"
,
13
"encoding"
:
"base64"
,
14
"file"
:
"folder/file.js"
15
}
16
]
,
17
"gitMetadata"
:
{
18
"remoteUrl"
:
"https://github.com/vercel/next.js"
,
19
"commitAuthorName"
:
"kyliau"
,
20
"commitAuthorEmail"
:
"kyliau@example.com"
,
21
"commitMessage"
:
"add method to measure Interaction to Next Paint (INP) (#36490)"
,
22
"commitRef"
:
"main"
,
23
"commitSha"
:
"dc36199b2234c6586ebe05ec94078a895c707e29"
,
24
"dirty"
:
"true"
,
25
"ci"
:
"true"
,
26
"ciType"
:
"github-actions"
,
27
"ciGitProviderUsername"
:
"rauchg"
,
28
"ciGitRepoVisibility"
:
"private"
,
29
"rootDirectory"
:
"apps/web"
30
}
,
31
"gitSource"
:
{
32
"type"
:
"vercel"
,
33
"sha"
:
"a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
34
}
,
35
"meta"
:
"[object Object]"
,
36
"monorepoManager"
:
"string"
,
37
"name"
:
"my-instant-deployment"
,
38
"project"
:
"my-deployment-project"
,
39
"projectSettings"
:
{
40
"buildCommand"
:
"next build"
,
41
"commandForIgnoringBuildStep"
:
"string"
,
42
"devCommand"
:
"string"
,
43
"framework"
:
"null"
,
44
"installCommand"
:
"pnpm install"
,
45
"nodeVersion"
:
"24.x"
,
46
"outputDirectory"
:
"string"
,
47
"rootDirectory"
:
"string"
,
48
"serverlessFunctionRegion"
:
"string"
,
49
"skipGitConnectDuringLink"
:
"true"
,
50
"sourceFilesOutsideRootDirectory"
:
"true"
51
}
,
52
"target"
:
"production"
,
53
"withLatestCommit"
:
"true"
54
}
)
,
55
}
)
;
56
57
const
data
=
await
response
.
json
(
)
;
58
console
.
log
(
data
)
;
Response
1
{
2
"alias"
:
[
]
,
3
"aliasAssigned"
:
"false"
,
4
"id"
:
"dpl_89qyp1cskzkLrVicDaZoDbjyHuDJ"
,
5
"target"
:
"null"
,
6
"readyState"
:
"READY"
,
7
"aliasError"
:
{
8
"code"
:
"string"
,
9
"message"
:
"string"
10
}
,
11
"aliasWarning"
:
{
12
"code"
:
"string"
,
13
"message"
:
"string"
,
14
"link"
:
"string"
,
15
"action"
:
"string"
16
}
,
17
"errorCode"
:
"string"
,
18
"errorMessage"
:
"string"
19
}
Copy as Markdown
Install Vercel Plugin
OpenAPI Specification
Give feedback
Ask AI about this page
Agent Stack
AI SDK
AI Gateway
Sandbox
Workflows
Connect
New
Passport
New
eve
New
Core Platform
CI/CD
Content Delivery
Fluid Compute
Observability
Security
Platform Security
WAF
Bot Management
Bot ID
Tools
Vercel Drop
New
Vercel Agent
Vercel Plugin
New
Agent Skills
Next.js
Domains
v0
Frameworks
eve
New
Nuxt
SvelteKit
Nitro
Turborepo
Tanstack Start
FastAPI
xmcp
All frameworks
SDKs
Vercel SDK
Workflow SDK
New
Flags SDK
Chat SDK
New
Queues SDK
New
Streamdown
Build
AI Apps
Web Apps
Marketing Sites
Platforms
Commerce
Platform Engineers
Design Engineers
Learn
Docs
Blog
Changelog
Knowledge Base
Academy
Articles
Community
Explore
Customers
Marketplace
Templates
Partner Finder
Vercel + AWS
Company
About
Careers
Press
Events
Startups
Shipped on Vercel
Open Source Program
Enterprise
Pricing
Help
Legal & Trust
Privacy Policy
Terms of Service
Cookie Policy
DPA
Acceptable Use Policy
Legal (all documents)
Trust Center
Status
Cookie Preferences
Social
GitHub
X
LinkedIn
YouTube
Instagram
