projects
Reference
10 min read

Projects

Add a domain to a project

post/v10/projects/{idOrName}/domains

Add a domain to the project by passing its domain name and by specifying the project by either passing the project id or name in the URL. If the domain is not yet verified to be used on this project, the request will return verified = false, and the domain will need to be verified according to the verification challenge via POST /projects/:idOrName/domains/:domain/verify. If the domain already exists on the project, the request will fail with a 400 status code.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v10/projects/SOME_STRING_VALUE/domains?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2
  "body": {
3
    "name": "www.example.com",
4
    "gitBranch": "SOME_STRING_VALUE",
5
    "redirect": "foobar.com",
6
    "redirectStatusCode": 307
7
  },
8
  "headers": {
9
    "Authorization": "Bearer <TOKEN>"
10
  },
11
  "method": "post"
12
})

Parameters

Path Params
Query Params
Body Params
Path ParameterDescription

idOrName

string

required
The unique project identifier or the project name

Response

  • apexNamestringRequired
  • createdAtnumber
  • gitBranchstring or null
  • namestringRequired
  • projectIdstringRequired
  • redirectstring or null
  • redirectStatusCodenumber or null
    One of: 307 | 301 | 302 | 308
  • updatedAtnumber
  • verificationarray
    A list of verification challenges, one of which must be completed to verify the domain for use on the project. After the challenge is complete POST /projects/:idOrName/domains/:domain/verify to verify the domain. Possible challenges: - If verification.type = TXT the verification.domain will be checked for a TXT record matching verification.value.
  • Properties
  • verifiedbooleanRequired
    true if the domain is verified for use with the project. If false it will not be used as an alias on this project until the challenge in verification is completed.

Response Codes

CodeDescription
200The domain was successfully added to the project
400

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

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

  • The domain is not valid

  • You can't set both a git branch and a redirect for the domain

  • The domain can not be added because the latest production deployment for the project was not successful

  • The domain redirect is not valid

  • A domain cannot redirect to itself

  • You can not set the production branch as a branch for your domain

401
402

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

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

403

  • You do not have permission to access this resource.

  • You don't have access to the domain you are adding

409

  • The domain is already assigned to another Vercel project

  • Cannot create project domain since owner already has domain on their account

  • Cannot create project domain if the current verified domain

  • The domain is not allowed to be used

  • The project is currently being transferred

Create a new project

post/v10/projects

Allows to create a new project with the provided configuration. It only requires the project name but more configuration can be provided to override the defaults.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v10/projects?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2
  "body": {
3
    "name": "a-project-name",
4
    "buildCommand": "SOME_STRING_VALUE",
5
    "commandForIgnoringBuildStep": "SOME_STRING_VALUE",
6
    "devCommand": "SOME_STRING_VALUE",
7
    "environmentVariables": [
8
      {
9
        "key": "SOME_STRING_VALUE",
10
        "target": "production",
11
        "gitBranch": "SOME_STRING_VALUE",
12
        "type": "system",
13
        "value": "SOME_STRING_VALUE"
14
      }
15
    ],
16
    "framework": "nextjs",
17
    "gitRepository": {
18
      "repo": "SOME_STRING_VALUE",
19
      "type": "github"
20
    },
21
    "installCommand": "SOME_STRING_VALUE",
22
    "outputDirectory": "SOME_STRING_VALUE",
23
    "publicSource": true,
24
    "rootDirectory": "SOME_STRING_VALUE",
25
    "serverlessFunctionRegion": "SOME_STRING_VALUE",
26
    "serverlessFunctionZeroConfigFailover": "ANY_TYPE_VALUE",
27
    "skipGitConnectDuringLink": true
28
  },
29
  "headers": {
30
    "Authorization": "Bearer <TOKEN>"
31
  },
32
  "method": "post"
33
})

Parameters

