vercel-logotype Logovercel-logotype Logo
deployments
Reference

Deployments

Cancel a deployment

patch/v12/deployments/{id}/cancel

This endpoint allows you to cancel a deployment which is currently building, by supplying its id in the URL.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v12/deployments/dpl_5WJWYSyB7BpgTj3EuwF37WMRBXBtPQ2iTMJHJBJyRfd/cancel?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2
  "headers": {
3
    "Authorization": "Bearer <TOKEN>"
4
  },
5
  "method": "patch"
6
})

Parameters

Path Params
Query Params
Path ParameterDescription

id

string

required
The unique identifier of the deployment.
Example:dpl_5WJWYSyB7BpgTj3EuwF37WMRBXBtPQ2iTMJHJBJyRfd

Response

The private deployment representation of a Deployment.

  • aliasarray
  • aliasAssignedbooleanRequired
  • aliasAssignedAtOne of the following objects or null
  • One of
  • aliasErrorobject or null
  • Properties
  • aliasFinalstring or null
  • aliasWarningobject or null
  • Properties
  • alwaysRefuseToBuildboolean
  • autoAssignCustomDomainsboolean
    applies to custom domains only, defaults to true
  • automaticAliasesarray
  • bootedAtnumberRequired
  • buildobjectRequired
  • Properties
  • buildArtifactUrlsarray
  • buildErrorAtnumber
  • buildSkippedbooleanRequired
  • buildingAtnumberRequired
  • buildsarray
  • canceledAtnumber
  • checksConclusionstring
    One of: skipped | succeeded | failed | canceled
  • checksStatestring
    One of: registered | running | completed
  • connectBuildsEnabledboolean
  • connectConfigurationIdstring
  • createdAtnumberRequired
  • createdInstringRequired
  • creatorobjectRequired
  • Properties
  • cronsarray
  • Properties
  • customEnvironmentOne of the following objects
  • One of
  • defaultRoutestring
    Computed field that is only available for deployments with a microfrontend configuration.
  • deletedAtnumber or null
  • envarrayRequired
  • errorCodestring
  • errorLinkstring
  • errorMessagestring or null
  • errorStepstring
  • flagsOne of the following objects
  • One of
  • functionsobject or null
  • gitRepoOne of the following objects or null
  • One of
  • gitSourceOne of the following objects
  • One of
  • idstringRequired
  • imagesobject
  • Properties
  • initReadyAtnumber
  • inspectorUrlstring or nullRequired
  • integrationsobject
  • Properties
  • isFirstBranchDeploymentboolean
  • isInConcurrentBuildsQueuebooleanRequired
  • isInSystemBuildsQueuebooleanRequired
  • lambdasarray
  • Properties
  • metaobjectRequired
  • microfrontendsOne of the following objects
  • One of
  • monorepoManagerstring or null
  • namestringRequired
  • oidcTokenClaimsobject
  • Properties
  • originCacheRegionstring
  • ownerIdstringRequired
  • passiveConnectConfigurationIdstring
    Since November 2023 this field defines a Secure Compute network that will only be used to deploy passive lambdas to (as in passiveRegions)
  • passiveRegionsarray
    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
  • planstringRequired
    One of: pro | enterprise | hobby
  • previewCommentsEnabledboolean
  • projectobject
  • Properties
  • projectIdstringRequired
  • projectSettingsobjectRequired
  • Properties
  • publicbooleanRequired
  • readynumber
  • readyStatestringRequired
    One of: BUILDING | ERROR | INITIALIZING | QUEUED | READY | CANCELED
  • readyStateReasonstring
  • readySubstatestring
    One of: STAGED | PROMOTED
    Since June 2023 Substate of deployment when readyState is 'READY' Tracks whether or not deployment has seen production traffic: - STAGED: never seen production traffic - PROMOTED: has seen production traffic
  • regionsarrayRequired
  • routesarray or nullRequired

    • One of:

  • Properties
  • Properties
  • Properties
  • softDeletedByRetentionboolean
  • sourcestring
    One of: api-trigger-git-deploy | cli | clone/repo | git | import | import/repo | redeploy | v0-web
  • statusstringRequired
    One of: BUILDING | ERROR | INITIALIZING | QUEUED | READY | CANCELED
  • targetstring or null
    One of: production | staging
  • teamobject
  • Properties
  • ttyBuildLogsboolean
  • typestringRequired
    One of: LAMBDAS
  • undeletedAtnumber
  • urlstringRequired
  • userAliasesarray
  • versionnumberRequired
    One of: 2

