deployments

Create a new deployment

Changed on

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

Request

  • Base URL: https://api.vercel.com
  • URL: https://api.vercel.com/v13/deployments
  • Auth: HTTP bearer

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

buildMachine'turbo'

Selects a custom build machine for this deployment without changing project settings.

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.

gitAccessTokenstring

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.

metaobject

An object containing the deployment's metadata. Multiple key-value pairs can be attached to a deployment. For deployments created with a Cursor Origin gitSource, Vercel automatically adds cursorOriginDeployment, cursorOriginCommitSha, cursorOriginCommitRef, cursorOriginCommitMessage, cursorOriginCommitAuthorName, cursorOriginCommitAuthorEmail when available, cursorOriginOwner, cursorOriginRepo, cursorOriginRepoId, and cursorOriginPrId for pull request deployments.

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",
    "rootDirectory": "apps/web"
  },
  "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. Returns the reduced deployment view for anonymous (vcn_) callers. Pool-team details are withheld.

OR

Example response

{
  "id": "dpl_89qyp1cskzkLrVicDaZoDbjyHuDJ",
  "readyState": "READY"
}

Changes

  • 2060b55dc517Revision changes
    • warning

      added the new project enum value to the // response property for the response status

  • 74d3a3591515Revision changes
    • breaking

      added subschema #1 subschema #2 to the // response property oneOf list for the response status

    • info

      removed subschema #1 subschema #2 from the // response property oneOf list for the response status