Query Params
Body 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

  • accountIdstringRequired
  • analyticsobject
  • Properties
  • autoAssignCustomDomainsboolean
  • autoAssignCustomDomainsUpdatedBystring
  • autoExposeSystemEnvsboolean
  • buildCommandstring or null
  • commandForIgnoringBuildStepstring or null
  • concurrencyBucketNamestring
  • connectBuildsEnabledboolean
  • connectConfigurationIdstring or null
  • createdAtnumber
  • cronsobject
  • Properties
  • customerSupportCodeVisibilityboolean
  • dataCacheobject
  • Properties
  • devCommandstring or null
  • directoryListingbooleanRequired
  • enablePreviewFeedbackboolean or null
  • envarray
  • Properties
  • frameworkstring or null
    One of: blitzjs | nextjs | gatsby | remix | astro | hexo | eleventy | docusaurus-2 | docusaurus | preact | solidstart-1 | solidstart | dojo | ember | vue | scully | ionic-angular | angular | polymer | svelte | sveltekit | sveltekit-1 | ionic-react | create-react-app | gridsome | umijs | sapper | saber | stencil | nuxtjs | redwoodjs | hugo | jekyll | brunch | middleman | zola | hydrogen | vite | vitepress | vuepress | parcel | sanity | storybook
  • gitCommentsobject
  • Properties
  • gitForkProtectionboolean
  • gitLFSboolean
  • hasActiveBranchesboolean
  • hasFloatingAliasesboolean
  • idstringRequired
  • installCommandstring or null
  • lastAliasRequestobject or null
  • Properties
  • lastRollbackTargetobject or null
  • latestDeploymentsarray
  • Properties
  • linkOne of the following objects
  • One of
  • liveboolean
  • namestringRequired
  • nodeVersionstringRequired
    One of: 20.x | 18.x | 16.x | 14.x | 12.x | 10.x | 8.10.x
  • oidcTokenConfigobject
  • Properties
  • outputDirectorystring or null
  • passiveConnectConfigurationIdstring or null
  • passwordProtectionobject or null
  • pausedboolean
  • permissionsobject
  • Properties
  • productionDeploymentsFastLaneboolean
  • protectionBypassobject
  • publicSourceboolean or null
  • rootDirectorystring or null
  • securityobject
  • Properties
  • serverlessFunctionRegionstring or null
  • serverlessFunctionZeroConfigFailoverboolean
  • skewProtectionBoundaryAtnumber
  • skewProtectionMaxAgenumber
  • skipGitConnectDuringLinkboolean
  • sourceFilesOutsideRootDirectoryboolean
  • speedInsightsobject
  • Properties
  • ssoProtectionobject or null
  • Properties
  • targetsobject
  • One of
  • transferCompletedAtnumber
  • transferStartedAtnumber
  • transferToAccountIdstring
  • transferredFromAccountIdstring
  • trustedIpsOne of the following objects or null
  • One of
  • updatedAtnumber
  • webAnalyticsobject
  • Properties

Response Codes

CodeDescription
200The project was successfuly created
400

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

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

  • The Bitbucket Webhook for the project link could not be created

  • The Gitlab Webhook for the project link could not be created

401
402

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

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

403You do not have permission to access this resource.
409A project with the provided name already exists.

Create one or more environment variables

post/v10/projects/{idOrName}/env

Create one ore more environment variables for a project by passing its key, value, type and target and by specifying the project by either passing the project id or name in the URL.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v10/projects/prj_XLKmu1DyR1eY7zq8UgeRKbA7yVLA/env?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE&upsert=true", {
2
  "body": {
3
    "key": "API_URL",
4
    "value": "https://api.vercel.com",
5
    "type": "plain",
6
    "target": [
7
      "preview"
8
    ],
9
    "gitBranch": "feature-1",
10
    "comment": "database connection string for production"
11
  },
12
  "headers": {
13
    "Authorization": "Bearer <TOKEN>"
14
  },
15
  "method": "post"
16
})

Parameters

Path Params
Query Params
Body Params
Path ParameterDescription

idOrName

string

required
The unique project identifier or the project name
Example:prj_XLKmu1DyR1eY7zq8UgeRKbA7yVLA

Response

  • createdRequiredOne of the following objects
  • One of
  • failedarrayRequired
  • Properties

Response Codes

CodeDescription
201The environment variable was created successfully
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

403

  • You do not have permission to access this resource.

  • The environment variable cannot be created because it already exists

  • Additional permissions are required to create production environment variables

409The project is being transfered and creating an environment variable is not possible

Delete a Project

delete/v9/projects/{idOrName}

Delete a specific project by passing either the project id or name in the URL.

Optional params

fetch-request

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

Parameters

Path Params
Query Params
Path ParameterDescription

idOrName

string

required
The unique project identifier or the project name
Example:prj_12HKQaOmR5t5Uy6vdcQsNIiZgHGB

Response

The project was successfuly removed

Response Codes

CodeDescription
204The project was successfuly removed
400One of the provided values in the request query is invalid.
401
403You do not have permission to access this resource.
409