Response Codes

CodeDescription
200
400One of the provided values in the request query is invalid.
401
403You do not have permission to access this resource.
404

Create a new deployment

post/v13/deployments

Create a new deployment with all the required and intended data. If the deployment is not a git deployment, all files must be provided with the request, either referenced or inlined. Additionally, a deployment id can be specified to redeploy a previous deployment.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v13/deployments?forceNew=0&skipAutoDetectionConfirmation=0&slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2
  "body": {
3
    "name": "my-instant-deployment",
4
    "deploymentId": "SOME_STRING_VALUE",
5
    "files": [
6
      {
7
        "InlinedFile": {
8
          "data": "SOME_STRING_VALUE",
9
          "encoding": "base64",
10
          "file": "folder/file.js"
11
        }
12
      }
13
    ],
14
    "gitMetadata": {
15
      "remoteUrl": "https://github.com/vercel/next.js",
16
      "commitAuthorName": "kyliau",
17
      "commitMessage": "add method to measure Interaction to Next Paint (INP) (#36490)",
18
      "commitRef": "main",
19
      "commitSha": "dc36199b2234c6586ebe05ec94078a895c707e29",
20
      "dirty": true
21
    },
22
    "gitSource": {
23
      "ref": "SOME_STRING_VALUE",
24
      "repoId": "",
25
      "sha": "SOME_STRING_VALUE",
26
      "type": "github"
27
    },
28
    "meta": "{foo:bar}",
29
    "monorepoManager": "SOME_STRING_VALUE",
30
    "project": "my-deployment-project",
31
    "projectSettings": {
32
      "buildCommand": "SOME_STRING_VALUE",
33
      "commandForIgnoringBuildStep": "SOME_STRING_VALUE",
34
      "devCommand": "SOME_STRING_VALUE",
35
      "framework": "blitzjs",
36
      "installCommand": "SOME_STRING_VALUE",
37
      "nodeVersion": "22.x",
38
      "outputDirectory": "SOME_STRING_VALUE",
39
      "rootDirectory": "SOME_STRING_VALUE",
40
      "serverlessFunctionRegion": "SOME_STRING_VALUE",
41
      "skipGitConnectDuringLink": true,
42
      "sourceFilesOutsideRootDirectory": true
43
    },
44
    "target": "staging",
45
    "withLatestCommit": true
46
  },
47
  "headers": {
48
    "Authorization": "Bearer <TOKEN>"
49
  },
50
  "method": "post"
51
})

Parameters

Query Params
Body Params
Query ParameterDescription

forceNew

string of the following

Forces a new deployment even if there is a previous similar deployment
Allowed values:01

skipAutoDetectionConfirmation

string of the following

Allows to skip framework detection so the API would not fail to ask for confirmation
Allowed values:01

slug

string

The Team slug to perform the request on behalf of.

teamId

string

The Team identifier to perform the request on behalf of.

Response

