Create a new deployment

APIs & SDKs

POSThttps://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.

https://api.vercel.com/v13/deployments

const response = await fetch('https://api.vercel.com/v13/deployments?forceNew=value&skipAutoDetectionConfirmation=value&teamId=string&slug=string', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "customEnvironmentSlugOrId": "staging",
    "deploymentId": "dpl_2qn7PZrx89yxY34vEZPD31Y9XVj6",
    "files": [
      {
        "data": "string",
        "encoding": "base64",
        "file": "folder/file.js"
      }
    ],
    "gitAccessToken": "string",
    "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",
      "rootDirectory": "apps/web"
    },
    "gitSource": {
      "type": "vercel",
      "sha": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
    },
    "meta": "[object Object]",
    "monorepoManager": "string",
    "name": "my-instant-deployment",
    "project": "my-deployment-project",
    "projectSettings": {
      "buildCommand": "next build",
      "commandForIgnoringBuildStep": "string",
      "devCommand": "string",
      "framework": "null",
      "installCommand": "pnpm install",
      "nodeVersion": "24.x",
      "outputDirectory": "string",
      "rootDirectory": "string",
      "serverlessFunctionRegion": "string",
      "skipGitConnectDuringLink": "true",
      "sourceFilesOutsideRootDirectory": "true"
    },
    "target": "production",
    "withLatestCommit": "true"
  }),
});

const data = await response.json();
console.log(data);

Response

{
  "alias": [],
  "aliasAssigned": "false",
  "id": "dpl_89qyp1cskzkLrVicDaZoDbjyHuDJ",
  "target": "null",
  "readyState": "READY",
  "aliasError": {
    "code": "string",
    "message": "string"
  },
  "aliasWarning": {
    "code": "string",
    "message": "string",
    "link": "string",
    "action": "string"
  },
  "errorCode": "string",
  "errorMessage": "string"
}

Authentication

AuthorizationbearerToken

Default authentication mechanism

Query parameters

forceNewanyOptional

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.

skipAutoDetectionConfirmationanyOptional

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.

teamIdstringOptional

The Team identifier to perform the request on behalf of.

slugstringOptional

The Team slug to perform the request on behalf of.

Body

application/json

customEnvironmentSlugOrIdstringOptional

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

deploymentIdstringOptional

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.

filesarrayOptional

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.

gitAccessTokenstringOptional

Available only to Vercel platform accounts. A read-only GitHub access token scoped to the requested repository. Use a token with a lifetime of 24 hours or less that remains valid until source retrieval completes.

gitMetadataobjectOptional

Populates initial git metadata for different git providers.

gitSourceobjectOptional9 variants

metaobjectOptional

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

monorepoManagerstringOptional

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

namestringRequired

A string with the project name used in the deployment URL

projectstringOptional

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

projectSettingsobjectOptional

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

targetstringOptional

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.

withLatestCommitbooleanOptional

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

200Returns 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.

aliasarrayOptional

aliasAssignedbooleanRequired

idstringRequired

A string holding the unique ID of the deployment

targetstringOptional

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.

readyStatestringRequired

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

aliasErrorobjectOptional

An object that will contain a code and a message when the aliasing fails, otherwise the value will be null

aliasWarningobjectOptional

errorCodestringOptional

errorMessagestringOptional

Errors

400One of the provided values in the request body is invalid. One of the provided values in the request query is invalid.

401The request is not authorized.

402The 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

403You do not have permission to access this resource.

404Error

409The deployment project is being transferred

410Error

426Error

429Error

500Error

503Error

Cross-link map: Create a new deployment (/docs/rest-api/deployments/create-a-new-deployment)

From the Vercel docs graph (built 2026-09-05T06:45:33.488Z), spanning vercel.com docs + KB, nextjs.org, ai-sdk.dev, and other Vercel documentation sites. Full graph as JSON: https://vercel.com/docs/graph.json

Semantically closest pages