Edit an environment variable

patch/v9/projects/{idOrName}/env/{id}

Edit a specific environment variable for a given project by passing the environment variable identifier and either passing the project id or name in the URL.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v9/projects/prj_XLKmu1DyR1eY7zq8UgeRKbA7yVLA/env/XMbOEya1gUUO1ir4?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2
  "body": {
3
    "comment": "database connection string for production",
4
    "gitBranch": "feature-1",
5
    "key": "GITHUB_APP_ID",
6
    "target": "[preview]",
7
    "type": "plain",
8
    "value": "bkWIjbnxcvo78"
9
  },
10
  "headers": {
11
    "Authorization": "Bearer <TOKEN>"
12
  },
13
  "method": "patch"
14
})

Parameters

Path Params
Query Params
Body Params
Path ParameterDescription

id

string

required
The unique environment variable identifier
Example:XMbOEya1gUUO1ir4

idOrName

string

required
The unique project identifier or the project name
Example:prj_XLKmu1DyR1eY7zq8UgeRKbA7yVLA

Response

  • commentstring
  • configurationIdstring or null
  • contentHintOne of the following objects or null
  • One of
  • createdAtnumber
  • createdBystring or null
  • customEnvironmentIdstring
  • decryptedboolean
    Whether value is decrypted.
  • edgeConfigIdstring or null
  • edgeConfigTokenIdstring or null
  • gitBranchstring
  • idstring
  • internalContentHintobject or null
    Similar to contentHints, but should not be exposed to the user.
  • Properties
  • keystringRequired
  • targetOne of the following objects
  • One of
  • typestringRequired
    One of: system | encrypted | plain | sensitive | secret
  • updatedAtnumber
  • updatedBystring or null
  • valuestringRequired

Response Codes

CodeDescription
200The environment variable was successfully edited
400

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

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

401
403You do not have permission to access this resource.
409The project is being transfered and removing an environment variable is not possible

Retrieve the environment variables of a project by id or name

get/v9/projects/{idOrName}/env

Retrieve the environment variables for a given project by passing either the project id or name in the URL.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v9/projects/prj_XLKmu1DyR1eY7zq8UgeRKbA7yVLA/env?decrypt=true&gitBranch=feature-1&slug=SOME_STRING_VALUE&source=vercel-cli:pull&teamId=SOME_STRING_VALUE", {
2
  "headers": {
3
    "Authorization": "Bearer <TOKEN>"
4
  },
5
  "method": "get"
6
})

Parameters

Path Params
Query Params
Path ParameterDescription

idOrName

string

required
The unique project identifier or the project name
Example:prj_XLKmu1DyR1eY7zq8UgeRKbA7yVLA

Response

  • One of the following objects
  • One of

Response Codes

CodeDescription
200The list of environment variables for the given project
400One of the provided values in the request query is invalid.
401
403You do not have permission to access this resource.

Find a project by id or name

get/v9/projects/{idOrName}

Get the information for a specific project by passing either the project id or name in the URL.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v9/projects/SOME_STRING|BOOLEAN_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

idOrName

string | boolean of the following

required
The unique project identifier or the project name
type: string
type: boolean