The successfully created deployment

  • aliasarray
  • aliasAssignedbooleanRequired
  • aliasAssignedAtOne of the following objects or null
  • One of
  • aliasErrorobject or null
  • Properties
  • aliasFinalstring or null
  • aliasWarningobject or null
  • Properties
  • alwaysRefuseToBuildboolean
  • autoAssignCustomDomainsboolean
    applies to custom domains only, defaults to true
  • automaticAliasesarray
  • bootedAtnumberRequired
  • buildobjectRequired
  • Properties
  • buildArtifactUrlsarray
  • buildErrorAtnumber
  • buildSkippedbooleanRequired
  • buildingAtnumberRequired
  • buildsarray
  • canceledAtnumber
  • checksConclusionstring
    One of: succeeded | failed | skipped | canceled
  • checksStatestring
    One of: registered | running | completed
  • connectBuildsEnabledboolean
  • connectConfigurationIdstring
  • createdAtnumberRequired
  • createdInstringRequired
  • creatorobjectRequired
  • Properties
  • cronsarray
  • Properties
  • customEnvironmentOne of the following objects
  • One of
  • defaultRoutestring
    Computed field that is only available for deployments with a microfrontend configuration.
  • deletedAtnumber or null
  • envarrayRequired
  • errorCodestring
  • errorLinkstring
  • errorMessagestring or null
  • errorStepstring
  • flagsOne of the following objects
  • One of
  • functionsobject or null
  • gitRepoOne of the following objects or null
  • One of
  • gitSourceOne of the following objects
  • One of
  • idstringRequired
  • imagesobject
  • Properties
  • initReadyAtnumber
  • inspectorUrlstring or nullRequired
  • integrationsobject
  • Properties
  • isFirstBranchDeploymentboolean
  • isInConcurrentBuildsQueuebooleanRequired
  • isInSystemBuildsQueuebooleanRequired
  • lambdasarray
  • Properties
  • metaobjectRequired
  • microfrontendsOne of the following objects
  • One of
  • monorepoManagerstring or null
  • namestringRequired
  • oidcTokenClaimsobject
  • Properties
  • originCacheRegionstring
  • ownerIdstringRequired
  • passiveConnectConfigurationIdstring
    Since November 2023 this field defines a Secure Compute network that will only be used to deploy passive lambdas to (as in passiveRegions)
  • passiveRegionsarray
    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
  • planstringRequired
    One of: pro | enterprise | hobby
  • previewCommentsEnabledboolean
  • projectobject
  • Properties
  • projectIdstringRequired
  • projectSettingsobjectRequired
  • Properties
  • publicbooleanRequired
  • readynumber
  • readyStatestringRequired
    One of: CANCELED | ERROR | QUEUED | BUILDING | INITIALIZING | READY
  • readyStateReasonstring
  • readySubstatestring
    One of: STAGED | PROMOTED
    Since June 2023 Substate of deployment when readyState is 'READY' Tracks whether or not deployment has seen production traffic: - STAGED: never seen production traffic - PROMOTED: has seen production traffic
  • regionsarrayRequired
  • routesarray or nullRequired

    • One of:

  • Properties
  • Properties
  • Properties
  • softDeletedByRetentionboolean
  • sourcestring
    One of: cli | git | import | import/repo | clone/repo | api-trigger-git-deploy | redeploy | v0-web
  • statusstringRequired
    One of: CANCELED | ERROR | QUEUED | BUILDING | INITIALIZING | READY
  • targetstring or null
    One of: staging | production
  • teamobject
  • Properties
  • ttyBuildLogsboolean
  • typestringRequired
    One of: LAMBDAS
  • undeletedAtnumber
  • urlstringRequired
  • userAliasesarray
  • versionnumberRequired
    One of: 2

Response Codes

CodeDescription
200The successfully created deployment
400

  • One of the provided values in the request body is invalid.

  • One of the provided values in the request query is invalid.

401
402

  • The account was soft-blocked for an unhandled reason.

  • The account is missing a payment so payment method must be updated

  • Pro customers are allowed to deploy Serverless Functions to up to PRO_CUSTOMERS_MAX_REGIONS 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.
404
409The deployment project is being transferred

Delete a Deployment

delete/v13/deployments/{id}

This API allows you to delete a deployment, either by supplying its id in the URL or the url of the deployment as a query parameter. You can obtain the ID, for example, by listing all deployments.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v13/deployments/dpl_5WJWYSyB7BpgTj3EuwF37WMRBXBtPQ2iTMJHJBJyRfd?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE&url=https://files-orcin-xi.vercel.app/", {
2
  "headers": {
3
    "Authorization": "Bearer <TOKEN>"
4
  },
