Sign in
deployments

Create a new deployment

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.

post/v13/deployments

Query parameters

forceNew'0' | '1'

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.

Example:1

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.

skipAutoDetectionConfirmation'0' | '1'

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.

Example:1

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.

teamIdstring
Example:team_1a2b3c4d5e6f7g8h9i0j1k2l

The Team identifier to perform the request on behalf of.

slugstring
Example:my-team-url-slug

The Team slug to perform the request on behalf of.

Request body

customEnvironmentSlugOrIdstring

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).

deploymentIdstring

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.

metaobject

An object containing the deployment's metadata. Multiple key-value pairs can be attached to a deployment

monorepoManagerstring nullable

The monorepo manager that is being used for this deployment. When null is used no monorepo manager is selected

namestring required

A string with the project name used in the deployment URL

projectstring

The target project identifier in which the deployment will be created. When defined, this parameter overrides name

targetstring

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.

withLatestCommitboolean

When true and deploymentId is passed in, the sha from the previous deployment's gitSource is removed forcing the latest commit to be used.

Example request

{
  "customEnvironmentSlugOrId": "staging",
  "deploymentId": "dpl_2qn7PZrx89yxY34vEZPD31Y9XVj6",
  "files": [
    {
      "file": "folder/file.js"
    }
  ],
  "gitMetadata": {
    "remoteUrl": "https://github.com/vercel/next.js",
    "commitAuthorName": "kyliau",
    "commitAuthorEmail": "kyliau@example.com",
    "commitMessage": "add method to measure Interaction to Next Paint (INP) (#36490)",
    "commitRef": "main",
    "commitSha": "dc36199b2234c6586ebe05ec94078a895c707e29",
    "dirty": true,
    "ci": true,
    "ciType": "github-actions",
    "ciGitProviderUsername": "rauchg",
    "ciGitRepoVisibility": "private"
  },
  "gitSource": {
    "sha": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
  },
  "meta": {
    "foo": "bar"
  },
  "name": "my-instant-deployment",
  "project": "my-deployment-project",
  "projectSettings": {
    "buildCommand": "next build",
    "installCommand": "pnpm install"
  },
  "target": "production"
}

Response

Returns the newly created deployment object. Poll readyState to track build progress. See https://vercel.com/docs/deployments/deployment-states for possible states.

alwaysRefuseToBuildfalse | true
buildArtifactUrlsstring[]
envstring[] required
inspectorUrlstring nullable required
isInConcurrentBuildsQueuefalse | true required
isInSystemBuildsQueuefalse | true required
aliasstring[]

A list of all the aliases (default aliases, staging aliases and production aliases) that were assigned upon deployment creation

aliasAssignedfalse | true required

A boolean that will be true when the aliases from the alias property were assigned successfully

bootedAtnumber required
buildingAtnumber required
buildContainerFinishedAtnumber

Since April 2025 it necessary for On-Demand Concurrency Minutes calculation

buildSkippedfalse | true required
initReadyAtnumber
isFirstBranchDeploymentfalse | true
publicfalse | true required

A boolean representing if the deployment is public or not. By default this is false

readynumber
status'BLOCKED' | 'BUILDING' | 'CANCELED' | 'ERROR' | 'INITIALIZING' | 'QUEUED' | 'READY' required
userAliasesstring[]

An array of domains that were provided by the user when creating the Deployment.

previewCommentsEnabledfalse | true

Whether or not preview comments are enabled for the deployment

ttyBuildLogsfalse | true
oomReport'out-of-memory'
readyStateReasonstring
idstring required

A string holding the unique ID of the deployment

createdAtnumber required

A number containing the date when the deployment was created in milliseconds

readyState'BLOCKED' | 'BUILDING' | 'CANCELED' | 'ERROR' | 'INITIALIZING' | 'QUEUED' | 'READY' required

The state of the deployment depending on the process of deploying, or if it is ready or in an error state

namestring required

The name of the project associated with the deployment at the time that the deployment was created

type'LAMBDAS' required
errorMessagestring nullable
aliasFinalstring nullable
autoAssignCustomDomainsfalse | true

applies to custom domains only, defaults to true

automaticAliasesstring[]
buildErrorAtnumber
checksState'completed' | 'registered' | 'running'
checksConclusion'canceled' | 'failed' | 'skipped' | 'succeeded'
deletedAtnumber nullable

A number containing the date when the deployment was deleted at milliseconds

defaultRoutestring

Computed field that is only available for deployments with a microfrontend configuration.

canceledAtnumber
errorCodestring
errorLinkstring
errorStepstring
passiveRegionsstring[]

Since November 2023 this field defines a set of regions that we will deploy the lambda to passively Lambdas will be deployed to these regions but only invoked if all of the primary regions are marked as out of service

metaobject required
originCacheRegionstring
nodeVersion'10.x' | '12.x' | '14.x' | '16.x' | '18.x' | '20.x' | '22.x' | '24.x' | '8.10.x'

If set it overrides the projectSettings.nodeVersion for this deployment.

prebuiltfalse | true
readySubstate'PROMOTED' | 'ROLLING' | 'STAGED'

Substate of deployment when readyState is 'READY' Tracks whether or not deployment has seen production traffic: - STAGED: never seen production traffic - ROLLING: in the process of having production traffic gradually transitioned. - PROMOTED: has seen production traffic

regionsstring[] required

The regions the deployment exists in

softDeletedByRetentionfalse | true

flag to indicate if the deployment was deleted by retention policy

source'api-trigger-git-deploy' | 'cli' | 'clone/repo' | 'drop' | 'git' | 'import' | 'import/repo' | 'redeploy' | 'v0-web'

Where was the deployment created from. Best-effort guess for metrics only — not authoritative; do not gate behavior on it.

target'production' | 'staging' | 'null' nullable

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.

undeletedAtnumber

A number containing the date when the deployment was undeleted at milliseconds

urlstring required

A string with the unique URL of the deployment

userConfiguredDeploymentIdstring

Since January 2025 User-configured deployment ID for skew protection with pre-built deployments. This is set when users configure a custom deploymentId in their next.config.js file. This allows Next.js to use skew protection even when deployments are pre-built outside of Vercel's build system.

version2 required

The platform version that was used to create the deployment.

projectIdstring required
plan'enterprise' | 'hobby' | 'pro' required
connectBuildsEnabledfalse | true
connectConfigurationIdstring
createdInstring required
functionsobject nullable
monorepoManagerstring nullable
ownerIdstring required
passiveConnectConfigurationIdstring

Since November 2023 this field defines a Secure Compute network that will only be used to deploy passive lambdas to (as in passiveRegions)

Example response

{
  "alias": [],
  "aliasAssigned": true,
  "creator": {
    "uid": "96SnxkFiMyVKsK3pnoHfx3Hz",
    "username": "john-doe"
  },
  "userAliases": [
    "sub1.example.com",
    "sub2.example.com"
  ],
  "id": "dpl_89qyp1cskzkLrVicDaZoDbjyHuDJ",
  "createdAt": 1540257589405,
  "readyState": "READY",
  "name": "my-project",
  "deletedAt": 1540257589405,
  "regions": [
    "sfo1"
  ],
  "source": "cli",
  "undeletedAt": 1540257589405,
  "url": "my-instant-deployment-3ij3cxz9qr.now.sh",
  "userConfiguredDeploymentId": "abc123",
  "version": 2
}

Changes