Response

  • accountIdstringRequired
  • analyticsobject
  • Properties
  • autoAssignCustomDomainsboolean
  • autoAssignCustomDomainsUpdatedBystring
  • autoExposeSystemEnvsboolean
  • buildCommandstring or null
  • commandForIgnoringBuildStepstring or null
  • concurrencyBucketNamestring
  • connectBuildsEnabledboolean
  • connectConfigurationIdstring or null
  • createdAtnumber
  • cronsobject
  • Properties
  • customerSupportCodeVisibilityboolean
  • dataCacheobject
  • Properties
  • devCommandstring or null
  • directoryListingbooleanRequired
  • enablePreviewFeedbackboolean or null
  • envarray
  • Properties
  • frameworkstring or null
    One of: blitzjs | nextjs | gatsby | remix | astro | hexo | eleventy | docusaurus-2 | docusaurus | preact | solidstart-1 | solidstart | dojo | ember | vue | scully | ionic-angular | angular | polymer | svelte | sveltekit | sveltekit-1 | ionic-react | create-react-app | gridsome | umijs | sapper | saber | stencil | nuxtjs | redwoodjs | hugo | jekyll | brunch | middleman | zola | hydrogen | vite | vitepress | vuepress | parcel | sanity | storybook
  • gitCommentsobject
  • Properties
  • gitForkProtectionboolean
  • gitLFSboolean
  • hasActiveBranchesboolean
  • hasFloatingAliasesboolean
  • idstringRequired
  • installCommandstring or null
  • lastAliasRequestobject or null
  • Properties
  • lastRollbackTargetobject or null
  • latestDeploymentsarray
  • Properties
  • linkOne of the following objects
  • One of
  • liveboolean
  • namestringRequired
  • nodeVersionstringRequired
    One of: 20.x | 18.x | 16.x | 14.x | 12.x | 10.x | 8.10.x
  • oidcTokenConfigobject
  • Properties
  • outputDirectorystring or null
  • passiveConnectConfigurationIdstring or null
  • passwordProtectionobject or null
  • pausedboolean
  • permissionsobject
  • Properties
  • productionDeploymentsFastLaneboolean
  • protectionBypassobject
  • publicSourceboolean or null
  • rootDirectorystring or null
  • securityobject
  • Properties
  • serverlessFunctionRegionstring or null
  • serverlessFunctionZeroConfigFailoverboolean
  • skewProtectionBoundaryAtnumber
  • skewProtectionMaxAgenumber
  • skipGitConnectDuringLinkboolean
  • sourceFilesOutsideRootDirectoryboolean
  • speedInsightsobject
  • Properties
  • ssoProtectionobject or null
  • Properties
  • targetsobject
  • One of
  • transferCompletedAtnumber
  • transferStartedAtnumber
  • transferToAccountIdstring
  • transferredFromAccountIdstring
  • trustedIpsOne of the following objects or null
  • One of
  • updatedAtnumber
  • webAnalyticsobject
  • Properties

Response Codes

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

Get a project domain

get/v9/projects/{idOrName}/domains/{domain}

Get project domain by project id/name and domain name.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v9/projects/SOME_STRING_VALUE/domains/www.example.com?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

domain

string

required
The project domain name
Example:www.example.com

idOrName

string

required
The unique project identifier or the project name

Response

  • apexNamestringRequired
  • createdAtnumber
  • gitBranchstring or null
  • namestringRequired
  • projectIdstringRequired
  • redirectstring or null
  • redirectStatusCodenumber or null
    One of: 307 | 301 | 302 | 308
  • updatedAtnumber
  • verificationarray
    A list of verification challenges, one of which must be completed to verify the domain for use on the project. After the challenge is complete POST /projects/:idOrName/domains/:domain/verify to verify the domain. Possible challenges: - If verification.type = TXT the verification.domain will be checked for a TXT record matching verification.value.
  • Properties
  • verifiedbooleanRequired
    true if the domain is verified for use with the project. If false it will not be used as an alias on this project until the challenge in verification is completed.

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.

Retrieve project domains by project by id or name

get/v9/projects/{idOrName}/domains

Retrieve the domains associated with a given project by passing either the project id or name in the URL.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v9/projects/SOME_STRING|INTEGER_VALUE/domains?gitBranch=SOME_STRING_VALUE&limit=20&order=ASC&production=true&redirect=example.com&redirects=true&since=1609499532000&slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE&until=1612264332000&verified=true", {
2
  "headers": {
3
    "Authorization": "Bearer <TOKEN>"
4
  },
5
  "method": "get"
6
})

Parameters

Path Params
Query Params
Path ParameterDescription

idOrName

string | integer of the following

required
The unique project identifier or the project name
type: string
type: integer

Response

  • domainsarrayRequired
  • Properties
  • paginationRequired

Response Codes

CodeDescription
200Successful response retrieving a list of domains
400One of the provided values in the request query is invalid.
401
403You do not have permission to access this resource.

Retrieve the decrypted value of an environment variable of a project by id

get/v1/projects/{idOrName}/env/{id}

Retrieve the environment variable for a given project.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v1/projects/prj_XLKmu1DyR1eY7zq8UgeRKbA7yVLA/env/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

id

string

required
The unique ID for the environment variable to get the decrypted value.

idOrName

string

required
The unique project identifier or the project name
Example:prj_XLKmu1DyR1eY7zq8UgeRKbA7yVLA

Response

  • One of the following objects
  • One of

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.

Retrieve a list of projects

get/v9/projects