5
  "method": "delete"
6
})

Parameters

Path Params
Query Params
Path ParameterDescription

id

string

required
The ID of the deployment to be deleted
Example:dpl_5WJWYSyB7BpgTj3EuwF37WMRBXBtPQ2iTMJHJBJyRfd

Response

  • statestringRequired
    One of: DELETED
    A constant with the final state of the deployment.
  • uidstringRequired
    The removed deployment ID.

    Example: dpl_5WJWYSyB7BpgTj3EuwF37WMRBXBtPQ2iTMJHJBJyRfd

Response Codes

CodeDescription
200The deployment was successfully deleted
400One of the provided values in the request query is invalid.
401
403You do not have permission to access this resource.
404The deployment was not found

Get a deployment by ID or URL

get/v13/deployments/{idOrUrl}

Retrieves information for a deployment either by supplying its ID (id property) or Hostname (url property). Additional details will be included when the authenticated user or team is an owner of the deployment.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v13/deployments/dpl_89qyp1cskzkLrVicDaZoDbjyHuDJ?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE&withGitRepoInfo=true", {
2
  "headers": {
3
    "Authorization": "Bearer <TOKEN>"
4
  },
5
  "method": "get"
6
})

Parameters

Path Params
Query Params
Path ParameterDescription

idOrUrl

string

required
The unique identifier or hostname of the deployment.
Example:dpl_89qyp1cskzkLrVicDaZoDbjyHuDJ

Response

  • One of the following objects
  • One of

Response Codes

CodeDescription
200

  • The deployment including only public information

  • The deployment including both public and private information

400One of the provided values in the request query is invalid.
403You do not have permission to access this resource.
404The deployment was not found

Get deployment events

get/v3/deployments/{idOrUrl}/events

Get the build logs of a deployment by deployment ID and build ID. It can work as an infinite stream of logs or as a JSON endpoint depending on the input parameters.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v3/deployments/dpl_5WJWYSyB7BpgTj3EuwF37WMRBXBtPQ2iTMJHJBJyRfd/events?builds=1&delimiter=1&direction=backward&follow=1&limit=100&name=bld_cotnkcr76&since=1540095775941&slug=SOME_STRING_VALUE&statusCode=5xx&teamId=SOME_STRING_VALUE&until=1540106318643", {
2
  "headers": {
3
    "Authorization": "Bearer <TOKEN>"
4
  },
5
  "method": "get"
6
})

Parameters

Path Params
Query Params
Path ParameterDescription

idOrUrl

string

required
The unique identifier or hostname of the deployment.
Example:dpl_5WJWYSyB7BpgTj3EuwF37WMRBXBtPQ2iTMJHJBJyRfd

Response

None

Response Codes

CodeDescription
400One of the provided values in the request query is invalid.
401
403You do not have permission to access this resource.
500

Get Deployment File Contents

get/v7/deployments/{id}/files/{fileId}

Allows to retrieve the content of a file by supplying the file identifier and the deployment unique identifier. The response body will contain a JSON response containing the contents of the file encoded as base64.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v7/deployments/SOME_STRING_VALUE/files/SOME_STRING_VALUE?path=SOME_STRING_VALUE&slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2
  "headers": {
3
    "Authorization": "Bearer <TOKEN>"
4
  },
5
  "method": "get"
6
})

Parameters

Path Params
Query Params
Path ParameterDescription

fileId

string

required
The unique file identifier

id

string

required
The unique deployment identifier

Response

None

Response Codes

CodeDescription
400One of the provided values in the request query is invalid.
401
403You do not have permission to access this resource.
404

  • File not found

  • Deployment not found

410Invalid API version.

List deployments

get/v6/deployments