Update a Team — PATCH /v2/teams/{teamId} — Update the information of a Team specified by the \teamId\\ parameter. The request body shou
Update a connector — PATCH /v2/connect/connectors/{connector} — Update a connector and return the connector with any service-side update sign
Create a new project — POST /v11/projects — Allows to create a new project with the provided configuration. It only requires the project \`name
Create a new Drain — POST /v1/drains — Create a new Drain with the provided configuration.
List deployments — GET /v7/deployments — List deployments under the authenticated user or team. If a deployment hasn't finished uploading \

This page links to (1)

Vercel REST API Reference — Interact programmatically with your Vercel account using the SDK or direct HTTP requests.

Pages that link here (8)

By site: vercel-changelog (1) · vercel-docs (7)

From vercel-changelog

Vercel for Platforms can now deploy from your users' GitHub repositories

From vercel-docs

Deploying to Vercel — Create, verify, and manage preview and production deployments on Vercel from Git, Vercel CLI, or the REST API.
Claim Deployments — Learn how to take ownership of deployments on Vercel with the Claim Deployments feature.
Troubleshooting Build Errors — Learn how to resolve common scenarios you may encounter during the Build step, including build errors that cancel a depl
Multi-Project Platforms Quickstart — Programmatically host code for user-generated or AI-generated applications on Vercel.
Multi-Project Platforms Reference — API reference, error codes, troubleshooting, and FAQ for multi-project platforms on Vercel.
Vercel REST API Reference — Interact programmatically with your Vercel account using the SDK or direct HTTP requests.
Vercel Documentation Sitemap — Browse Vercel documentation pages with summaries, prerequisites, and topics.

https://api.vercel.com/v13/deployments

const response = await fetch('https://api.vercel.com/v13/deployments?forceNew=value&skipAutoDetectionConfirmation=value&teamId=string&slug=string', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "customEnvironmentSlugOrId": "staging",
    "deploymentId": "dpl_2qn7PZrx89yxY34vEZPD31Y9XVj6",
    "files": [
      {
        "data": "string",
        "encoding": "base64",
        "file": "folder/file.js"
      }
    ],
    "gitAccessToken": "string",
    "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",
      "rootDirectory": "apps/web"
    },
    "gitSource": {
      "type": "vercel",
      "sha": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
    },
    "meta": "[object Object]",
    "monorepoManager": "string",
    "name": "my-instant-deployment",
    "project": "my-deployment-project",
    "projectSettings": {
      "buildCommand": "next build",
      "commandForIgnoringBuildStep": "string",
      "devCommand": "string",
      "framework": "null",
      "installCommand": "pnpm install",
      "nodeVersion": "24.x",
      "outputDirectory": "string",
      "rootDirectory": "string",
      "serverlessFunctionRegion": "string",
      "skipGitConnectDuringLink": "true",
      "sourceFilesOutsideRootDirectory": "true"
    },
    "target": "production",
    "withLatestCommit": "true"
  }),
});

const data = await response.json();
console.log(data);

Response

{
  "alias": [],
  "aliasAssigned": "false",
  "id": "dpl_89qyp1cskzkLrVicDaZoDbjyHuDJ",
  "target": "null",
  "readyState": "READY",
  "aliasError": {
    "code": "string",
    "message": "string"
  },
  "aliasWarning": {
    "code": "string",
    "message": "string",
    "link": "string",
    "action": "string"
  },
  "errorCode": "string",
  "errorMessage": "string"
}

OpenAPI Specification

Build with AI

Deploy & scale

Operate & protect

Resources

Authentication

Query parameters

Body

Response

Errors

Cross-link map: Create a new deployment (/docs/rest-api/deployments/create-a-new-deployment)

Semantically closest pages

This page links to (1)

Pages that link here (8)

From vercel-changelog

From vercel-docs

Cross-link map: Create a new deployment (/docs/rest-api/deployments/create-a-new-deployment)

Semantically closest pages

This page links to (1)

Pages that link here (8)

From vercel-changelog

From vercel-docs