Allows to retrieve the list of projects of the authenticated user or team. The list will be paginated and the provided query parameters allow filtering the returned projects.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v9/projects?deprecated=true&edgeConfigId=SOME_STRING_VALUE&edgeConfigTokenId=SOME_STRING_VALUE&excludeRepos=SOME_STRING_VALUE&from=SOME_STRING_VALUE&gitForkProtection=1&limit=SOME_STRING_VALUE&repo=SOME_STRING_VALUE&repoId=SOME_STRING_VALUE&repoUrl=https://github.com/vercel/next.js&search=SOME_STRING_VALUE&slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2
  "headers": {
3
    "Authorization": "Bearer <TOKEN>"
4
  },
5
  "method": "get"
6
})

Parameters

Query Params
Query ParameterDescription

deprecated

boolean

edgeConfigId

string

Filter results by connected Edge Config ID

edgeConfigTokenId

string

Filter results by connected Edge Config Token ID

excludeRepos

string

Filter results by excluding those projects that belong to a repo

from

string

Query only projects updated after the given timestamp

gitForkProtection

string of the following

Specifies whether PRs from Git forks should require a team member's authorization before it can be deployed
Example:1
Allowed values:10

limit

string

Limit the number of projects returned

repo

string

Filter results by repo. Also used for project count

repoId

string

Filter results by Repository ID.

repoUrl

string

Filter results by Repository URL.
Example:https://github.com/vercel/next.js

search

string

Search projects by the name field

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 paginated list of projects

  • paginationRequired
  • projectsarrayRequired
  • Properties

Response Codes

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

Pause a project

post/v1/projects/{projectId}/pause

Pause a project by passing its project id in the URL. If the project does not exist given the id then the request will fail with 400 status code. If the project disables auto assigning custom production domains and blocks the active Production Deployment then the request will return with 200 status code.

Optional params

fetch-request

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

Parameters

Path Params
Query Params
Path ParameterDescription

projectId

string

required
The unique project identifier

Response

N/A

Response Codes

CodeDescription
200
400One 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

403You do not have permission to access this resource.
500

Remove a domain from a project

delete/v9/projects/{idOrName}/domains/{domain}

Remove a domain from a project by passing the domain name and by specifying the project by either passing the project id or name in the URL.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v9/projects/SOME_STRING_VALUE/domains/www.example.com?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2
  "headers": {
3
    "Authorization": "Bearer <TOKEN>"
4
  },
5
  "method": "delete"
6
})

Parameters

Path Params
Query Params
Path ParameterDescription

domain

string

required
The project domain name
Example:www.example.com

idOrName

string

required
The unique project identifier or the project name

Response

  • object

Response Codes

CodeDescription
200The domain was succesfully removed from the project
400One of the provided values in the request query is invalid.
401
403You do not have permission to access this resource.
404
409The project is currently being transferred

Remove an environment variable

delete/v9/projects/{idOrName}/env/{id}

Delete a specific environment variable for a given project by passing the environment variable identifier and either passing the project id or name in the URL.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v9/projects/prj_XLKmu1DyR1eY7zq8UgeRKbA7yVLA/env/XMbOEya1gUUO1ir4?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2
  "headers": {
3
    "Authorization": "Bearer <TOKEN>"
4
  },
5
  "method": "delete"
6
})

Parameters

Path Params
Query Params
Path ParameterDescription

id

string

required
The unique environment variable identifier
Example:XMbOEya1gUUO1ir4

idOrName

string

required
The unique project identifier or the project name
Example:prj_XLKmu1DyR1eY7zq8UgeRKbA7yVLA

Response

  • One of the following objects
  • One of

Response Codes

CodeDescription
200The environment variable was successfully removed
400One of the provided values in the request query is invalid.
401
403You do not have permission to access this resource.
404
409The project is being transfered and removing an environment variable is not possible

Gets a list of aliases with status for the current promote

get/v1/projects/{projectId}/promote/aliases

Get a list of aliases related to the last promote request with their mapping status

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v1/projects/SOME_STRING_VALUE/promote/aliases?failedOnly=true&limit=20&since=1609499532000&slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE&until=1612264332000", {
2
  "headers": {
3
    "Authorization": "Bearer <TOKEN>"
4
  },
5
  "method": "get"
6
})

Parameters

Path Params
Query Params
Path ParameterDescription

projectId

string

required

Response

  • One of the following objects
  • One of

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

Unpause a project

post/v1/projects/{projectId}/unpause