List deployments under the authenticated user or team. If a deployment hasn't finished uploading (is incomplete), the url property will have a value of null.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v6/deployments?app=docs&from=1612948664566&limit=10&projectId=QmXGTs7mvAMMC7WW5ebrM33qKG32QK3h4vmQMjmY&rollbackCandidate=true&since=1540095775941&slug=SOME_STRING_VALUE&state=BUILDING,READY&target=production&teamId=SOME_STRING_VALUE&to=1612948664566&until=1540095775951&users=kr1PsOIzqEL5Xg6M4VZcZosf,K4amb7K9dAt5R2vBJWF32bmY", {
2
  "headers": {
3
    "Authorization": "Bearer <TOKEN>"
4
  },
5
  "method": "get"
6
})

Parameters

Query Params
Query ParameterDescription

app

string

Name of the deployment.
Example:docs

from

number

deprecated
Gets the deployment created after this Date timestamp. (default: current time)
Example:1612948664566

limit

number

Maximum number of deployments to list from a request.
Example:10

projectId

string

Filter deployments from the given ID or name.
Example:QmXGTs7mvAMMC7WW5ebrM33qKG32QK3h4vmQMjmY

rollbackCandidate

boolean

Filter deployments based on their rollback candidacy

since

number

Get Deployments created after this JavaScript timestamp.
Example:1540095775941

slug

string

The Team slug to perform the request on behalf of.

state

string

Filter deployments based on their state (BUILDING, ERROR, INITIALIZING, QUEUED, READY, CANCELED)
Example:BUILDING,READY

target

string

Filter deployments based on the environment.
Example:production

teamId

string

The Team identifier to perform the request on behalf of.

to

number

deprecated
Gets the deployment created before this Date timestamp. (default: current time)
Example:1612948664566

until

number

Get Deployments created before this JavaScript timestamp.
Example:1540095775951

users

string

Filter out deployments based on users who have created the deployment.
Example:kr1PsOIzqEL5Xg6M4VZcZosf,K4amb7K9dAt5R2vBJWF32bmY

Response

  • deploymentsarrayRequired
  • Properties
  • paginationRequired

Response Codes

CodeDescription
200
400One of the provided values in the request query is invalid.
401
403You do not have permission to access this resource.
404
422

List Deployment Files

get/v6/deployments/{id}/files

Allows to retrieve the file structure of a deployment by supplying the deployment unique identifier.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v6/deployments/SOME_STRING_VALUE/files?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2
  "headers": {
3
    "Authorization": "Bearer <TOKEN>"
4
  },
5
  "method": "get"
6
})

Parameters

Path Params
Query Params
Path ParameterDescription

id

string

required
The unique deployment identifier

Response

  • array
  • Array

Response Codes

CodeDescription
200Retrieved the file tree successfully
400One of the provided values in the request query is invalid.
401
403You do not have permission to access this resource.
404

  • File tree not found

  • Deployment not found

Upload Deployment Files

post/v2/files

Before you create a deployment you need to upload the required files for that deployment. To do it, you need to first upload each file to this endpoint. Once that's completed, you can create a new deployment with the uploaded files. The file content must be placed inside the body of the request. In the case of a successful response you'll receive a status code 200 with an empty body.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v2/files?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2
  "headers": {
3
    "Authorization": "Bearer <TOKEN>",
4
    "Content-Length": "SOME_NUMBER_VALUE",
5
    "x-now-digest": "SOME_STRING_VALUE",
6
    "x-now-size": "SOME_NUMBER_VALUE",
7
    "x-vercel-digest": "SOME_STRING_VALUE"
8
  },
9
  "method": "post"
10
})

Parameters

Query Params
Header Params
Query ParameterDescription

slug

string

The Team slug to perform the request on behalf of.

teamId

string

The Team identifier to perform the request on behalf of.

Response

  • One of the following objects
  • One of

Response Codes

CodeDescription
200

  • File already uploaded

  • File successfully uploaded

400

  • One of the provided values in the headers is invalid

  • Digest is not valid

  • File size is not valid

401
403You do not have permission to access this resource.
Last updated on December 20, 2024
Previous
Update a check
Next
Cancel a deployment