Unpause a project by passing its project id in the URL. If the project does not exist given the id then the request will fail with 400 status code. If the project enables auto assigning custom production domains and unblocks the active Production Deployment then the request will return with 200 status code.

Optional params

fetch-request

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

Parameters

Path Params
Query Params
Path ParameterDescription

projectId

string

required
The unique project identifier

Response

N/A

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

Update an existing project

patch/v9/projects/{idOrName}

Update the fields of a project using either its name or id.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v9/projects/prj_12HKQaOmR5t5Uy6vdcQsNIiZgHGB?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2
  "body": {
3
    "autoAssignCustomDomains": true,
4
    "autoAssignCustomDomainsUpdatedBy": "SOME_STRING_VALUE",
5
    "autoExposeSystemEnvs": true,
6
    "buildCommand": "SOME_STRING_VALUE",
7
    "commandForIgnoringBuildStep": "SOME_STRING_VALUE",
8
    "customerSupportCodeVisibility": true,
9
    "devCommand": "SOME_STRING_VALUE",
10
    "directoryListing": true,
11
    "enablePreviewFeedback": true,
12
    "framework": "nextjs",
13
    "gitForkProtection": true,
14
    "gitLFS": true,
15
    "installCommand": "SOME_STRING_VALUE",
16
    "name": "a-project-name",
17
    "nodeVersion": "20.x",
18
    "outputDirectory": "SOME_STRING_VALUE",
19
    "passwordProtection": {
20
      "deploymentType": "all",
21
      "password": "SOME_STRING_VALUE"
22
    },
23
    "publicSource": true,
24
    "rootDirectory": "SOME_STRING_VALUE",
25
    "serverlessFunctionRegion": "SOME_STRING_VALUE",
26
    "serverlessFunctionZeroConfigFailover": "ANY_TYPE_VALUE",
27
    "skewProtectionBoundaryAt": "SOME_INTEGER_VALUE",
28
    "skewProtectionMaxAge": "SOME_INTEGER_VALUE",
29
    "skipGitConnectDuringLink": true,
30
    "sourceFilesOutsideRootDirectory": true,
31
    "ssoProtection": {
32
      "deploymentType": "all"
33
    },
34
    "trustedIps": {
35
      "deploymentType": "all",
36
      "addresses": "SOME_ARRAY_VALUE",
37
      "protectionMode": "exclusive"
38
    }
39
  },
40
  "headers": {
41
    "Authorization": "Bearer <TOKEN>"
42
  },
43
  "method": "patch"
44
})

Parameters

Path Params
Query Params
Body Params
Path ParameterDescription

idOrName

string

required
The unique project identifier or the project name
Example:prj_12HKQaOmR5t5Uy6vdcQsNIiZgHGB

Response

  • accountIdstringRequired
  • analyticsobject
  • Properties
  • autoAssignCustomDomainsboolean
  • autoAssignCustomDomainsUpdatedBystring
  • autoExposeSystemEnvsboolean
  • buildCommandstring or null
  • commandForIgnoringBuildStepstring or null
  • concurrencyBucketNamestring
  • connectBuildsEnabledboolean
  • connectConfigurationIdstring or null
  • createdAtnumber
  • cronsobject
  • Properties
  • customerSupportCodeVisibilityboolean
  • dataCacheobject
  • Properties
  • devCommandstring or null
  • directoryListingbooleanRequired
  • enablePreviewFeedbackboolean or null
  • envarray
  • Properties
  • frameworkstring or null
    One of: blitzjs | nextjs | gatsby | remix | astro | hexo | eleventy | docusaurus-2 | docusaurus | preact | solidstart-1 | solidstart | dojo | ember | vue | scully | ionic-angular | angular | polymer | svelte | sveltekit | sveltekit-1 | ionic-react | create-react-app | gridsome | umijs | sapper | saber | stencil | nuxtjs | redwoodjs | hugo | jekyll | brunch | middleman | zola | hydrogen | vite | vitepress | vuepress | parcel | sanity | storybook
  • gitCommentsobject
  • Properties
  • gitForkProtectionboolean
  • gitLFSboolean
  • hasActiveBranchesboolean
  • hasFloatingAliasesboolean
  • idstringRequired
  • installCommandstring or null
  • lastAliasRequestobject or null
  • Properties
  • lastRollbackTargetobject or null
  • latestDeploymentsarray
  • Properties
  • linkOne of the following objects
  • One of
  • liveboolean
  • namestringRequired
  • nodeVersionstringRequired
    One of: 20.x | 18.x | 16.x | 14.x | 12.x | 10.x | 8.10.x
  • oidcTokenConfigobject
  • Properties
  • outputDirectorystring or null
  • passiveConnectConfigurationIdstring or null
  • passwordProtectionobject or null
  • pausedboolean
  • permissionsobject
  • Properties
  • productionDeploymentsFastLaneboolean
  • protectionBypassobject
  • publicSourceboolean or null
  • rootDirectorystring or null
  • securityobject
  • Properties
  • serverlessFunctionRegionstring or null
  • serverlessFunctionZeroConfigFailoverboolean
  • skewProtectionBoundaryAtnumber
  • skewProtectionMaxAgenumber
  • skipGitConnectDuringLinkboolean
  • sourceFilesOutsideRootDirectoryboolean
  • speedInsightsobject
  • Properties
  • ssoProtectionobject or null
  • Properties
  • targetsobject
  • One of
  • transferCompletedAtnumber
  • transferStartedAtnumber
  • transferToAccountIdstring
  • transferredFromAccountIdstring
  • trustedIpsOne of the following objects or null
  • One of
  • updatedAtnumber
  • webAnalyticsobject
  • Properties

Response Codes

CodeDescription
200The project was successfully updated
400

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

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

  • Trusted IPs is only accessible for enterprise customers

401
402
403You do not have permission to access this resource.
409

  • The provided name for the project is already being used

  • The project is currently being transferred.

428

  • Owner does not have protection add-on

  • Advanced Deployment Protection is not available for the user plan

Update the data cache feature

patch/v1/data-cache/projects/{projectId}

Update the data cache feature on a project.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v1/data-cache/projects/prj_12HKQaOmR5t5Uy6vdcQsNIiZgHGB?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2
  "body": {
3
    "disabled": true
4
  },
5
  "headers": {
6
    "Authorization": "Bearer <TOKEN>"
7
  },
8
  "method": "patch"
9
})

Parameters

Path Params
Query Params
Body Params
Path ParameterDescription

projectId

string

required
The unique project identifier
Example:prj_12HKQaOmR5t5Uy6vdcQsNIiZgHGB

Response

  • accountIdstringRequired
  • analyticsobject
  • Properties
  • autoAssignCustomDomainsboolean
  • autoAssignCustomDomainsUpdatedBystring
  • autoExposeSystemEnvsboolean
  • buildCommandstring or null
  • commandForIgnoringBuildStepstring or null
  • concurrencyBucketNamestring
  • connectBuildsEnabledboolean
  • connectConfigurationIdstring or null
  • createdAtnumber
  • cronsobject
  • Properties
  • customerSupportCodeVisibilityboolean
  • dataCacheobject
  • Properties
  • devCommandstring or null
  • directoryListingbooleanRequired
  • enablePreviewFeedbackboolean or null
  • envarray
  • Properties
  • frameworkstring or null
    One of: blitzjs | nextjs | gatsby | remix | astro | hexo | eleventy | docusaurus-2 | docusaurus | preact | solidstart | dojo | ember | vue | scully | ionic-angular | angular | polymer | svelte | sveltekit | sveltekit-1 | ionic-react | create-react-app | gridsome | umijs | sapper | saber | stencil | nuxtjs | redwoodjs | hugo | jekyll | brunch | middleman | zola | hydrogen | vite | vitepress | vuepress | parcel | sanity | storybook
  • gitCommentsobject
  • Properties
  • gitForkProtectionboolean
  • gitLFSboolean
  • hasActiveBranchesboolean
  • hasFloatingAliasesboolean
  • idstringRequired
  • installCommandstring or null
  • lastAliasRequestobject or null
  • Properties
  • lastRollbackTargetobject or null
  • latestDeploymentsarray
  • Properties
  • linkOne of the following objects
  • One of
  • liveboolean
  • namestringRequired
  • nodeVersionstringRequired
    One of: 20.x | 18.x | 16.x | 14.x | 12.x | 10.x | 8.10.x
  • oidcTokenConfigobject
  • Properties
  • outputDirectorystring or null
  • passiveConnectConfigurationIdstring or null
  • passwordProtectionobject or null
  • pausedboolean
  • permissionsobject
  • Properties
  • productionDeploymentsFastLaneboolean
  • protectionBypassobject
  • publicSourceboolean or null
  • rootDirectorystring or null
  • securityobject
  • Properties
  • serverlessFunctionRegionstring or null
  • serverlessFunctionZeroConfigFailoverboolean
  • skewProtectionBoundaryAtnumber
  • skewProtectionMaxAgenumber
  • skipGitConnectDuringLinkboolean
  • sourceFilesOutsideRootDirectoryboolean
  • speedInsightsobject
  • Properties
  • ssoProtectionobject or null
  • Properties
  • targetsobject
  • One of
  • transferCompletedAtnumber
  • transferStartedAtnumber
  • transferToAccountIdstring
  • transferredFromAccountIdstring
  • trustedIpsOne of the following objects or null
  • One of
  • updatedAtnumber
  • webAnalyticsobject
  • Properties

Response Codes

CodeDescription
200
400

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

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

401
403You do not have permission to access this resource.
404

Update a project domain

patch/v9/projects/{idOrName}/domains/{domain}

Update a project domain's configuration, including the name, git branch and redirect of the domain.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v9/projects/SOME_STRING_VALUE/domains/www.example.com?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2
  "body": {
3
    "gitBranch": "SOME_STRING_VALUE",
4
    "redirect": "foobar.com",
5
    "redirectStatusCode": 307
6
  },
7
  "headers": {
8
    "Authorization": "Bearer <TOKEN>"
9
  },
10
  "method": "patch"
11
})

Parameters

Path Params
Query Params
Body Params
Path ParameterDescription

domain

string

required
The project domain name
Example:www.example.com

idOrName

string

required
The unique project identifier or the project name

Response

  • apexNamestringRequired
  • createdAtnumber
  • gitBranchstring or null
  • namestringRequired
  • projectIdstringRequired
  • redirectstring or null
  • redirectStatusCodenumber or null
    One of: 307 | 301 | 302 | 308
  • updatedAtnumber
  • verificationarray
    A list of verification challenges, one of which must be completed to verify the domain for use on the project. After the challenge is complete POST /projects/:idOrName/domains/:domain/verify to verify the domain. Possible challenges: - If verification.type = TXT the verification.domain will be checked for a TXT record matching verification.value.
  • Properties
  • verifiedbooleanRequired
    true if the domain is verified for use with the project. If false it will not be used as an alias on this project until the challenge in verification is completed.

Response Codes

CodeDescription
200The domain was updated successfuly
400

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

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

  • The domain redirect is not valid

401
403You do not have permission to access this resource.
409The project is currently being transferred

Verify project domain

post/v9/projects/{idOrName}/domains/{domain}/verify

Attempts to verify a project domain with verified = false by checking the correctness of the project domain's verification challenge.

Optional params

fetch-request

1
await fetch("https://api.vercel.com/v9/projects/prj_12HKQaOmR5t5Uy6vdcQsNIiZgHGB/domains/example.com/verify?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2
  "headers": {
3
    "Authorization": "Bearer <TOKEN>"
4
  },
5
  "method": "post"
6
})

Parameters

Path Params
Query Params
Path ParameterDescription

domain

string

required
The domain name you want to verify
Example:example.com

idOrName

string

required
The unique project identifier or the project name
Example:prj_12HKQaOmR5t5Uy6vdcQsNIiZgHGB

Response

  • apexNamestringRequired
  • createdAtnumber
  • gitBranchstring or null
  • namestringRequired
  • projectIdstringRequired
  • redirectstring or null
  • redirectStatusCodenumber or null
    One of: 307 | 301 | 302 | 308
  • updatedAtnumber
  • verificationarray
    A list of verification challenges, one of which must be completed to verify the domain for use on the project. After the challenge is complete POST /projects/:idOrName/domains/:domain/verify to verify the domain. Possible challenges: - If verification.type = TXT the verification.domain will be checked for a TXT record matching verification.value.
  • Properties
  • verifiedbooleanRequired
    true if the domain is verified for use with the project. If false it will not be used as an alias on this project until the challenge in verification is completed.

Response Codes

CodeDescription
200

  • The project domain was verified successfully

  • Domain is already verified

400

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

  • There is an existing TXT record on the domain verifying it for another project

  • The domain does not have a TXT record that attempts to verify the project domain

  • The TXT record on the domain does not match the expected challenge for the project domain

  • Project domain is not assigned to project

401
403You do not have permission to access this resource.
Last updated on April 29, 2024
Previous
Remove a Project Member
Next
Add a domain to a project