Search...

Getting Started

Introduction

The Vercel API gives full control over the entire Vercel platform by providing all the resources available to our official clients, exposed as simple HTTP endpoints.

You can use the commands listed below with curl by providing your testing token.


API Basics

Our API is exposed as an HTTP/1 and HTTP/2 service over SSL. All endpoints live under the URL https://api.vercel.com and then generally follow the REST architecture.

Server Specs

HTTP and TLS

The API supports HTTP versions 1, 1.1, and 2, although HTTP/2 is preferred.

TLS versions 1.2 and 1.3 are supported, with resumption.

For more information on TLS support, refer to the SSL Labs report.

Content Type

All requests must be encoded as JSON with the Content-Type: application/json header. If not otherwise specified, responses from the Vercel API, including errors, are encoded exclusively as JSON as well.

Authentication

Requests to the Vercel API must provide an API token through the Authorization header:

Authorization: Bearer <TOKEN>

The Authorization header with a token.

Note: In order to get this token, you will need to use the OAuth2 endpoint.

Accessing Resources Owned by a Team

By default, you can access resources contained within your own user account.

To access resources owned by a team, you must first find the team ID. You can do so by using the teams endpoint (documentation) and obtaining the id of a team.

After you obtained the team ID, append it as a query string at the end of the API endpoint URL:

https://api.vercel.com/v6/now/deployments?teamId=[team ID]

Replace [team ID] with the team ID you obtained.

Note: You still need to provide an API token through the Authorization header.

Failed Authentication

If authentication is unsuccessful for a request, the error status code 403 is returned.

Errors

All API endpoints contain a code and message within the error responses, though some API endpoints extend the error object to contain other information. Each endpoint that does this will be documented in their appropriate section.

While we recommend that you write error messages that fit your needs and provide your users with the best experience, our message fields are designed to be neutral, not contain sensitive information, and can be safely passed down to user interfaces.

{
  "error": {
    "code": "forbidden",
    "message": "Not authorized"
  }
}

An example of an unauthorized request error.

Rate Limits

We limit the number of calls you can make over a certain period of time. Rate limits vary and are specified by the following header in all responses:

Header
Description
X-RateLimit-Limit
The maximum number of requests that the consumer is permitted to make.
X-RateLimit-Remaining
The number of requests remaining in the current rate limit window.
X-RateLimit-Reset
The time at which the current rate limit window resets in UTC epoch seconds.

When the rate limit is exceeded, an error is returned with the status "429 Too Many Requests":

{
  "error": {
    "code": "too_many_requests",
    "message": "Rate limit exceeded",
  }
}

An example of a rate limit exceeded error.

Note: You can find the complete list of rate limits in the limits documentation.

Versioning

All endpoints and examples are designated with a specific version. Versions vary per endpoint and are not global.

The response shape of a certain endpoint is not guaranteed to be fixed over time. In particular, we might add new keys to responses without bumping a version endpoint, which will be noted in the changelog.

To ensure the security and correctness of your application, make sure to only read the keys from the response that your application needs. Don't proxy entire responses to third-parties without validation.

Old versions of each endpoint are supported for as long as possible. When we intend to deprecate, we will notify users in the changelog section.

Endpoint versions follow the base URL and come before the endpoint. For example:

https://api.vercel.com/v6/now/deployments

Using version 6 of the deployments endpoint.

Types

The following is a list of the types of data used within the Vercel API:

Name
Definition
Example
ID
A unique value used to identify resources.
"V0fra8eEgQwEpFhYG2vTzC3K"
String
A string is a sequence of characters used to represent text.
"value"
Integer
An integer is a number without decimals.
1234
Float
A float is a number with decimals.
12.34
Map
A data structure with a list of values assigned to a unique key.
{ "key": "value" }
List
A data structure with only a list of values separated by a comma.
["value", 1234, 12.34]
Enum
An Enum is a String with only a few possible valid values.
`"A"
Date
An Integer representing a date in milliseconds since the UNIX epoch.
1540095775941
Boolean
A Boolean is a type of two possible values representing true or false.
true

Endpoints

User

Get the authenticated user

Endpoint
GET https://api.vercel.com/www/user

Retrieves information related to the authenticated user.

Example Request
curl "https://api.vercel.com/www/user" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "user":{
    "uid":"96SnxkFiMyVKsK3pnoHfx3Hz",
    "email":"john@user.co",
    "name":"John Doe",
    "username":"john-doe",
    "avatar":"c51b0a8e9ef8e44a79472c6a3da64add0d742a0f",
    "platformVersion":1,
    "billing":{
      "plan":"hobby",
      "period":null,
      "trial":null,
      "cancelation":null,
      "addons":null
    },
    "bio":"I work at John Doe Inc.",
    "website":"john-doe.com",
    "profiles":[
      {
        "service":"website",
        "link":"john-doe.com"
      }
    ]
  }
}

Deployments

Create a New Deployment

Endpoint
POST /v12/now/deployments

Create a new deployment with all the required and intended data.

Before creating a deployment, upload any required files when they cannot be posted at once by inlining files.

Request Parameters

Key
Required
Description
name
Yes
A string with the project name used in the deployment URL. The name string has a maximum length of 52 characters.
files
Yes
A list of objects with the files to be deployed.
project
No
The target project identifier in which the deployment will be created. When defined, this parameter overrides name.
meta
No
An object containing the deployment's metadata. Multiple key-value pairs can be attached to a deployment. For example, { "foo": "bar" }.
env
No
An object containing the deployment's environment variable names and values. Secrets can be referenced by prefixing the value with @.
build.env
No
An object containing the deployment's environment variable names and values to be passed to Builds. Secrets can be referenced by prefixing the value with @.
functions
No
A list of objects used to configure your Serverless Functions. For example, { "api/test.js": { "memory": 3008 } }.
routes
No
A list of routes objects used to rewrite paths to point towards other internal or external paths. For example; [{ "src": "/docs", "dest": "https://docs.example.com" }].
regions
No
An array of the regions the deployment's Serverless Functions should be deployed to. For example, ["sfo", "bru"].
public
No
Whether a deployment's source and logs are available publicly.
target
No
Either not defined, staging, or production. If staging, a staging alias in the format <project>.<team>.now.sh will be assigned. If production, any aliases defined in alias will be assigned.
alias
No
Aliases that will get assigned when the deployment is READY and the target is production. The client needs to make a GET request to its API to ensure the assignment.
projectSettings
No
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.
Aliases

The aliases inside of alias are only assigned when the target is set to production and the deployment reached the READY state.

Note: If there are missing certificates for any of the required domains, they will get created during the initialization of the deployment. This could make the deployment take slightly longer to complete.
Files

Each item in the files array could be either a list of inlined files or a list of SHA1 strings used to match with already uploaded files.

Inlined Files

In the case you want to inline each file inside the create deployment request each item in the files key should have the following format:

Note: Inlined files, either as plain or base64 strings, are useful when a deployment has only a few small files that you can upload in a single request.
Key
Required
Description
file
Yes
The file name including the whole path, eg. folder/file.js.
data
Yes
The file content, it could be either a base64 (useful for images, etc.) of the files or the plain content for source code.
encoding
No
The file content, it could be either a base64 (useful for images, etc.) of the files or the plain content for source code.
Project Settings

Project settings that will be applied to the deployment. They are required for the first deployment of a project and will be saved for following deployments. They can be changed on the dashboard or through the projects API.

Key
Required
Description
framework
No
Must be either a framework slug from @vercel/frameworks or null.
devCommand
No
Either a command that is executed during development or null for auto detection.
installCommand
No
Either a command that is executed for the "install" step during build time or null for auto detection.
buildCommand
No
Either a command that is executed for the "build" step during build time or null for auto detection.
outputDirectory
No
The name of a directory or relative path to the output of the build.
rootDirectory
No
The path of a directory that contains the source code if your deployment or null for auto detection.

If the projectSettings property is not set for the first deployment, the API will return an error containing information about the detected framework from @vercel/frameworks, which can be used for the next request to complete the deployment.

{
  "error": {
    "code": "missing_project_settings",
    "message": "The `projectSettings` object is required for new projects, but is missing in the deployment payload",
    "framework": {
      "name": "Next.js",
      "slug": "nextjs",
      "demo": "https://nextjs.now-examples.now.sh",
      "logo": "https://raw.githubusercontent.com/vercel/vercel/master/packages/frameworks/logos/next.svg",
      "tagline": "Next.js makes you productive with React instantly — whether you want to build static or dynamic sites. ",
      "description": "A Next.js app and a Serverless Function API.",
      "website": "https://nextjs.org",
      "settings": {
        "installCommand": {
          "placeholder": "`yarn install` or `npm install`"
        },
        "buildCommand": {
          "placeholder": "`next build` or `build` from `package.json`"
        },
        "devCommand": {
          "value": "next dev --port $PORT"
        },
        "outputDirectory": {
          "placeholder": "Next.js default"
        }
      }
    }
  }
}
Note: The query parameter ?skipAutoDetectionConfirmation=1 can be appended to the deployments API URL to skip this confirmation error.
Example Request
curl -X POST "https://api.vercel.com/v12/now/deployments" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-instant-deployment",
  "files": [
    {
      "file": "index.html",
      "data": "<!doctype html>\n<html>\n  <head>\n    <title>A simple deployment with the Vercel API!</title>\n  </head>\n  <body>\n    <h1>Welcome to a simple static file</h1>\n    <p>Deployed with <a href=\"/docs/api\">the Vercel API</a>!</p>\n    </body>\n</html>"
    }
  ],
  "projectSettings": {
    "framework": null
  }
}'
SHA1 files

In the case you want to first upload each file and then create a deployment you need to pass the file name and the file content SHA1 which is going to be used to check the integrity and match the requests with the file.

Note: Uploading each file and then creating the deployment with files using SHA1 strings is especially useful when uploading many, or big, files. This is helpful when retrying deployments without needing to upload the files again.
Key
Required
Description
file
Yes
The file name including the whole path, eg. folder/file.js.
sha
Yes
The file SHA1 used to check the integrity.
size
Yes
The file size in bytes.
Example Request
curl -X POST "https://api.vercel.com/v12/now/deployments" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-instant-deployment",
  "files": [
    {
      "file": "index.html",
      "sha": "6938e4ed47a23f17ceb6dbd880ab18d2787e7946",
      "size": 160
    }
  ]
}'
Example Response
{
  "id": "dpl_6EZWg2tkQevMN76UQzFgKsD2gaNR",
  "url": "my-instant-deployment-2i7mwl1a1w.now.sh",
  "name": "my-instant-deployment",
  "meta": {},
  "plan": "pro",
  "public": false,
  "ownerId": "ZspSRT4ljIEEmMHgoDwKWDei",
  "readyState": "READY",
  "createdAt": 1540257237129,
  "createdIn": "sfo1",
  "regions": [
    "sfo1"
  ],
  "functions": {
    "api/test.js": {
      "memory": 3008
    }
  },
  "routes": null,
  "env": [],
  "build": {
    "env": []
  },
  "target": null,
  "alias": [],
  "aliasError": null,
  "aliasAssigned": false
}

Create a New Deployment With Metadata

In the case you want to attach metadata to a new deployment, you need to pass the meta object alongside other required data.

Example Request
curl -X POST "https://api.vercel.com/v12/now/deployments" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-instant-deployment",
  "files": [
    {
      "file": "index.html",
      "sha": "6938e4ed47a23f17ceb6dbd880ab18d2787e7946",
      "size": 160
    }
  ],
  "meta": {
    "kito": "lavendar",
    "foo": "bar"
  }
}'
Note: You can attach up to 100 of those key-value pairs to a single deployment.
Example Response
{
  "id": "dpl_6EZWg2tkQevMN76UQzFgKsD2gaNR",
  "url": "my-instant-deployment-2i7mwl1a1w.now.sh",
  "name": "my-instant-deployment",
  "meta": {
    "kito": "lavender",
    "foo": "bar"
  },
  "plan": "pro",
  "public": false,
  "ownerId": "ZspSRT4ljIEEmMHgoDwKWDei",
  "readyState": "READY",
  "createdAt": 1540257237129,
  "createdIn": "sfo1",
  "regions": [
    "sfo1"
  ],
  "routes": null,
  "env": [],
  "build": {
    "env": []
  },
  "target": null,
  "alias": [],
  "aliasError": null,
  "aliasAssigned": true
}

Force a New Deployment

To create a new deployment, with a new ID and URL, etc. if nothing has changed with the files intended to be deployed that were already previously deployed, use the forceNew=1 URL parameter.

Example Request
curl -X POST "https://api.vercel.com/v12/now/deployments?forceNew=1" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-instant-deployment",
  "files": [
    {
      "file": "index.html",
      "data": "<!doctype html>\n<html>\n  <head>\n    <title>A simple deployment with the Vercel API!</title>\n  </head>\n  <body>\n    <h1>Welcome to a simple static file</h1>\n    <p>Deployed with <a href=\"/docs/api\">the Vercel API</a>!</p>\n    </body>\n</html>"
    }
  ]
}'
Example Response
{
  "id": "dpl_D6FpCMUYdba5bZFJvA46FLBMxM2W",
  "url": "my-instant-deployment-3ij3cxz9qr.now.sh",
  "name": "my-instant-deployment",
  "meta": {},
  "plan": "pro",
  "public": false,
  "ownerId": "ZspSRT4ljIEEmMHgoDwKWDei",
  "readyState": "READY",
  "createdAt": 1540257237129,
  "createdIn": "sfo1",
  "regions": [
    "sfo1"
  ],
  "routes": null,
  "env": [],
  "build": {
    "env": []
  },
  "target": null,
  "alias": [],
  "aliasError": null,
  "aliasAssigned": true
}
Deploying again with the same request would yield the same response, with the same ID and URL due to no differences to the files or configuration.
Example Request
curl -X POST "https://api.vercel.com/v12/now/deployments?forceNew=1" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-instant-deployment",
  "files": [
    {
      "file": "index.html",
      "data": "<!doctype html>\n<html>\n  <head>\n    <title>A simple deployment with the Vercel API!</title>\n  </head>\n  <body>\n    <h1>Welcome to a simple static file</h1>\n    <p>Deployed with <a href=\"/docs/api\">the Vercel API</a>!</p>\n    </body>\n</html>"
    }
  ],
  "projectSettings": {
    "framework": null
  }
}'

Deploying again with the same request using the ?forceNew=1 URL parameter would yield a new, different, response, with a different ID and URL:

Example Response
{
  "id": "dpl_5bQis7iG8EQxJMAEY92KxsE4WmQZ",
  "url": "my-instant-deployment-613cx07atx.now.sh",
  "name": "my-instant-deployment",
  "meta": {},
  "plan": "pro",
  "public": false,
  "ownerId": "ZspSRT4ljIEEmMHgoDwKWDei",
  "readyState": "READY",
  "createdAt": 1540257454135,
  "createdIn": "sfo1",
  "regions": [
    "sfo1"
  ],
  "routes": null,
  "env": [],
  "build": {
    "env": []
  },
  "target": null,
  "alias": [],
  "aliasError": null,
  "aliasAssigned": true
}

Response Parameters

Key
Description
id
A string holding the unique ID of the deployment.
url
A string with the unique URL of the deployment. If it hasn't finished uploading (is incomplete), the value will be null.
name
The name of the deployment.
meta
An object containing the deployment's metadata. For example, { "foo": "bar" }.
regions
The regions the deployment exists in, e.g. sfo1.
routes
A list of routes objects used to rewrite paths to point towards other internal or external paths. For example; [{ "src": "/docs", "dest": "https://docs.example.com" }].
functions
A list of objects used to configure your Serverless Functions. For example, { "api/test.js": { "memory": 3008 } }.
plan
The pricing plan the deployment was made under.
public
A boolean representing if the deployment is public or not. By default this is false.
ownerId
The unique ID of the user or team the deployment belongs to.
readyState
The state of the deployment depending on the process of deploying, or if it is ready or in an error state. Possible values are INITIALIZING, ANALYZING, BUILDING, DEPLOYING, READY, or ERROR.
createdAt
A number containing the date when the deployment was created in milliseconds.
createdIn
The region where the deployment was first created, e.g. sfo1.
env
The keys of the environment variables that were assigned during runtime.
build.env
The keys of the environment variables that were assigned during the build phase.
target
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.
alias
A list of all the aliases (default aliases, staging aliases and production aliases) that were assigned upon deployment creation.
aliasError
An object that will contain a code and a message when the aliasing fails, otherwise the value will be null.
aliasAssigned
A boolean that will be true when the aliases from the alias property were assigned successfully.
Example Request
curl -X POST "https://api.vercel.com/v12/now/deployments" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-instant-deployment",
  "files": [
    {
      "file": "index.html",
      "data": "<!doctype html>\n<html>\n  <head>\n    <title>A simple deployment with the Vercel API!</title>\n  </head>\n  <body>\n    <h1>Welcome to a simple static file</h1>\n    <p>Deployed with <a href=\"/docs/api\">the Vercel API</a>!</p>\n    </body>\n</html>"
    }
  ],
  "projectSettings": {
    "framework": null
  }
}'
Example Response
{
  "id": "dpl_89qyp1cskzkLrVicDaZoDbjyHuDJ",
  "url": "my-instant-deployment-3ij3cxz9qr.now.sh",
  "name": "my-instant-deployment",
  "meta": {},
  "plan": "pro",
  "public": false,
  "ownerId": "ZspSRT4ljIEEmMHgoDwKWDei",
  "readyState": "READY",
  "createdAt": 1540257589405,
  "createdIn": "sfo1",
  "regions": [
    "sfo1"
  ],
  "routes": null,
  "env": [],
  "build": {
    "env": []
  },
  "target": null,
  "alias": [],
  "aliasError": null,
  "aliasAssigned": true
}

Upload Deployment Files

Endpoint
POST /v2/now/files

Before you create a deployment you need to upload the required files for that deployment. To do it you need to POST each file to this endpoint, after that's completed you'll need to POST to create a new deployment.

Note: If you need to upload only a few small files for a deployment you could inline them when you're creating a new deployment.

Headers

The POST needs to have the following headers:

Header
Description
Content-Length
The file size in bytes.
x-now-digest
The file SHA1 used to check the integrity.

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.

Note: The file name is defined when you create the deployment.
Example Request
curl -X POST "https://api.vercel.com/v2/now/files" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "x-now-digest: 6938e4ed47a23f17ceb6dbd880ab18d2787e7946" \
  -d '<!doctype html>
<html>

  <head>

    <title>My Instant Deployment</title>

  </head>

  <body>

    &nbsp;<h1>My Instant Vercel Deployment</h1>

    <p>Hello world!</p>

  </body>
</html>
'

List Deployments

Endpoint
GET /v5/now/deployments

List deployments under the account corresponding to the API token. If a deployment hasn't finished uploading (is incomplete), the url property will have a value of null.

Request Query Parameters

The response of this API can be controlled with the following query parameters. All of them are optional.

Key
Description
limit
Maximum number of deployments to list from a request. (default: 5, max: 100)
from
Get the deployment created after this Date timestamp. (default: current time)
teamId
List deployments of the team matching the specified teamId.
projectId
Filter deployments from the given projectId.
meta-[KEY]
Filter deployments by the given meta key value pairs. e.g., meta-githubDeployment=1.

Each deployment is an object with the following keys:

Response Parameters

Key
Description
uid
A string with the unique deployment ID you can use to get more information or remove it.
name
A string with the project under which the deployment was created.
url
A string with the unique URL of the deployment. If it hasn't finished uploading (is incomplete), the value will be null.
created
A number containing the date when the deployment was created (in timestamp).
creator
A map with the ID of the user who created the deployment.
state
A string with the current deployment state, it could be one of the following QUEUED, BUILDING, READY, or ERROR.
meta
A map containing all deployment metadata.
target
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 (property on the deployment document) were assigned.
aliasError
An object that will contain a code and a message when the aliasing fails, otherwise the value will be null.
aliasAssigned
A boolean that will be true when the aliases from the alias property of the deployment document were assigned successfully.

Get a Single Deployment

Endpoint
GET /v11/now/deployments/:id
GET /v11/now/deployments/get?url=[deployment URL or alias]

This endpoint allows you to retrieve information for a deployment either by supplying its id in the URL or the url query parameter. The url query parameter can be either the URL of the deployment or an alias attached to it.

One way to obtain a deployment ID is to list all deployments.

Response Parameters

Key
Description
id
A string holding the unique ID of the deployment.
url
A string with the unique URL of the deployment. If it hasn't finished uploading (is incomplete), the value will be null.
name
The name of the deployment.
meta
An object containing the deployment's metadata. For example, { "foo": "bar" }.
regions
The regions the deployment exists in, e.g. sfo1.
routes
A list of routes objects used to rewrite paths to point towards other internal or external paths. For example; [{ "src": "/docs", "dest": "https://docs.example.com" }].
functions
A list of objects used to configure your Serverless Functions. For example, { "api/test.js": { "memory": 3008 } }.
plan
The pricing plan the deployment was made under.
public
A boolean representing if the deployment is public or not. By default this is false.
ownerId
The unique ID of the user or team the deployment belongs to.
readyState
The state of the deployment depending on the process of deploying, or if it is ready or in an error state. Possible values are QUEUED, BUILDING, READY, or ERROR.
createdAt
A number containing the date when the deployment was created in milliseconds.
createdIn
The region where the deployment was first created, e.g. sfo1.
env
The keys of the environment variables that were assigned during runtime.
build.env
The keys of the environment variables that were assigned during the build phase.
target
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.
alias
A list of all the aliases (default aliases, staging aliases and production aliases) that were assigned upon deployment creation.
aliasError
An object that will contain a code and a message when the aliasing fails, otherwise the value will be null.
aliasAssigned
A boolean that will be true when the aliases from the alias property of the deployment document were assigned successfully.
Example Request
curl "https://api.vercel.com/v12/now/deployments/dpl_89qyp1cskzkLrVicDaZoDbjyHuDJ" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "id": "dpl_89qyp1cskzkLrVicDaZoDbjyHuDJ",
  "url": "my-instant-deployment-3ij3cxz9qr.now.sh",
  "name": "my-instant-deployment",
  "version": 2
  "meta": {},
  "plan": "pro",
  "public": false,
  "ownerId": "ZspSRT4ljIEEmMHgoDwKWDei",
  "readyState": "QUEUED",
  "createdAt": 1540257589405,
  "createdIn": "sfo1",
  "regions": [
    "sfo1"
  ],
  "functions": {
    "api/test.js": {
      "memory": 3008
    }
  },
  "routes": null,
  "env": [],
  "build": {
    "env": []
  },
  "target": "production",
  "alias": [
    "mywebsite.com",
    "project.my-team.now.sh"
  ],
  "aliasError": null,
  "aliasAssigned": true
}

Delete a Deployment

Endpoint
DELETE /v11/now/deployments/:id
DELETE /v11/now/deployments/remove?url

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.

Example Request
curl -X DELETE "https://api.vercel.com/v12/now/deployments/dpl_5WJWYSyB7BpgTj3EuwF37WMRBXBtPQ2iTMJHJBJyRfd" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "uid": "dpl_5WJWYSyB7BpgTj3EuwF37WMRBXBtPQ2iTMJHJBJyRfd",
  "state": "DELETED"
}

List Deployment Files

Endpoint
GET /v11/now/deployments/:id/files

This API allows you to retrieve the file structure of a deployment by supplying its :id in the URL.

The body will contain entries for each child and directory, coupled with an ID of the file for content download.

Response Parameters

Key
Description
name
The name of the file.
type
If it's a file or a directory.
uid
The unique ID of the file (only valid for file type).
children
The children files of the directory (only valid for directory type).
Example Request
curl "https://api.vercel.com/v11/now/deployments/dpl_BRGyoU2Jzzwx7myBnqv3xjRDD2GnHTwUWyFybnrUvjDD/files" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
[
  {
    "name": "index.html",
    "type": "file",
    "mode": 33206,
    "uid": "6938e4ed47a23f17ceb6dbd880ab18d2787e7946"
  },
  {
    "name": "static",
    "type": "directory",
    "mode": 16749,
    "children": [
      {
        "name": "logo.png",
        "type": "file",
        "mode": 33188,
        "uid": "c11e3ce950b69b959fcd691df973143271647714"
      }
    ]
  }
]

Get Single File Contents

Endpoint
GET /v11/now/deployments/:id/files/:fileId

This API allows you to retrieve the file data of a file associated with a deployment by supplying its :id and :fileId in the URL.

The body will contain the raw content of the file.

Example Request
curl "https://api.vercel.com/v11/now/deployments/dpl_BRGyoU2Jzzwx7myBnqv3xjRDD2GnHTwUWyFybnrUvjDD/files/2d4aad419917f15b1146e9e03ddc9bb31747e4d0" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
<!doctype html>
<html>
 <head>
 <title>My Instant Deployment</title>
 </head>
 <body>
 <h1>My Instant Vercel Deployment</h1>
 <p>Hello world!</p>
 </body>
</html>

List Builds

Endpoint
GET /v11/now/deployments/:id/builds

This endpoint retrieves a list of Build objects by supplying its :id in the URL.

Response Parameters

Each Build is an object with the following keys:

Key
Description
id
The unique identifier of the Build.
deploymentId
The unique identifier of the deployment.
entrypoint
The entrypoint of the deployment.
readyState
The state of the deployment depending on the process of deploying, or if it is ready or in an error state. Possible values are INITIALIZING, BUILDING,UPLOADING, DEPLOYING, READY, ARCHIVED, or ERROR.
readyStateAt
The time at which the Build state was last modified.
scheduledAt
The time at which the Build was scheduled to be built.
createdAt
The time at which the Build was created.
createdIn
The region where the Build was first created, for example, sfo1.
use
The Runtime the Build used to generate the output.
config
An object that contains the Build's configuration. For example, { "zeroConfig": true }.
output
A list of outputs for the Build. These can either be Serverless Functions or static files.
fingerprint
If the Build uses the @vercel/static Runtime, it contains a hashed string of all outputs.
Build Output Key

These are the keys of the output Map of the Build.

Key
Description
type
The type of the output. Either lambda or file.
path
The absolute path of the file or Serverless Function.
digest
The SHA1 of the file.
mode
The POSIX file permissions.
size
The size of the file in bytes.
lambda
If the output is a Serverless Function, it returns an object that contains functionName, deployedTo, and optional memorySize keys.
Example Request
curl "https://api.vercel.com/v11/now/deployments/dpl_BRGyoU2Jzzwx7myBnqv3xjRDD2GnHTwUWyFybnrUvjDD/builds" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "builds": [
    {
      "id": "bld_q5fj68jh7eewfe8",
      "deploymentId": "dpl_BRGyoU2Jzzwx7myBnqv3xjRDD2GnHTwUWyFybnrUvjDD",
      "entrypoint": "api/index.js",
      "readyState": "READY",
      "readyStateAt": 1567024758130,
      "scheduledAt": 1567024756543,
      "createdAt": 1567071524208,
      "createdIn": "sfo1",
      "use": "@vercel/node",
      "config": {
        "zeroConfig": true
      },
      "output": [{
        "type": "lambda",
        "path": "api/index.js",
        "digest": "digest_string",
        "mode": 49590,
        "size": 1502531,
        "lambda": {
          "functionName": "function_name",
          "deployedTo": [
            "sfo1"
          ]
        }
      }],
      "fingerprint": null
    }
  ]
}

Cancel a Deployment

Endpoint
PATCH /v12/now/deployments/:id/cancel

This API allows you to cancel a deployment, by supplying its :id in the URL.

Example Request
curl -X PATCH "https://api.vercel.com/v12/now/deployments/dpl_5WJWYSyB7BpgTj3EuwF37WMRBXBtPQ2iTMJHJBJyRfd/cancel" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "id": "dpl_6EZWg2tkQevMN76UQzFgKsD2gaNR",
  "url": "my-instant-deployment-2i7mwl1a1w.now.sh",
  "name": "my-instant-deployment",
  "meta": {},
  "plan": "pro",
  "public": false,
  "ownerId": "ZspSRT4ljIEEmMHgoDwKWDei",
  "readyState": "CANCELED",
  "createdAt": 1540257237129,
  "canceledAt": 1540257249129
  "createdIn": "sfo1",
  "regions": [
    "sfo1"
  ],
  "functions": {
    "api/test.js": {
      "memory": 3008
    }
  },
  "routes": null,
  "env": [],
  "build": {
    "env": []
  },
  "target": null,
  "alias": [],
  "aliasError": null,
  "aliasAssigned": false
}

Logs

Get Build Logs

Endpoint
GET /v2/now/deployments/:id/events

Get the build logs of a deployment by deployment ID and build ID.

Request Parameters

Key
Description
name
Deployment build ID.
limit
Maximum number of events to return. Provide -1 to return all available logs.
since
Timestamp for when build logs should be pulled from.
until
Timestamp for when the build logs should be pulled up until.
direction
Direction in which logs would be returned. Either backward or forward.
follow
When follow is set to 1, the API will return an HTTP stream similar to Serverless Function Logs, which allows you to see realtime feedback on build progress.

Response Parameters

Key
Description
type
The type of log. The type could be request, response, command or stdout.
created
The date when the log was created.
payload
An object containing information about the deployment including deploymentId, info, text, id, date, and serial.
Log Payload Key

These are the keys of the payload key of the logs.

Key
Description
deploymentId
The unique identifier of the deployment.
info
An object containing the type, name, and entrypoint of the deployment.
text
The log content as a string.
id
The unique identifier of the log.
date
The date when the log was created.
Example Request
curl "https://api.vercel.com/v2/now/deployments/Cm6WigEH9EBI4Uzs2WA6qOGe/events" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
[
  {
    "type": "stdout",
    "created": 1548675195849,
    "payload": {
        "deploymentId": "dpl_CyMsjjbZjkvMBom8ugeAWdKdcfQo",
        "info": {
            "type": "build",
            "name": "bld_j178cr7cm",
            "entrypoint": "package.json"
        },
        "text": "sandbox worker for deployment dpl_CyMsjjbZjkvMBom8ugeAWdKdcfQo build bld_j178cr7cm",
        "id": "34536610937913059182614073591023254523011083812228628481",
        "date": 1548675195849,
        "serial": "34536610937913059182614073591023254523011083812228628481"
    }
  },
  {
    "type": "stdout",
    "created": 1548675195854,
    "payload": {
        "deploymentId": "dpl_CyMsjjbZjkvMBom8ugeAWdKdcfQo",
        "info": {
            "type": "build",
            "name": "bld_j178cr7cm",
            "entrypoint": "package.json"
        },
        "text": "patching https://api-bru1.zeit.co/v2/now/deployments/dpl_CyMsjjbZjkvMBom8ugeAWdKdcfQo/builds/bld_j178cr7cm",
        "id": "34536610938024562908606726706730933114374325619758530562",
        "date": 1548675195854,
        "serial": "34536610938024562908606726706730933114374325619758530562"
    }
  },
  {
    "type": "stdout",
    "created": 1548675196557,
    "payload": {
        "deploymentId": "dpl_CyMsjjbZjkvMBom8ugeAWdKdcfQo",
        "info": {
            "type": "build",
            "name": "bld_j178cr7cm",
            "entrypoint": "package.json"
        },
        "text": "cleaning up...
",
        "id": "34536610953701986783173754775230543060046123758462763011",
        "date": 1548675196557,
        "serial": "34536610953701986783173754775230543060046123758462763011"
    }
  },
  {
    "type": "stdout",
    "created": 1548675196561,
    "payload": {
        "deploymentId": "dpl_CyMsjjbZjkvMBom8ugeAWdKdcfQo",
        "info": {
            "type": "build",
            "name": "bld_j178cr7cm",
            "entrypoint": "package.json"
        },
        "text": "running yarn for @vercel/build-utils...
",
        "id": "34536610953791189763967877267796685933136717204486684676",
        "date": 1548675196561,
        "serial": "34536610953791189763967877267796685933136717204486684676"
    }
  },
  {
    "type": "stdout",
    "created": 1548675196984,
    "payload": {
        "deploymentId": "dpl_CyMsjjbZjkvMBom8ugeAWdKdcfQo",
        "info": {
            "type": "build",
            "name": "bld_j178cr7cm",
            "entrypoint": "package.json"
        },
        "text": "yarn add v1.12.3
",
        "id": "34536610963224404982946330856666294762466974121516400645",
        "date": 1548675196984,
        "serial": "34536610963224404982946330856666294762466974121516400645"
    }
  },
]

Stream Serverless Function Logs

Endpoint
GET /v2/now/deployments/:id/events?follow=1

Open an HTTP stream of realtime logs for a Serverless Function by it's name.

Request Parameters

Key
Description
name
Serverless Function's functionName property

Response Parameters

Key
Description
type
The type of log. The type could be request, response, command or stdout.
created
The date when the log was created.
payload
An object containing information about the deployment including deploymentId, info, text, id, date, and serial.
Log Payload Key

These are the keys of the payload key of the logs.

Key
Description
deploymentId
The unique identifier of the deployment.
info
An object containing the type, name, and entrypoint of the deployment.
text
The log content as a string.
id
The unique identifier of the log.
date
The date when the log was created.

Types

These are the available log types with an explanation of what they mean.

Type
Description
request
The log is an HTTP request.
response
The log is an HTTP response.
command
The log is a terminal command, e.g. npm start.
stdout
The log is anything the application wrote to console.
Example Request
curl "https://api.vercel.com/v2/now/deployments/Cm6WigEH9EBI4Uzs2WA6qOGe/events?follow=1&name=team_nLlpyC6REAzxudGFKbrMDlud-5916ac0d61abdb050d45f579aaa77c70a7" \
  -H "Authorization: Bearer <TOKEN>"

Fetch Failed Requests for Serverless Function

Endpoint
GET /v2/now/deployments/:id/events

Get the failed request logs of a Serverless Function by it's name.

Request Parameters

Key
Description
statusCode
A string with an exact HTTP error code or it's mask: 500, 5xx.
name
Serverless Function's functionName property.

Response Parameters

Key
Description
type
The type of log. The type could be request, response, command or stdout.
created
The date when the log was created.
payload
An object containing information about the deployment including deploymentId, info, text, id, date, and serial.
Log Payload Key

These are the keys of the payload key of the logs.

Key
Description
deploymentId
The unique identifier of the deployment.
info
An object containing the type, name, and entrypoint of the deployment.
text
The log content as a string.
id
The unique identifier of the log.
date
The date when the log was created.

Types

These are the available log types with an explanation of what they mean.

Type
Description
request
The log is an HTTP request.
response
The log is an HTTP response.
command
The log is a terminal command, e.g. npm start.
stdout
The log is anything the application wrote to console.
Example Request
curl "https://api.vercel.com/v2/now/deployments/Cm6WigEH9EBI4Uzs2WA6qOGe/events?name=team_nLlpyC6REAzxudGFKbrMDlud-5916ac0d61abdb050d45f579aaa77c70a7&statusCode=5xx" \
  -H "Authorization: Bearer <TOKEN>"

Domains

List all the domains

Endpoint
GET /v5/domains

Retrieves a list of domains registered for the authenticating user. By default it returns the last 20 domains if no limit is provided.

Request Query Parameters

The response of this API can be controlled with the following optional query parameters.

Key
Description
limit
Maximum number of domains to list from a request.
since
Get domains created after this JavaScript timestamp.
until
Get domains created before this JavaScript timestamp.

Response Parameters

Key
Description
id
The unique ID of the domain.
name
The domain name.
serviceType
The type of service the domain is handled by. external if the DNS is externally handled, or zeit.world if handled with Vercel.
nsVerifiedAt
The date at which the domain's nameservers were verified based on the intended set.
txtVerifiedAt
The date at which the domain's TXT DNS record was verified.
cdnEnabled
Whether the domain has the Vercel Edge Network enabled or not.
createdAt
The date when the domain was created in the registry.
expiresAt
The date at which the domain is set to expire. null if not bought with Vercel.
boughtAt
If it was purchased through Vercel, the date when it was purchased.
verifiedRecord
The ID of the verification record in the registry.
verified
If the domain has the ownership verified.
nameservers
A list of the current nameservers of the domain.
intendedNameservers
A list of the intended nameservers for the domain to point to Vercel DNS.
creator
An object containing information of the domain creator, including the user's id, username, and email.
renew
If the domain will be auto renewed. undefined is equivalent to true.
Example Request
curl "https://api.vercel.com/v5/domains" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "domains": [
    {
      "id": "EmTbe5CEJyTk2yVAHBUWy4A3sRusca3GCwRjTC1bpeVnt1",
      "name": "example.com",
      "serviceType": "external",
      "nsVerifiedAt": null,
      "txtVerifiedAt": null,
      "cdnEnabled": false,
      "createdAt": 1544658552174,
      "boughtAt": null,
      "verificationRecord": "YMc9dEJKbAncYtTqSH8dp1j5NXycfEzyjkzBJ3m3UGwR43",
      "verified": true,
      "nameservers": [
        "ns1.nameserver.net",
        "ns2.nameserver.net"
      ],
      "intendedNameservers": [
        "a.zeit-world.net",
        "b.zeit-world.co.uk",
        "e.zeit-world.org",
        "f.zeit-world.com"
      ],
      "creator": {
        "id": "ZspSRT4ljIEEmMHgoDwKWDei",
        "username": "zeit_user",
        "email": "demo@example.com"
      }
    }
  ],
  "pagination": {
    "count": 1,
    "next": 1544658552174,
    "prev": 1544658552174
  }
}

Add a New Domain

Endpoint
POST /v4/domains

Register a new domain name with Vercel for the authenticating user. The field serviceType selects whether the domains are going to use zeit.world DNS or an external nameserver. In the latter case a CNAME/ALIAS record(s) are expected to point towards cname.vercel-dns.com.

If an external nameserver is used the user must verify the domain name by creating a TXT record for _now subdomain containing a verification token provided as a POST result. After the record has been created, the user may retry the same POST and the endpoint shall return verified: true, if the domain was verified successfully.

Request Parameters

Key
Required
Description
name
Yes
The domain name you want to add.

Response Parameters

Key
Description
id
The unique ID of the domain.
name
The domain name.
serviceType
The type of service the domain is handled by. external if the DNS is externally handled, or zeit.world if handled with Vercel.
nsVerifiedAt
The date at which the domain's nameservers were verified based on the intended set.
txtVerifiedAt
The date at which the domain's TXT DNS record was verified.
cdnEnabled
Whether the domain has the Vercel Edge Network enabled or not.
createdAt
The date when the domain was created in the registry.
expiresAt
The date at which the domain is set to expire. null if not bought with Vercel.
boughtAt
If it was purchased through Vercel, the date when it was purchased.
transferStartedAt
If transferred into Vercel, The date when the domain transfer was initiated
transferredAt
The date at which the domain was successfully transferred into Vercel. null if the transfer is still processing or was never transferred in.
verifiedRecord
The ID of the verification record in the registry.
verified
If the domain has the ownership verified.
nameservers
A list of the current nameservers of the domain.
intendedNameservers
A list of the intended nameservers for the domain to point to Vercel DNS.
creator
An object containing information of the domain creator, including the user's id, username, and email.
Example Request
curl -X POST "https://api.vercel.com/v4/domains" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example.com"
}'
Example Response
{
  "domain": {
    "id": "EmTbe5CEJyTk2yVAHBUWy4A3sRusca3GCwRjTC1bpeVnt1",
    "name": "example.com",
    "serviceType": "external",
    "nsVerifiedAt": null,
    "txtVerifiedAt": null,
    "cdnEnabled": false,
    "createdAt": 1544658552174,
    "boughtAt": null,
    "transferredAt": null,
    "verificationRecord": "YMc9dEJKbAncYtTqSH8dp1j5NXycfEzyjkzBJ3m3UGwR43",
    "verified": true,
    "nameservers": [
      "ns1.nameserver.net",
      "ns2.nameserver.net"
    ],
    "intendedNameservers": [
      "a.zeit-world.net",
      "b.zeit-world.co.uk",
      "e.zeit-world.org",
      "f.zeit-world.com"
    ],
    "creator": {
      "id": "ZspSRT4ljIEEmMHgoDwKWDei",
      "username": "zeit_user",
      "email": "demo@example.com"
    }
  }
}

Transfer In a Domain

Endpoint
POST /v4/domains

Initiate a domain transfer request from an external Registrar to Vercel.

Request Parameters

Key
Required
Description
method
Yes
The domain add operation to perform. When transferring in, use transfer-in.
name
Yes
The domain name you want to add.
authCode
Yes
The authorization code assigned to the domain.
expectedPrice
Yes
The price you expect to be charged for the required 1 year renewal.

Response Parameters

Key
Description
id
The unique ID of the domain.
name
The domain name.
serviceType
The type of service the domain is handled by. external if the DNS is externally handled, or zeit.world if handled with Vercel.
nsVerifiedAt
The date at which the domain's nameservers were verified based on the intended set.
txtVerifiedAt
The date at which the domain's TXT DNS record was verified.
cdnEnabled
Whether the domain has the Vercel Edge Network enabled or not.
createdAt
The date when the domain was created in the registry.
expiresAt
The date at which the domain is set to expire. null if not bought with Vercel.
boughtAt
If it was purchased through Vercel, the date when it was purchased.
transferStartedAt
The date when the domain transfer was initiated
transferredAt
The date at which the domain was successfully transferred into Vercel. null if the transfer is still processing.
verifiedRecord
The ID of the verification record in the registry.
verified
If the domain has the ownership verified.
nameservers
A list of the current nameservers of the domain.
intendedNameservers
A list of the intended nameservers for the domain to point to Vercel DNS.
creator
An object containing information of the domain creator, including the user's id, username, and email.
Example Request
curl -X POST "https://api.vercel.com/v4/domains" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "method": "transfer-in",
  "name": "example.com",
  "authCode": "fdhfr820ad#@FAdlj$$",
  "expectedPrice": 8
}'
Example Response
{
  "domain": {
    "id": "EmTbe5CEJyTk2yVAHBUWy4A3sRusca3GCwRjTC1bpeVnt1",
    "name": "example.com",
    "serviceType": "external",
    "nsVerifiedAt": null,
    "txtVerifiedAt": null,
    "cdnEnabled": false,
    "createdAt": 1544658552174,
    "boughtAt": null,
    "transferStartedAt": 1549928108897,
    "transferredAt": null,
    "verificationRecord": "YMc9dEJKbAncYtTqSH8dp1j5NXycfEzyjkzBJ3m3UGwR43",
    "verified": true,
    "nameservers": [
      "ns1.nameserver.net",
      "ns2.nameserver.net"
    ],
    "intendedNameservers": [
      "a.zeit-world.net",
      "b.zeit-world.co.uk",
      "e.zeit-world.org",
      "f.zeit-world.com"
    ],
    "creator": {
      "id": "ZspSRT4ljIEEmMHgoDwKWDei",
      "username": "zeit_user",
      "email": "demo@example.com"
    }
  }
}

Verify a Domain

Endpoint
POST /v4/domains/:name/verify

Verify a domain after adding either the intended nameservers or DNS TXT verification record to the domain.

Response Parameters

Key
Description
id
The unique ID of the domain.
name
The domain name.
serviceType
The type of service the domain is handled by. external if the DNS is externally handled, or zeit.world if handled with Vercel.
nsVerifiedAt
The date at which the domain's nameservers were verified based on the intended set.
txtVerifiedAt
The date at which the domain's TXT DNS record was verified.
cdnEnabled
Whether the domain has the Vercel Edge Network enabled or not.
createdAt
The date when the domain was created in the registry.
expiresAt
The date at which the domain is set to expire. null if not bought with Vercel.
boughtAt
If it was purchased through Vercel, the date when it was purchased.
verifiedRecord
The ID of the verification record in the registry.
verified
If the domain has the ownership verified.
nameservers
A list of the current nameservers of the domain.
intendedNameservers
A list of the intended nameservers for the domain to point to Vercel DNS.
creator
An object containing information of the domain creator, including the user's id, username, and email.
suffix
If the domain is used as a Custom Deployment Suffix (available on the Enterprise plan).
aliases
The list of aliases created using the domain.
certs
The list of SSL certificates created for the domain.
renew
If the domain will be auto renewed. undefined is equivalent to true.
Example Request
curl -X POST "https://api.vercel.com/v4/domains/example.com/verify" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{}'
Example Response (successful)
{
  "domain": {
    "id": "EmTbe5CEJyTk2yVAHBUWy4A3sRusca3GCwRjTC1bpeVnt1",
    "name": "example.com",
    "serviceType": "external",
    "nsVerifiedAt": null,
    "txtVerifiedAt": 1546869733102,
    "cdnEnabled": false,
    "createdAt": 1544658552174,
    "expiresAt": null,
    "boughtAt": null,
    "verificationRecord": "YMc9dEJKbAncYtTqSH8dp1j5NXycfEzyjkzBJ3m3UGwR43",
    "verified": true
    "nameservers": [
      "ns1.nameserver.net",
      "ns2.nameserver.net"
    ],
    "intendedNameservers": [
      "a.zeit-world.co.uk",
      "c.zeit-world.org",
      "d.zeit-world.com",
      "f.zeit-world.net"
    ],
    "creator": {
      "id": "ZspSRT4ljIEEmMHgoDwKWDei",
      "username": "zeit_user",
      "email": "demo@example.com"
    }
  }
}
Example Response (unsuccessful)
{
  "error": {
    "code": "verification_failed",
    "message": "The domain example.com couldn't be verified. Both nameservers and TXT verification methods failed",
    "name": "example.com",
    "nsVerification": {
      "name": "example.com",
      "nameservers": [
        "ns1.nameserver.net",
        "ns2.nameserver.net"
      ],
      "intendedNameservers": [
        "a.zeit-world.co.uk",
        "c.zeit-world.org",
        "d.zeit-world.com",
        "f.zeit-world.net"
      ]
    },
    "txtVerification": {
      "name": "example.com",
      "values": [],
      "verificationRecord": "YMc9dEJKbAncYtTqSH8dp1j5NXycfEzyjkzBJ3m3UGwR43"
    }
  }
}

Get Information for a Single Domain

Endpoint
 /v4/domains/:name

Get information for a single domain in an account or team.

Response Parameters

Key
Description
id
The unique ID of the domain.
name
The domain name.
serviceType
The type of service the domain is handled by. external if the DNS is externally handled, or zeit.world if handled with Vercel.
nsVerifiedAt
The date at which the domain's nameservers were verified based on the intended set.
txtVerifiedAt
The date at which the domain's TXT DNS record was verified.
cdnEnabled
Whether the domain has the Vercel Edge Network enabled or not.
createdAt
The date when the domain was created in the registry.
expiresAt
The date at which the domain is set to expire. null if not bought with Vercel.
boughtAt
If it was purchased through Vercel, the date when it was purchased.
verifiedRecord
The ID of the verification record in the registry.
verified
If the domain has the ownership verified.
nameservers
A list of the current nameservers of the domain.
intendedNameservers
A list of the intended nameservers for the domain to point to Vercel DNS.
creator
An object containing information of the domain creator, including the user's id, username, and email.
suffix
If the domain is used as a Custom Deployment Suffix (available on the Enterprise plan).
aliases
The list of aliases created using the domain.
certs
The list of SSL certificates created for the domain.
renew
If the domain will be auto renewed. undefined is equivalent to true.
Example Request
curl "https://api.vercel.com/v4/domains/example.com" \
  -H "Authorization: Bearer <TOKEN>"
Example Response (successful)
{
  "domain": {
    "id": "EmTbe5CEJyTk2yVAHBUWy4A3sRusca3GCwRjTC1bpeVnt1",
    "name": "example.com",
    "serviceType": "external",
    "nsVerifiedAt": null,
    "txtVerifiedAt": null,
    "cdnEnabled": false,
    "createdAt": 1544658552174,
    "expiresAt": null,
    "boughtAt": null,
    "verificationRecord": "YMc9dEJKbAncYtTqSH8dp1j5NXycfEzyjkzBJ3m3UGwR43",
    "verified": false,
    "nameservers": [
      "ns1.nameserver.net",
      "ns2.nameserver.net"
    ],
    "intendedNameservers": [
      "a.zeit-world.co.uk",
      "c.zeit-world.org",
      "d.zeit-world.com",
      "f.zeit-world.net"
    ],
    "creator": {
      "id": "ZspSRT4ljIEEmMHgoDwKWDei",
      "username": "zeit_user",
      "email": "demo@example.com"
    },
    "suffix": false,
    "aliases": [],
    "certs": []
  }
}
Example Response (unsuccessful)
{
  "error": {
    "code": "not_found",
    "message": "Domain name `my-zeit-domain.online` not found",
    "name": "my-zeit-domain.online"
  }
}

Remove a domain by name

Endpoint
DELETE /v4/domains/:name

Delete a previously registered domain name from Vercel. Deleting a domain will automatically remove any associated aliases.

Response Parameters

Key
Description
uid
The unique ID of the removed domain.
Example Request
curl -X DELETE "https://api.vercel.com/v4/domains/example.com" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  uid: "EmTbe5CEJyTk2yVAHBUWy4A3sRusca3GCwRjTC1bpeVnt1"
}

Check a domain availability

Endpoint
GET /v4/domains/status?name

Check if a domain name may be available to buy or not. The response is a JSON with the key available as a boolean.

Response Parameters

Key
Description
available
If the domain is available or not.
Example Request
curl "https://api.vercel.com/v4/domains/status?name=example.com" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "available": false
}

Check the price of a domain

Endpoint
GET /v4/domains/price?name

Check the price to purchase a domain and how long a single purchase period is. The response is a JSON with the key price as a number (always an integer) and a key period as a number indicating the number of years the domains could be held before paying again.

Response Parameters

Key
Description
price
The domain price.
period
The time period by which the domain is purchased.
Example Request
curl "https://api.vercel.com/v4/domains/price?name=example.com" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "price": 17,
  "period": 1
}

Purchase a domain

Endpoint
POST /v4/domains/buy

Purchase the specified domain, it receive the domain name as the key name inside the request body.

In case of a successful purchase the returns with code 200 and an empty body.

Request Parameters

Key
Required
Description
name
Yes
The domain name to purchase.
expectedPrice
Yes
The price you expect to be charged for the purchase.
Example Response (successful)
curl -X POST "https://api.vercel.com/v4/domains/buy" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example.com"
}'
Example Response (unsuccessful)
{
  "error": {
    "code": "not_available",
    "message": "Domain is not available"
  }
}

DNS

List all the DNS records of a domain

Endpoint
GET /v4/domains/:domain/records

Get a list of DNS records created for a domain name specified in the URL. By default it returns 20 records if no limit is provided. The rest can be retrieved using the pagination options described below.

Request Query Parameters

The response of this API can be controlled with the following optional query parameters.

Key
Description
limit
Maximum number of records to list from a request.
since
Get records created after this JavaScript timestamp.
until
Get records created before this JavaScript timestamp.

Response Parameters

Key
Description
records
The list of active records.
pagination
A map with pagination options.

Record

This is the format of each item in the records list.

Key
Description
id
The unique ID of the DNS record. Always prepended with rec_.
type
The type of record, it could be any valid DNS record.
name
A subdomain name or an empty string for the root domain.
value
The record value.
creator
The ID of the user who created the record or system if the record is an automatic record.
created
The date when the record was created.
updated
The date when the record was updated.
createdAt
The date when the record was created in milliseconds since the UNIX epoch.
updatedAt
The date when the record was updated in milliseconds since the UNIX epoch.

Pagination

This is the format of the pagination map.

Key
Description
count
The number of returned records.
next
The JavaScript timestamp to fetch the next set of records.
prev
The JavaScript timestamp to fetch the previous set of records.
Example Request
curl "https://api.vercel.com/v4/domains/example.com/records" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "records": [
    {
      "id": "rec_38OtX1f51szRA03atCybBuZ3",
      "slug": "example.com.-address",
      "type": "ALIAS",
      "name": "",
      "value": "cname.vercel-dns.com",
      "creator": "EvQtLv2F0FvfB5Vx4eK0R3Mf",
      "created": "1474631621542",
      "createdAt": "1474631621542",
      "updated": null,
      "updatedAt": null
    },
    {
      "id": "rec_Pxo2HEfutmlIYECtTE4SpDzY",
      "slug": "",
      "type": "CNAME",
      "name": "*",
      "value": "cname.vercel-dns.com",
      "creator": "system",
      "created": "1474631619960",
      "createdAt": "1474631619960",
      "updated": null,
      "updatedAt": null
    }
  ],
  "pagination": {
    "count": 2,
    "next": 1474631619960,
    "prev": 1474631621542
  }
}

Create a new DNS record

Endpoint
POST /v2/domains/:domain/records

Create a DNS record for a domain specified in the URL.

Request Parameters

Key
Required
Description
name
Yes
A subdomain name or an empty string for the root domain.
type
Yes
The type of record, it could be any valid DNS record.
value
Yes
The record value.
ttl
No
The TTL value. Must be a number between 60 and 2147483647. Default value is 60.
Value

The following table defines the format of the value property for supported record types.

Type
Description
Format
Example
A
An A record pointing to an IPv4 address.
address
192.0.2.42
AAAA
An AAAA record pointing to an IPv6 address.
address
2001:DB8::42
ALIAS
An ALIAS virtual record pointing to a hostname resolved to an A record on server side.
host
cname.vercel-dns.com
CAA
A CAA record to specify which Certificate Authorities (CAs) are allowed to issue certificates for the domain.
flags tag value
0 issue "letsencrypt.org"
CNAME
A CNAME record mapping to another domain name.
domain
cname.vercel-dns.com
MX
An MX record specifying the mail server responsible for accepting messages on behalf of the domain name.
priority host
10 mail.example.com.
SRV
A SRV record defining servers for specified services.
priority weight port target
10 10 500 sip.example.com.
TXT
A TXT record containing arbitrary text.
text
hello

Response Parameters

Key
Description
uid
The unique ID of the DNS record. Always prepended with rec_.
Example Request
curl -X POST "https://api.vercel.com/v2/domains/example.com/records" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "subdomain",
  "type": "MX",
  "value": "10 mail.example.com",
  "ttl": 3600
}'
Example Response
{
  uid: "rec_V0fra8eEgQwEpFhYG2vTzC3K"
}

Remove a DNS record

Endpoint
DELETE /v2/domains/:domain/records/:recId

Delete a DNS record created for a domain name, where both the domain and the record ID are specified in the URL. If the record was removed successfully the endpoint returns with code 200 and an empty body.

Example Request
curl -X DELETE "https://api.vercel.com/v2/domains/example.com/records/rec_V0fra8eEgQwEpFhYG2vTzC3K" \
  -H "Authorization: Bearer <TOKEN>"

Certificates

List certificates

Endpoint
GET /v4/now/certs

Retrieves a list of certificates issued for the authenticating user or information about the certificate issued for the common name specified in the URL. By default it returns 20 certificates if no limit is provided. The rest can be retrieved using the pagination options described below.

Request Query Parameters

The response of this API can be controlled with the following optional query parameters.

Key
Description
limit
Maximum number of certificates to list from a request.
since
Get certificates created after this JavaScript timestamp.
until
Get certificates created before this JavaScript timestamp.

Response Parameters

Key
Description
certs
The list of issued certificates.
pagination
A map with pagination options.

Certificate

This is the format of each item in the certs list.

Key
Description
uid
The unique identifier of the certificate.
cns
The common names for which domain the certificate was issued.
created
The date when the certificate was created.
expiration
The date when the certificate is going to expire.
createdAt
The date when the certificate was created.
expiresAt
The date when the certificate is going to expire.
autoRenew
If the certificate is going to be automatically renewed.

Pagination

This is the format of the pagination map.

Key
Description
count
The number of returned certificates.
next
The JavaScript timestamp to fetch the next set of certificates.
prev
The JavaScript timestamp to fetch the previous set of certificates.
Example Request
curl "https://api.vercel.com/v4/now/certs?limit=2" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "certs": [
    {
      "cns": ["testing.example.com", "*.example.com"],
      "uid": "oAjf6y9pxZgCJyQfrclN",
      "created": "2016-08-23T18:13:09.773Z",
      "expiration": "2016-12-16T16:00:00.000Z",
      "createdAt": 1471968789000,
      "expiresAt": 1481900400000,
      "autoRenew": true
    },
    {
      "cns": ["testing2.example.com", "*.example.com"],
      "uid": "tyrf6y9pxZgCJyQfttyu",
      "created": "2016-08-22T18:13:09.773Z",
      "expiration": "2016-12-15T16:00:00.000Z",
      "createdAt": 1471882389000,
      "expiresAt": 1481814000000,
      "autoRenew": true
    }
  ],
  "pagination": {
    "count": 2,
    "next": 1471882389000,
    "prev": 1471968789000
  }
}

Get a single certificate

Endpoint
GET /v3/now/certs/:id

Retrieves the information about the certificate issued for certificate id specified in the URL.

Response Parameters

Key
Description
uid
The unique identifier of the certificate.
cns
The common names for which domain the certificate was issued.
created
The date when the certificate was created.
expiration
The date when the certificate is going to expire.
autoRenew
If the certificate is going to be automatically renewed.
Example Request
curl "https://api.vercel.com/v3/now/certs/oAjf6y9pxZgCJyQfrclN" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "cns": ["wow.example.com"],
  "uid": "oAjf6y9pxZgCJyQfrclN",
  "created": "2016-08-23T18:13:09.773Z",
  "expiration": "2016-12-16T16:00:00.000Z",
  "autoRenew": true
}

Create a new certificate

Endpoint
POST /v3/now/certs

Issues and stores a new certificate for the common names given in the body using Let's Encrypt.

The body should contain `domains` array and it may contain `renew` field to renew an existing certificate.

Request Parameters

Key
Required
Description
domains
Yes
A list of Common Names for which the certificate is being provisioned.

Response Parameters

Key
Description
uid
The unique identifier of the issued certificate.
created_at
The date when the certificate was created.
Example Request
curl -X POST "https://api.vercel.com/v3/now/certs" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "domains": [
    "testing.example.com"
  ],
  "renew": true
}'
Example Response
{
  "uid": "zWsFytQUFlkUWaR7nWdwS7xR"
  "created_at": 2016-06-01T21:03:10.420Z"
}

Submit a certificate

Endpoint
PUT /v3/now/certs

Create a new certificate entry with a user-supplied certificate.

The body should contain cert, private key, and ca chain fields in PEM format.

Request Parameters

Key
Required
Description
ca
Yes
PEM formatted CA chain.
cert
Yes
PEM formatted certificate.
key
Yes
PEM formatted private key.

Response Parameters

Key
Description
created_at
The date when the certificate was created.
Example Request
curl -X PUT "https://api.vercel.com/v3/now/certs" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "ca": "PEM formatted CA chain",
  "cert": "PEM formatted certificate",
  "key": "PEM formatted private key"
}'
Example Response
{
  "created_at": 2016-06-01T21:03:10.420Z"
}

Delete a certificate

Endpoint
DELETE /v3/now/certs/:id

Delete an existing certificate entry. If the certificate entry was removed successfully the endpoint will return with code 200 and an empty body; Otherwise an error object is returned.

Example Request
curl -X DELETE "https://api.vercel.com/v3/now/certs/zWsFytQUFlkUWaR7nWdwS7xR" \
  -H "Authorization: Bearer <TOKEN>"

Aliases

List all the aliases

Endpoint
GET /v3/now/aliases

Retrieves active aliases for the authenticated account. By default it returns the last 20 aliases if no limit is provided.

Request Query Parameters

The response of this API can be controlled with the following optional query parameters.

Key
Description
limit
Maximum number of aliases to list from a request.
since
Get aliases created after this JavaScript timestamp.
until
Get aliases created before this JavaScript timestamp.
projectId
Filter aliases from the given projectId.

The body will contain an entry for each alias.

Response Parameters

Key
Description
uid
The unique identifier of the alias.
alias
The alias name, it could be a .now.sh subdomain or a custom domain.
created
The date when the alias was created.
createdAt
The date when the alias was created in milliseconds since the UNIX epoch.
updatedAt
The date when the alias was updated in milliseconds since the UNIX epoch.
deployment
A map with the deployment ID and URL.
deploymentId
The deployment ID.
projectId
The unique identifier of the project.

Deployment

This is the format of the deployment described above.

Key
Description
id
The deployment unique identifier.
url
The deployment unique URL.
Example Request
curl "https://api.vercel.com/v3/now/aliases" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "aliases": [
    {
      "uid": "2WjyKQmM8ZnGcJsPWMrHRHrE",
      "alias": "my-alias",
      "created": "2016-06-02T21:01:40.950Z",
      "createdAt": 1464894100000,
      "updatedAt": 1464895100000,
      "projectId": "QmXGTs7mvAMMC7WW5ebrM33qKG32QK3h4vmQMjmY",
      "deployment": {
        "id": "c9MrOWGzdJSfPxqyTDYhdEGN",
        "url": "my-app-fjvngszyiq.now.sh"
      },
      "deploymentId": "c9MrOWGzdJSfPxqyTDYhdEGN"
    },
    {
      "uid": "CR3bdJZkiaAuh9yr0OHXJJPG",
      "alias": "my-alias-2",
      "created": "2016-06-01T21:03:10.420Z",
      "createdAt": 1464807790000,
      "updatedAt": 1464808790000,
      "projectId": "QmXGTs7mvAMMC7WW5ebrM33qKG32QK3h4vmQMjmY",
      "rules": [
          {
              "pathname": "/",
              "dest": "my-app-fjvngszyiq.now.sh"
          },
          {
              "dest": "my-api-ibzcpajvlo.now.sh"
          }
      ]
    }
  ],
  "pagination": {
    "count": 2,
    "next": 1464807790000,
    "prev": 1464894100000
  }
}

Get a Single Alias

Endpoint
GET /v2/now/aliases/:id
GET /v2/now/aliases/:name

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

Response Parameters

Key
Description
uid
The unique identifier of the alias.
alias
The name of the alias.
deployment
An object containing the id and url of the deployment.
created
The date when the alias was created.
projectId
The unique identifier of the project.
deploymentId
The unique identifier of the deployment.
Example Request
curl "https://api.vercel.com/v2/now/aliases/2WjyKQmM8ZnGcJsPWMrHRHrE" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "uid": "2WjyKQmM8ZnGcJsPWMrHRHrE",
  "alias": "my-alias.now.sh",
  "deployment": {
    "id": "dpl_2MfpYzxMJiiPVRs7ZYqo8US9dynT",
    "url": "my-alias-repfs93ww.now.sh"
  },
  "created": "2019-07-17T17:33:35.374Z",
  "projectId": "QmPMW4P9rKjheg6k3MckC7yZjRwMB6FdE8SZBerRvHWnYs",
  "deploymentId": "dpl_2MfpYzxMJiiPVRs7ZYqo8US9dynT"
}

Remove an Alias

Endpoint
DELETE /v2/now/aliases/:id

The API allows you to delete an alias by supplying the alias :id in the url. You can obtain this id from the list of aliases.

Response Parameters

Key
Description
status
If the alias was successfully removed.
Example Request
curl -X DELETE "https://api.vercel.com/v2/now/aliases/2WjyKQmM8ZnGcJsPWMrHRHrE" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "status": "SUCCESS"
}

Purge Alias in the CDN

Endpoint
PURGE /v2/now/aliases/:id

Purges the CDN of content from the given alias via :id.

Response Parameters

Key
Description
status
The status of the purge request. The value should be REQUESTED.
Example PURGE Request
curl -X PURGE "https://api.vercel.com/v2/now/aliases/:id" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "status": "REQUESTED"
}

List aliases by deployment

Endpoint
GET /v2/now/deployments/:id/aliases

Retrieves all of the aliases for the deployment with the given :id. The authenticating user must own this deployment. The body will contain an entry for each alias.

Response Parameters

Key
Description
aliases
A list of the aliases assigned to the deployment.

Alias

This is the format of each item in the aliases list.

Key
Description
uid
The unique identifier of the alias.
alias
The alias name, it could be a .now.sh subdomain or a custom domain.
created
The date when the alias was created.
Example Request
curl "https://api.vercel.com/v2/now/deployments/7Npest0z1zW5QVFfNDBId4BW/aliases" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "aliases": [
    {
      "uid": "2WjyKQmM8ZnGcJsPWMrHRHrE",
      "alias": "my-alias",
      "created": "2016-06-02T21:01:40.950Z",
    }
  ]
}

Assign an alias to a deployment

Endpoint
POST /v2/now/deployments/:id/aliases

Creates a new alias for the deployment with the given :id. The authenticated user must own this deployment.

The JSON body of the POST should contain an alias key with the desired alias (hostname or custom url).

If the desired alias was used before it will be removed from the old deployment and assigned to the new one.

Request Parameters

Key
Required
Description
alias
Yes
The alias we want to assign to the deployment defined in the URL.
redirect
No
The redirect property will take precedence over the deployment id from the URL and consists of a hostname (like test.com) to which the alias should redirect using status code 307.

Response Parameters

Key
Description
oldID
The unique identifier of the previously aliased deployment, only received when the alias was used before.
uid
The unique identifier of the alias.
created
The date when the alias was created.
Example Request
curl -X POST "https://api.vercel.com/v2/now/deployments/7Npest0z1zW5QVFfNDBId4BW/aliases" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "alias": "my-alias.now.sh"
}'
Example Response (new alias)
{
  "uid": "2WjyKQmM8ZnGcJsPWMrHRHrE",
  "created": "2016-06-02T21:01:40.950Z"
}
Example Response (alias with existing deployment)

(oldId is the id of the previous deployment):

{
  "oldId": "c9MrOWGzdJSfPxqyTDYhdEGN",
  "uid": "2WjyKQmM8ZnGcJsPWMrHRHrE",
  "created": "2016-06-02T21:01:40.950Z"
}

Secrets

List secrets

Endpoint
GET /v3/now/secrets

Retrieves the active now secrets for the authenticating user. By default it returns 20 secrets. The rest can be retrieved using the pagination options described below. The body will contain an entry for each secret.

Request Query Parameters

The response of this API can be controlled with the following optional query parameters.

Key
Description
limit
Maximum number of secrets to list from a request.
since
Get secrets created after this JavaScript timestamp.
until
Get secrets created before this JavaScript timestamp.

Response Parameters

Key
Description
secrets
The list of active secrets.
pagination
A map with pagination options.

Secret

This is the format of each item in the secrets list.

Key
Description
uid
The unique identifier of the secret. Always prepended with sec_.
name
The name of the secret. This is what you could use in your environment variables after a @.
created
The date when the secret was created (ISO 8601).
createdAt
The date when the secret was created (timestamp).

Pagination

This is the format of the pagination map.

Key
Description
count
The number of returned secrets.
next
The JavaScript timestamp to fetch the next set of secrets.
prev
The JavaScript timestamp to fetch the previous set of secrets.
Example Request
curl "https://api.vercel.com/v3/now/secrets" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "secrets": [
    {
      "uid": "sec_T70JHBhR1gqaxXVrLTsHr6B9",
      "name": "guillermo",
      "created": "2016-09-02T01:03:50.000Z"
      "createdAt": "1472771030000"
    },
    {
      "uid": "sec_T70JHBhR1gqaxXVrLTsHr6C0",
      "name": "new-secret",
      "created": "2016-09-01T01:03:50.000Z"
      "createdAt": "1472684630000"
    }
  ],
  "pagination": {
    "count": 2,
    "next": 1472684630000,
    "prev": 1472771030000
  }
}

Get a Single Secret

Endpoint
GET /v3/now/secrets/:id
GET /v3/now/secrets/:name

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

Response Parameters

Key
Description
uid
The unique identifier of the secret.
name
The name of the secret.
teamId
The team unique identifier to which the secret belongs to.
userId
The unique identifier of the user who created the secret.
created
The date when the secret was created.
createdAt
The date when the secret was created in milliseconds since the UNIX epoch.
Example Request
curl "https://api.vercel.com/v3/now/secrets/secret-name" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
    "uid": "sec_RKc5iV0rV3ZSrFrHiruRno7k",
    "name": "secret-name",
    "teamId": null,
    "userId": "kr1PsOIzqEL5Xg6M4VZcZosf",
    "created": "2020-03-30T19:14:50.435Z",
    "createdAt": 1585595690436
}

Create a new secret

Endpoint
POST /v2/now/secrets

Creates a new secret. The body should contain name and value strings.

Note: The name of the secret couldn't be bigger than 100 characters.

Request Parameters

Key
Required
Description
name
Yes
The name of the secret (max 100 characters).
value
Yes
The value of the new secret.

Response Parameters

Key
Description
uid
The unique identifier of the secret. Always prepended with sec_.
name
The name of the secret.
created
The date when the secret was created.
userId
The unique identifier of the user who created the secret.
value
A map with the value of the secret.

Secret value

This is the format of the Map received as value.

Key
Description
type
The type of structure used to save the secret value (always Buffer).
data
A list of numbers which could be used to recreate the secret value.
Example Request
curl -X POST "https://api.vercel.com/v2/now/secrets" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-api-key",
  "value": "my-value"
}'
Example Response
{
  "uid": "sec_XCG7t7AIHuO2SBA8667zNUiM",
  "name": "my-api-key",
  "created": "2017-09-22T13:11:49.180Z",
  "userId": "kr1PsOIzqEL5Xg6M4VZcZosf",
  "value": {
    "type": "Buffer",
    "data": [
      109,
      121,
      45,
      118,
      97,
      108,
      117,
      101
    ]
  }
}

Change secret name

Endpoint
PATCH /v2/now/secrets/:name

This endpoint provides an opportunity to edit the name of a user's secret. The name has to be unique to that user's secrets.

The body must contain a field name with the new name to use.

Request Parameters

Key
Required
Description
name
Yes
The new name of the secret.

Response Parameters

Key
Description
uid
The unique identifier of the secret. Always prepended with sec_.
name
The new name of the secret.
created
The date when the secret was created.
oldName
The old name of the secret.
Example Request
curl -X PATCH "https://api.vercel.com/v2/now/secrets/my-api-key" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-renamed-api-key"
}'
Example Response
{
  "uid": "sec_XCG7t7AIHuO2SBA8667zNUiM",
  "name": "my-api-key",
  "created": "2017-09-22T13:11:49.180Z",
  "oldName": "my-api-key"
}

The uid returned is that of the matched secret.

Delete a secret

Endpoint
DELETE /v2/now/secrets/:name

This deletes the user's secret defined in the URL.

Response Parameters

Key
Description
uid
The unique identifier of the secret. Always prepended with sec_.
name
The name of the secret.
created
The date when the secret was created.
Example Request
curl -X DELETE "https://api.vercel.com/v2/now/secrets/my-renamed-api-key" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "uid": "sec_XCG7t7AIHuO2SBA8667zNUiM",
  "name": "my-renamed-api-key",
  "created": "2017-09-22T13:11:49.180Z"
}

The uid returned is that of the matched secret.

Teams

Create a Team

Endpoint
POST /v1/teams

Create a new Team under your account. You need to send a POST request with the desired Team slug, and optionally the Team name.

Request Parameters

Key
Required
Description
slug
Yes
The desired slug for the Team.
name
No
The desired name for the Team.
Example Request
curl -X POST "https://api.vercel.com/v1/teams" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "slug": "a-random-team",
  "name": "a-random-team-name"
}'
Example Response
{
  "id": "team_LLHUOMOoDlqOp8wPE4kFo9pE"
}

Delete a Team

Endpoint
DELETE /v1/teams/:id

Delete a team under your account. You need to send a DELETE request with the desired team id.

Request Parameters

Key
Required
Description
id
Yes
The desired id for the team.
Example Request
curl -X DELETE "https://api.vercel.com/v1/teams/team_LLHUOMOoDlqOp8wPE4kFo9pE" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json"
Example Response
{
  "id": "team_LLHUOMOoDlqOp8wPE4kFo9pE"
}

List all your teams

Endpoint
GET /v1/teams

Get a list of all the team you belong to.

Response Parameters

Key
Description
teams
The list of each team member as described on Get single team information.
Example Request
curl "https://api.vercel.com/v1/teams" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "teams": [
    {
      "id": "team_ofwUZockJlL53hINUGCc1ONW",
      "slug": "my-team",
      "name": "My Team",
      "creatorId": "2qDDuGFTWXBLDNnqZfWPDp1A",
      "created": "2017-04-29T17:21:54.514Z",
      "avatar": null
    }
  ]
}

Get single team information

Endpoint
GET /v1/teams/:id
GET /v1/teams?slug

Get the information of a specific team, it could be used either passing the :id in the URL or the team slug as a query parameter.

Response Parameters

Key
Description
id
The team unique identifier. Always prepended by team_.
slug
The team slug. A slugified version of the name.
name
The name of the team.
creatorId
The ID of the user who created the team.
avatar
Example Request
curl "https://api.vercel.com/v1/teams/team_ofwUZockJlL53hINUGCc1ONW" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "id": "team_ofwUZockJlL53hINUGCc1ONW",
  "slug": "my-team",
  "name": "My Team",
  "creatorId": "2qDDuGFTWXBLDNnqZfWPDp1A",
  "created": "2017-04-29T17:21:54.514Z",
  "avatar": null
}

Update team information

Endpoint
PATCH /v1/teams/:id

Update the information of the team defined with the id. You need to send a PATCH request with a body containing the information you want to change.

Note: You need to be OWNER to use it.

Request Parameters

Key
Required
Description
slug
Yes
The new team slug.
name
Yes
The new team name.
Example Request
curl -X PATCH "https://api.vercel.com/v1/teams/team_ofwUZockJlL53hINUGCc1ONW" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "My Cool Team"
}'
Example Response
{
  "id": "team_ofwUZockJlL53hINUGCc1ONW",
  "slug": "my-team",
  "name": "My Cool Team",
  "creator_id": "2qDDuGFTWXBLDNnqZfWPDp1A",
  "creatorId": "2qDDuGFTWXBLDNnqZfWPDp1A"
}

Get list of team members

Endpoint
GET /v2/teams/:id/members

Get the list of team members of the team defined in the URL. The response is a list of maps with the following format.

Response Parameters

Key
Description
uid
The team member unique identifier.
role
The role inside the team, it could be OWNER or MEMBER.
email
The email address of the team member.
username
The username of the team member.
confirmed
If the member's request to join the team is still pending or if the member still needs to accept their invitation, the value will be false. Otherwise it will be true.
accessRequestedAt
Timestamp for when the user requested access to the team.
Example Request
curl "https://api.vercel.com/v2/teams/team_ofwUZockJlL53hINUGCc1ONW/members" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  members: [
    {
      "uid": "2qDDuGFTWXBLDNnqZfWPDp1A",
      "role": "OWNER",
      "email": "user-emailgmail.com",
      "username": "some-user",
      "confirmed": true
    },
    {
      "uid": "JJHkdv6NaPOTH88pXn8FEuGz",
      "role": "OWNER",
      "email": "another-user@mail.com",
      "username": "another-user",
      "confirmed": true
    }
  ]
}

Invite user to team

Endpoint
POST /v1/teams/:id/members

Invite a user to join the team specified in the URL. To use it send a POST request with the user email in the body.

Note: The authenticated user needs to be an OWNER in order to be able to successfully invoke this endpoint.

Note: Users requesting access must be accepted instead of invited. Learn More

Request Parameters

Key
Required
Description
email
Yes
The email address of the user to invite.
role
No
The role of the user to invite, it could be OWNER or MEMBER. If not defined, the default is MEMBER.

Response Parameters

Key
Description
uid
The ID of the invited user.
username
The username of the invited user.
Example Request
curl -X POST "https://api.vercel.com/v1/teams/team_ofwUZockJlL53hINUGCc1ONW/members" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "user@mail.com"
}'
Example Response
{
  "uid": "kr1PsOIzqEL5Xg6M4VZcZosf",
  "username": "an-user"
}

Change user role or status

Endpoint
PATCH /v1/teams/:id/members/:userId

Change the role or status of an user inside a team member. To change it send a PATCH request, if the change is done you will receive a 200 status code with an empty body.

Note: You need to be OWNER to use it.

Request Parameters

Key
Required
Description
role
No
The new role of the team member, it could be OWNER or MEMBER.
confirmed
No
If the user has requested access to the team, setting this field to true will accept their request.
Example Request
curl -X PATCH "https://api.vercel.com/v1/teams/team_ofwUZockJlL53hINUGCc1ONW/members/kr1PsOIzqEL5Xg6M4VZcZosf" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "OWNER"
}'

Request to join to a team

Endpoint
POST /v1/teams/:id/request

Request to join a team as a MEMBER. An OWNER of the team can accept or decline this request.

Note: Only 10 users can request access to a team at the same time. Learn More

Request Parameters

Key
Required
Description
joinedFrom.origin
Yes
Where the member has joined the team from. Either mail, link, import, onboarding, github, gitlab, or bitbucket.
joinedFrom.commitId
No
This field is required for GitHub, GitLab, and Bitbucket. The SHA of the commit that will be deployed.
joinedFrom.repoId
No
This field is required for GitHub, GitLab, and Bitbucket. The ID of the repository that will be deployed.
Example Request
curl -X POST "https://api.zeit.co/v1/teams/team_ofwUZockJlL53hINUGCc1ONW/request" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "joinedFrom": "import"
}'

Check status of a join request

Endpoint
GET /v1/teams/:id/request

Returns the status of a join request. It'll respond with a 404 if the request has been declined.

Response Parameters

Key
Description
confirmed
The value is true for users that were already accepted. If they are in a pending state it'll be false.
accessRequestedAt
Timestamp in milliseconds that indicates when the user requested access.
joinedFrom.origin
Where the member has joined the team from. Either mail, link, import, onboarding, github, gitlab, or bitbucket.
joinedFrom.commitId
This field is set for GitHub, GitLab, and Bitbucket. The SHA of the commit that will be deployed.
joinedFrom.repoId
This field is set for GitHub, GitLab, and Bitbucket. The ID of the repository that will be deployed. For GitHub and Bitbucket it can be a number.
Example Request
curl "https://api.zeit.co/v1/teams/team_ofwUZockJlL53hINUGCc1ONW/request" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json"
Example Response
{
  "confirmed": false,
  "accessRequestedAt": 1591279968068,
  "joinedFrom": {
    "origin": "github",
    "commitId": "9aef718917d938f51cbb031006ff5b943a55f774",
    "repoId": 67753070
  }
}

Remove user from team

Endpoint
DELETE /v1/teams/:id/members/:userId

Remove the specified user from a team.

Note: You need to be OWNER to use it and the user must not be an owner themselves.
Example Request
curl -X DELETE "https://api.vercel.com/v1/teams/team_ofwUZockJlL53hINUGCc1ONW/members/kr1PsOIzqEL5Xg6M4VZcZosf" \
  -H "Authorization: Bearer <TOKEN>"

Projects

Create a Project

Endpoint
POST /v6/projects/

Create a new project with the name request parameter. If the project already exists, fails with 409 status code.

Request Parameters

Key
Required
Description
name
Yes
The desired name for the project.
gitRepository
No
The Git Repository that will be connected to the project. When this is defined, any pushes to the specified connected Git Repository will be automatically deployed.
Git Repository

The Git Repository that will be connected to the project. Any pushes to the specified connected Git Repository will be automatically deployed. The Repository can be changed from the Dashboard in the Git Project Settings.

Key
Required
Description
type
Yes
The Git Provider of the repository. Must be either github, gitlab, or bitbucket.
repo
Yes
The name of the Git Repository.
Example Request
curl -X POST "https://api.vercel.com/v6/projects/" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "a-project-name"
}'
Example Response
{
  "id":"QmQKrt94KYKF3sDysJq19N87uMmE8Wicbt2GirePy1dH8U",
  "name":"a-project-name",
  "alias":[
    {
      "domain": "a-project-name-elegant-deer.now.sh",
      "target": "PRODUCTION",
      "createdAt": 1555413045188,
      "configuredBy": "A",
      "configuredChangedAt": 1555413045188
    }
  ],
  "accountId":"K4amb7K9dAt5R2vBJWF32bmY",
  "updatedAt":1555413045188,
  "createdAt":1555413045188
}

Ensure a Project Exists

Endpoint
POST /v1/projects/ensure-project

Create a project with the name request parameter if it does not already exist. Updates the project updatedAt if it already exists.

Request Parameters

Key
Required
Description
name
Yes
The desired name for the project.
Example Request
curl -X POST "https://api.vercel.com/v1/projects/ensure-project" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "a-project-name"
}'
Example Response
{
  "id":"QmQKrt94KYKF3sDysJq19N87uMmE8Wicbt2GirePy1dH8U",
  "name":"a-project-name",
  "alias":[
    {
      "domain": "a-project-name-elegant-deer.now.sh",
      "target": "PRODUCTION",
      "createdAt": 1555413045188,
      "configuredBy": "A",
      "configuredChangedAt": 1555413045188
    }
  ],
  "accountId":"K4amb7K9dAt5R2vBJWF32bmY",
  "updatedAt":1555413045188,
  "createdAt":1555413045188
}

Get Projects

Endpoint
GET /v4/projects/

Get a list of the projects you currently have under your account.

By default, it returns the last 20 projects. The rest can be retrieved using the pagination options described below.

Note: The order is always based on the updatedAt field of the project.

Query Parameters

Key
Required
Description
limit
No
Limit the number of projects returned.
since
No
The updatedAt point where the list should start.
until
No
The updatedAt point where the list should end.
search
No
Search projects by the name field.
Example Request
curl "https://api.vercel.com/v4/projects/?limit=2" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "projects": [
    {
      "id":"QmQKrt94KYKF3sDysJq19N8gvhmE8Wicbt2GirePy1dH8U",
      "name":"a-project-name",
      "accountId":"K4amb7K9dAt5R2vBJWF32bmY",
      "createdAt":1555413045188,
      "updatedAt":1555413045188,
      "targets": {},
      "latestDeployments": []
    },
    {
      "id":"QmRhxc9HAmRMcLvWhCAf2ALLctxZ4s4fwsM1D5kNM8PJuL",
      "name":"another-project-name",
      "accountId":"K4amb7K9dAt5R2vBJWF32bmY",
      "createdAt":1555072968396,
      "updatedAt":1555345633993,
      "targets": {},
      "latestDeployments": []
    }
  ],
  "pagination": {
    "count": 2,
    "next": 1555072968396,
    "prev": 1555413045188
  }
}

Get a Single Project

Endpoint
GET /v1/projects/:id
GET /v1/projects/:name

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

URL Parameters

Key
Required
Description
id
No
The unique project identifier.
name
No
The project name.

Response Parameters

Key
Description
id
A string holding the unique ID of the project.
name
The name of the project.
alias
A list of production domains for the project.
accountId
The unique ID of the user or team the project belongs to.
createdAt
A number containing the date when the project was created in milliseconds.
updatedAt
A number containing the date when the project was updated in milliseconds.
env
A list of environment variables configured for the project.
targets
An object which has a production key containing the production deployment object, if a production deployment exists
latestDeployments
A list of the latest deployments for the project
Example Request
curl "https://api.vercel.com/v1/projects/a-project-name" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "id":"QmQKrt94KYKF3sDysJq19N8gvhmE8Wicbt2GirePy1dH8U",
  "name":"a-project-name",
  "alias": [
    {
      "createdAt": 1555413045188,
      "domain": "foobar.com",
      "target": "PRODUCTION",
      "configuredBy": "A",
      "configuredChangedAt": 1555413045188
    }
  ],
  "accountId":"K4amb7K9dAt5R2vBJWF32bmY",
  "createdAt":1555413045188,
  "updatedAt":1555413045188,
  "env": [
    {
      "type": "secret",
      "id": "781dt89g8r2h789g",
      "key": "API_SECRET",
      "value": "@a-new-secret",
      "configurationId": null,
      "updatedAt": 1557241361455,
      "createdAt": 1557241361455
    }
  ],
  "targets": {
    "production": {
      "alias": [
        "foobar.com"
      ],
      "aliasAssigned": 1571239348998,
      "createdAt": 1571239348998,
      "createdIn": "sfo1",
      "deploymentHostname": "a-project-name-rjtr4pz3f",
      "forced": false,
      "id": "dpl_89qyp1cskzkLrVicDaZoDbjyHuDJ",
      "meta": {},
      "plan": "pro",
      "private": true,
      "readyState": "READY",
      "requestedAt": 1571239348998,
      "target": "production",
      "teamId": null,
      "type": "LAMBDAS",
      "url": "a-project-name-rjtr4pz3f.now.sh",
      "userId": "K4amb7K9dAt5R2vBJWF32bmY"
    }
  },
  "latestDeployments": [
    {
      "alias": [
        "foobar.com"
      ],
      "aliasAssigned": 1571239348998,
      "createdAt": 1571239348998,
      "createdIn": "sfo1",
      "deploymentHostname": "a-project-name-rjtr4pz3f",
      "forced": false,
      "id": "dpl_89qyp1cskzkLrVicDaZoDbjyHuDJ",
      "meta": {},
      "plan": "pro",
      "private": true,
      "readyState": "READY",
      "requestedAt": 1571239348998,
      "target": "production",
      "teamId": null,
      "type": "LAMBDAS",
      "url": "a-project-name-rjtr4pz3f.now.sh",
      "userId": "K4amb7K9dAt5R2vBJWF32bmY"
    }
  ]
}

Update a Single Project

Endpoint
PATCH /v2/projects/:id
PATCH /v2/projects/:name

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

Request Parameters

Key
Required
Description
framework
No
The framework that is being used for this project. When null is used no framework is selected.
publicSource
No
Specifies whether the source code and logs of the deployments for this project should be public or not.
installCommand
No
The install command for this project. When null is used this value will be automatically detected.
buildCommand
No
The build command for this project. When null is used this value will be automatically detected.
devCommand
No
The dev command for this project. When null is used this value will be automatically detected.
outputDirectory
No
The output directory of the project. When null is used this value will be automatically detected.
serverlessFunctionRegion
No
The region to deploy Serverless Functions in this project.
rootDirectory
No
The name of a directory or relative path to the source code of your project. When null is used it will default to the project root.
name
No
A new name for this project.
Example Request
curl -X PATCH "https://api.vercel.com/v2/projects/a-project-name" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "framework": "nextjs",
  "publicSource": false,
  "installCommand": "yarn install",
  "buildCommand": "yarn run different-build",
  "devCommand": "yarn run different-dev",
  "outputDirectory": null
}'
Example Response
{
  "id": "QmQKrt94KYKF3sDysJq19N87uMmE8Wicbt2GirePy1dH8U",
  "name": "a-project-name",
  "accountId": "K4amb7K9dAt5R2vBJWF32bmY",
  "framework": 'nextjs',
  "publicSource": false,
  "installCommand": "yarn install",
  "buildCommand": "yarn run different-build",
  "devCommand": "yarn run different-dev",
  "outputDirectory": null,
  "updatedAt": 1555413045188,
  "createdAt": 1575972468641
}

Remove a Single Project

Endpoint
DELETE /v1/projects/:id
DELETE /v1/projects/:name

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

URL Parameters

Key
Required
Description
id
No
The unique project identifier.
name
No
The project name.
Example Request
curl -X DELETE "${API_ENDPOINT}/v1/projects/a-project-name" \
  -H "Authorization: Bearer <TOKEN>"
Note: If the request is successful, you will receive a 204 HTTP Status code in the response.

Get Project Environment Variables

Endpoint
GET /v6/projects/:id/env

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

By default, it returns the last updated 20 environment variables. The rest can be retrieved using the pagination options described below.

URL Parameters

Key
Required
Description
id
Yes
The unique project identifier.

Query Parameters

Key
Required
Description
limit
No
Maximum number of environment variables to list from a request.
since
No
Get environment variables updated after this JavaScript timestamp.
until
No
Get environment variables updated before this JavaScript timestamp.
Example Request
curl "https://api.vercel.com/v6/projects/QmXtXGhXF6mZQ5ete2AwbeV3zAS17wEj7LYM3LuQ3Y45FF/env" \
  -H "Authorization: Bearer <TOKEN>"
Example Response

{
  "envs": [
    {
      "type": "secret",
      "id": "781dt89g8r2h789g",
      "key": "API_SECRET_2",
      "value": "secret_id_123456789",
      "target": ["production", "preview"],
      "configurationId": null,
      "updatedAt": 1557241361455,
      "createdAt": 1557241361455
    },
    {
      "type": "secret",
      "id": "r124t6frtu25df16",
      "key": "API_SECRET_1",
      "value": "secret_id_123456788",
      "target": "production",
      "configurationId": null,
      "updatedAt": 1557241361445,
      "createdAt": 1557241361445
    },
    {
      "type": "secret",
      "id": "1rtu37gupq8bg67y",
      "key": "API_SECRET",
      "value": "secret_id_123456787",
      "target": "production",
      "configurationId": null,
      "updatedAt": 1557241361435,
      "createdAt": 1557241361435
    }
  ],
  "pagination": {
    "count": 3,
    "next": 1557241361435,
    "prev": 1557241361455
  }
}

Create a Project Environment Variable

Endpoint
POST /v6/projects/:id/env

Create a new environment variable for the project by passing the project id in the URL and a key and value as request parameters.

Note: For security, environment variable values must reference a secret.

Note: Changes to environment variables are not applied to existing deployments. The changes are only applied to new deployments.

URL Parameters

Key
Required
Description
id
Yes
The unique project identifier.

Request Parameters

Key
Required
Description
type
Yes
The type can be plain, secret, or system.
key
Yes
The name of the environment variable.
value
Yes
If the type is plain, a string representing the value of the environment variable.
If the type is secret, the secret ID of the secret attached to the environment variable.
If the type is system, the name of the System Environment Variable.
target
Yes
The target can be a list of development, preview, or production.
Example Request with secret type
curl -X POST "https://api.vercel.com/v6/projects/QmXtXGhXF6mZQ5ete2AwbeV3zAS17wEj7LYM3LuQ3Y45FF/env" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "API_SECRET",
  "value": "sec_123456789",
  "target": [
    "production",
    "preview"
  ]
}'
Example Response
{
  "type": "secret",
  "id": "781dt89g8r2h789g",
  "key": "API_SECRET",
  "value": "sec_123456789",
  "target": ["production", "preview"],
  "configurationId": null,
  "updatedAt": 1557241361455,
  "createdAt": 1557241361455
}
Example Request with plain type
curl -X POST "https://api.vercel.com/v6/projects/QmXtXGhXF6mZQ5ete2AwbeV3zAS17wEj7LYM3LuQ3Y45FF/env" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "plain",
  "key": "MY_PLAIN_ENV_VARIABLE",
  "value": "hello",
  "target": [
    "production",
    "preview"
  ]
}'
Example Response
{
  "type": "plain",
  "key": "MY_PLAIN_ENV_VARIABLE",
  "value": "hello",
  "target": ["production", "preview"],
  "configurationId": null,
  "updatedAt": 1557241361455,
  "createdAt": 1557241361455
}
Example Request with system type
curl -X POST "https://api.vercel.com/v6/projects/QmXtXGhXF6mZQ5ete2AwbeV3zAS17wEj7LYM3LuQ3Y45FF/env" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "system",
  "key": "MY_VERCEL_URL",
  "value": "VERCEL_URL",
  "target": [
    "production",
    "preview"
  ]
}'
Example Response
{
  "type": "system",
  "key": "MY_VERCEL_URL",
  "value": "VERCEL_URL",
  "target": ["production", "preview"],
  "configurationId": null,
  "updatedAt": 1557241361455,
  "createdAt": 1557241361455
}
Note: The configurationId depends on the token used to make the request.

Edit a Project Environment Variable

Endpoint
PATCH /v6/projects/:projectId/env/:envId

Edit an Environment Variable for a Project by passing projectId and envId in the URL and a key, value, target, type as request parameters.

Note: Changes to Environment Variables are not applied to existing Deployments. The changes are only applied to new Deployments.

URL Parameters

Key
Required
Description
projectId
Yes
The unique Project identifier.
envId
Yes
The unique Environment Variable identifier.

Request Parameters

Key
Required
Description
type
No
The type can be plain, secret, or system.
key
No
The name of the Environment Variable.
value
No
The value of the Environment Variable.
target
No
The target can be a list of development, preview, or production.
Example Request
curl -X PATCH "https://api.vercel.com/v6/projects/QmXtXGhXF6mZQ5ete2AwbeV3zAS17wEj7LYM3LuQ3Y45FF/env/781dt89g8r2h789g" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "API_SECRET",
  "value": "secret_id_123456789",
  "target": [
    "production",
    "preview"
  ],
  "type": "secret"
}'
Example Response
{
  "type": "secret",
  "id": "781dt89g8r2h789g",
  "key": "API_SECRET",
  "value": "secret_id_123456789",
  "target": ["production", "preview"],
  "configurationId": null,
  "updatedAt": 1557241361455,
  "createdAt": 1557241361455
}

Delete a Specific Environment Variable

Endpoint
DELETE /v4/projects/:id/env/:key?target=:target

Delete a specific environment variable for a given project by passing the project id, env key, and target in the URL.

URL Parameters

Key
Required
Description
id
Yes
The unique project identifier.
key
Yes
The name of the environment variable.
target
No
The target can be development, preview, or production.
Example Request
curl -X DELETE "https://api.vercel.com/v1/projects/QmXtXGhXF6mZQ5ete2AwbeV3zAS17wEj7LYM3LuQ3Y45FF/env/API_SECRET?target=production" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "type": "secret",
  "key": "API_SECRET",
  "value": "secret_id_123456789",
  "target": "production",
  "configurationId": null,
  "updatedAt": 1557241361455,
  "createdAt": 1557241361455
}

Add a Domain to a Project

Endpoint
POST /v1/projects/:id/alias

Add a domain to the project by passing the project id in the URL and the domain and redirect as request parameters. If the domain already exists on the project, fails with 400 status code.

URL Parameters

Key
Required
Description
id
Yes
The unique project identifier.

Request Parameters

Key
Required
Description
domain
Yes
The name of the production domain.
redirect
No
Target destination domain for redirect
Note: You can only redirect to domains that belong to the project.
Example Request
curl -X POST "https://api.vercel.com/v1/projects/QmXtXGhXF6mZQ5ete2AwbeV3zAS17wEj7LYM3LuQ3Y45FF/alias" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "domain": "foobar.com",
  "redirect": null
}'
Example Response (successful)
[
  {
    "createdAt": 1562119110860,
    "domain": "foobar.com",
    "target": "PRODUCTION",
    "configuredBy": "A",
    "configuredChangedAt": 1562119110860
  }
]
Example response (unsuccessful)
{
  "error": {
    "code": "ALIAS_DOMAIN_EXIST",
    "domain": "foobar.com",
    "project": {
      "id": "QmXtXGhXF6mZQ5ete2AwbeV3zAS17wEj7LYM3LuQ3Y45FF",
      "name": "a-project-name",
      "accountId": "K4amb7K9dAt5R2vBJWF32bmY",
    }
  }
}
Note: The response will include all production domains configured for the project.
Note: You can also get the production domains from the alias field of a project, returned by any other project API endpoints.

Set Redirect for a Domain

Endpoint
PATCH /v1/projects/:id/alias

Set redirect from specified domain to a different domain in the same project (status code 307).

URL Parameters

Key
Required
Description
id
Yes
The unique project identifier.

Request Parameters

Key
Required
Description
domain
Yes
The name of the production domain.
redirect
No
Target destination domain for redirect.
Note: You can only redirect to domains that belong to the project.
Example Request
curl -X PATCH "https://api.vercel.com/v1/projects/QmXtXGhXF6mZQ5ete2AwbeV3zAS17wEj7LYM3LuQ3Y45FF/alias" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
  "domain": "www.foobar.com",
  "redirect": "foobar.com"
}'
Example response:
[
  {
    "createdAt": 1571138625066,
    "domain": "foobar.com",
    "target": "PRODUCTION",
    "configuredBy": "A",
    "configuredChangedAt": 1571945629322
  },
  {
    "createdAt": 1571921061602,
    "domain": "www.foobar.com",
    "target": "PRODUCTION",
    "redirect": "foobar.com",
    "configuredBy": "CNAME",
    "configuredChangedAt": 1571945629501
  }
]
Note: The response will include all production domains configured for the project.
Note: You can also retrieve the production domains from the alias field of a project, returned by any other project API endpoints.

Delete a Specific Production Domain of a Project

Endpoint
DELETE /v1/projects/:id/alias?domain

Delete a specific production domain configuration from a project by passing the project id and a domain query in the URL.

Note: After deleting the domain, all remaining aliases and deployments will not be affected.

URL Parameters

Key
Required
Description
id
Yes
The unique project identifier.

Query Parameters

Key
Required
Description
domain
Yes
The name of the production domain.
Example Request
curl -X DELETE "https://api.vercel.com/v1/projects/QmXtXGhXF6mZQ5ete2AwbeV3zAS17wEj7LYM3LuQ3Y45FF/alias?domain=foobar.com" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
[]
Note: The response will include all the remaining production domains configured for the project.

Authentication

Request a login

Endpoint
POST /now/registration

Request a new login for an user to get a token.

Request Parameters

Key
Required
Description
email
Yes
The user email.
tokenName
Yes
The desired name for the token. It will be displayed on the user account details.

Response Parameters

Key
Description
token
The token used to verify the user accepted the login request.
securityCode
The code the user is going to receive on the email. Must be displayed to the user so they can verify the request is the correct.
Example Request
curl -X POST "https://api.vercel.com/now/registration" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "user@mail.com",
  "tokenName": "Your Client App Name"
}'
Example Response
{
  "token": "T1dmvPu36nmyYisXAs7IRzcR",
  "securityCode": "Practical Saola"
}

Verify login

Endpoint
GET /now/registration/verify?email&token

Verify the user accepted the login request and get a authentication token. The user email address and the token received after requesting the login must be added to the URL as a query string with the names email and token.

Response Parameters

Key
Description
token
The user authentication token you can use as described in API Basics - Authentication.
Example Request
curl "https://api.vercel.com/now/registration/verify?email=user@mail.com&token=T1dmvPu36nmyYisXAs7IRzcR"
Example Response
{
  "token": "sGkHhSH98wtJB0lyODZJ2bRe"
}

OAuth2

OAuth2 lets your app request authorization to private details in a user's Vercel account. When using OAuth Apps, all actions are performed as the user who granted access to the OAuth App.

You will need to register your app before getting started, you can do this by visiting the Integrations Developer Console.

Authorization

Your app should redirect users to the following URL:

https://vercel.com/oauth/authorize

You will pass the following values as query parameters:

Key
Required
Description
client_id
Yes
ID of your application.
state
No
Random string to be passed back upon completion. It is used to protect against CSRF attacks.

If the user grants your request, we redirect back to your site with a code parameter and a state parameter if you provided one in previous step.

Note: The process should be aborted if the states do not match.
Example Request
https://vercel.com/oauth/authorize?client_id=oac_s4cllbR9Ao8307IDSkluOQBS&state=t2eh4KHwNyGbo5g65VNvoFhl
Example Redirect URL:
https://example.com/oauth/callback?code=jMIukZ1DBCKXHje3X14BCkU0&state=t2eh4KHwNyGbo5g65VNvoFhl

Exchanging code for an access token

If all goes well, exchange the authorization code for an access token using the following API:

Endpoint
POST https://api.vercel.com/v2/oauth/access_token

You will pass the following values to request body in the form of application/x-www-form-urlencoded.

Key
Required
Description
client_id
Yes
ID of your application.
client_secret
Yes
Secret of your application.
code
Yes
The code you received.
redirect_uri
Yes
URL to redirect back.

You'll receive a JSON response containing an access_token:

Example Request
curl -X POST https://api.vercel.com/v2/oauth/access_token \
 -d "client_id=oac_s4cllbR9Ao8307IDSkluOQBS&client_secret=EOBPvZuBYAtb3SbYo8H1iWFP&code=jMIukZ1DBCKXHje3X14BCkU0&redirect_uri=https://example.com/oauth" \
 -H "Content-Type: application/x-www-form-urlencoded"
Example Response
{
  "access_token": "xEbuzM1ZAJ46afITQlYqH605"
}
Note: A request can only be made once with the same code.

Using access token

The access token allows you to make requests to the API on a behalf of a user, by providing the token in the Authorization header.

Installed applications

When a user authorizes an application for the first time, we create an installation for that app.

Installed applications will appear in the integrations dashboard where they can be uninstalled by the user also.

Integrations

Webhooks

Webhooks allow you to subscribe to certain events on Vercel by providing a destination URL.

We send a POST request to that URL with an event payload every time an event associated with the webhook happens.

Each URL can register up to 5 webhooks for a given team or user account.

List all Webhooks

Endpoint
GET /v1/integrations/webhooks

Retrieves a list of all webhooks that are defined for the authorized account.

Create a Webhook

Endpoint
POST /v1/integrations/webhooks

Creates a new webhook subscription.

Request Parameters

Key
Required
Description
name
Yes
The name of the webhook.
url
Yes
The url where you will receive events.
events
No
A list of events to subscribe to. Otherwise it will be subscribe to all events.

Response Parameters

Key
Description
id
The unique identifier of the webhook. Always prefixed with hook_.
url
The URL to call when an event for the webhook is triggered.
name
The name of the webhook.
events
The list of events the webhook is subcribed to.
ownerId
The identifier of the team or user whose events will trigger the webhook.
createdAt
A timestamp that tells you when the webhook was created.
Example Request
curl -X POST "https://api.vercel.com/v1/integrations/webhooks" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "My first webhook",
  "url": "https://my-webhook-handler.com/example"
}'
Example Response
{
  "id": "hook_XCG7t7AIHuO2SBA8667zNUiM",
  "url": "https://my-webhook-handler.com/example",
  "name": "My first webhook",
  "ownerId": "kr1PsOIzqEL5Xg6M4VZcZosf",
  "createdAt": 1558531915505,
  "events": []
}

Delete a Webhook

Endpoint
DELETE /v1/integrations/webhooks/:id

Deletes the webhook with the provided id.

Webhook Events

The webhook URL receives a HTTP POST request with a JSON payload for each event. All the events has the following format:

{
  "type": <event-type>,
  "createdAt": <javascript-timestamp>,
  "payload": <payload for the event>,
  "teamId": <teamId>,
  "userId": <userId>
}

Event Payloads

Here's a list of supported event types and their payload.

deployment

Occurs whenever a deployment is created.

Key
Description
deploymentId
The ID of the deployment.
project
The project name of the deployment.
url
The URL of the deployment.
plan
The plan type of the deployment.
regions
An array of the supported regions for the deployment.
deployment.meta
A Map of deployment metadata.

deployment-ready

Occurs whenever a deployment is ready.

Key
Description
deploymentId
The ID of the deployment.
project
The project name of the deployment.
url
The URL of the deployment.
plan
The plan type of the deployment.
regions
An array of the supported regions for the deployment.
deployment.meta
A Map of deployment metadata.

deployment-error

Occurs whenever a deployment has failed.

Key
Description
deploymentId
The ID of the deployment.
project
The project ID of the deployment.
plan
The plan type of the deployment.
regions
An array of the supported regions for the deployment.
deployment.meta
A Map of deployment metadata.

Securing Webhooks

Once your server is configured to receive payloads, it will listen for any payload sent to the endpoint you configured. By knowing the URL of your webhook, anybody can send you requests. It is therefore recommend to check whether the requests are coming from Vercel or not.

The recommended method to check is to use the x-vercel-signature security header you receive with each request. The value of this header corresponds to the sha1 of the payload body using your client secret.

For example, you can validate a webhook message as follows:

const crypto = require('crypto');
const { send } = require('micro');

module.exports = (req, res) => {
  const payload = await json(req);

  if (!verifySignature(req, payload)) {
    return send(res, 403, {
      code: `invalid_signature`,
      error: `signature didn't match`
    });
  }

  // Process the payload
};

function verifySignature(req, payload) {
  const signature = crypto.createHmac('sha1', process.env.OAUTH2_SECRET)
    .update(payload)
    .digest('hex');
  return signature === req.headers['x-vercel-signature'];
}

Example on how to validate a webhook message.

You can compute the signature using a HMAC hexdigest from the secret token of OAuth2 and request body, then compare it with the value of the x-vercel-signature header to validate the payload.

Log Drains

Log Drains allow you to collect logs from your deployments. To enable Log Drains, you must provide a destination URL to send the logs to.

We send logs to destination URLs over HTTPS, HTTP, TLS, or TCP every time logs are generated.

List all Log Drains

Endpoint
GET /v1/integrations/log-drains

Retrieves a list of all Log Drains that are defined for the authorized account.

Create a Log Drain

Endpoint
POST /v1/integrations/log-drains

Creates a new Log Drain subscription.

Request Parameters

Key
Required
Description
name
Yes
The name of the drain.
type
Yes
The type of log format, one of json, ndjson or syslog.
url
Yes
The URL where you will receive logs. The protocol must be https:// or http:// for the type json and ndjson, syslog+tls: or syslog: for the type syslog.
projectId
No
The ID of a project to subscribe.

See the Format and Transport section for more details on the types.

Response Parameters

Key
Description
id
The unique identifier of the drain. Always prefixed with ld_.
name
The name of the Log Drain.
type
The type of log format.
url
The URL to call when logs for the Log Drain is triggered.
ownerId
The identifier of the team or user whose logs will trigger the Log Drain.
projectId
The identifier of the project to be subscribed.
clientId
The identifier of the client which created the Log Drain.
configurationId
The identifier of the configuration which created the Log Drain.
createdAt
A timestamp that tells you when the Log Drain was created.
Example Request
curl -X POST "https://api.vercel.com/v1/integrations/log-drains" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "My first Log Drain",
  "type": "json",
  "url": "https://user:pass@my-log-drain-handler.com/example",
  "projectId": "abcdefgdufoJxB6b9b1fEqr1jUtFkyavUURbnDCFCnZxgs"
}'
Example Response
{
  "id": "ld_XCG7t7AIHuO2SBA8667zNUiM",
  "url": "https://user:pass@my-log-drain-handler.com/example",
  "name": "My first Log Drain",
  "type": "json",
  "ownerId": "kr1PsOIzqEL5Xg6M4VZcZosf",
  "projectId": "abcdefgdufoJxB6b9b1fEqr1jUtFkyavUURbnDCFCnZxgs"
  "clientId": "oac_xbk2e7gE1XYr37jTgAV4ewX6",
  "configurationId": "icfg_8ygXBI4T7VCjxZLYopICFWzX",
  "createdAt": 1558531915505
}

Delete a Log Drain

Endpoint
DELETE /v1/integrations/log-drains/:id

Deletes the Log Drain with the provided id.

Format and Transport

We support 3 types of Log Drains:

  • JSON
  • NDJSON
  • Syslog

JSON drains

When you choose the json type, the URL receives a HTTPS or HTTP POST request with a JSON array on the POST body. The logs are buffered and submitted as batches with the following formats:

[
  {
    "id": <identifier>,
    "message": <text>,
    "timestamp": <timestamp>,
    "type": <"stdout" or "stderr">,
    "source": <"build", "static", "external", or "lambda">,
    "projectId": <identifier of project>,
    "deploymentId": <identifier of deployement>,
    "buildId": <identifier of build>,
    "host": <hostname>,
    "entrypoint": <entrypoint>
  },
  {
    "id": <identifier>,
    "message": <text>,
    "timestamp": <timestamp>,
    "requestId": <identifier of request only on runtime logs>,
    "statusCode": <HTTP status code of request only on runtime logs>,
    "source": <"build", "static", "external", or "lambda">,
    "projectId": <identifier of project>,
    "deploymentId": <identifier of deployement>,
    "buildId": <identifier of build only on build logs>,
    "destination": <origin of external content only on external logs>,
    "host": <hostname>,
    "path": <path>,
    "proxy": {
      "timestamp": <timestamp of proxy request>,
      "method": <method of request>,
      "scheme": <protocol of request>,
      "host": <hostname>,
      "path": <path of proxy request>,
      "userAgent": <user agent>,
      "referer": <referer>,
      "statusCode": <HTTP status code of proxy request>,
      "clientIp": <client IP>,
      "region": <region request is processed>,
      "cacheId": <original request id when request is served from cache>,
    }
  }
]

The requests are posted with a x-vercel-signature header which contains a hash signature you can use to validate the request body. See the Securing your Log Drains section to learn how to verify requests.

NDJSON Drains

When you choose the ndjson type, the URL receives a HTTPS or HTTP POST request with JSON objects delimited by newline (\\n) on the POST body. See ndjson.org for more information on the structure.

Each request receives HTTP headers including x-vercel-signature.

The following is an example POST body:

{"id":"1573817187330377061717300000","message":"done","timestamp":1573817187330,"type":"stdout","source":"build","projectId":"abcdefgdufoJxB6b9b1fEqr1jUtFkyavUURbnDCFCnZxgs","deploymentId":"dpl_233NRGRjVZX1caZrXWtz5g1TAksD","buildId":"bld_cotnkcr76","host":"example-4lp0kffgq.now.sh","entrypoint":"api/index.js"}
{"id":"1573817250283254651097202070","message":"START RequestId: 643af4e3-975a-4cc7-9e7a-1eda11539d90 Version: $LATEST\n2019-11-15T11:27:30.721Z\t643af4e3-975a-4cc7-9e7a-1eda11539d90\tINFO\thello\nEND RequestId: 643af4e3-975a-4cc7-9e7a-1eda11539d90\nREPORT RequestId: 643af4e3-975a-4cc7-9e7a-1eda11539d90\tDuration: 16.76 ms\tBilled Duration: 100 ms\tMemory Size: 1024 MB\tMax Memory Used: 78 MB\tInit Duration: 186.49 ms\t\n","timestamp":1573817250283,"source":"lambda","requestId":"894xj-1573817250172-7847d20a4939","statusCode":200,"proxy":{"timestamp":1573817250172,"path":"/api","userAgent":["Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.97 Safari/537.36"],"referer":"http://example.now.sh","method":"GET","scheme":"https","host":"example-4lp0kffgq.now.sh","statusCode":200,"clientIp":"120.75.16.101","region":"sfo1"},"projectId":"abcdefgdufoJxB6b9b1fEqr1jUtFkyavUURbnDCFCnZxgs","deploymentId":"dpl_233NRGRjVZX1caZrXWtz5g1TAksD","host":"example-4lp0kffgq.now.sh","path":"api/index.js"}

Syslog Drain

When you choose the syslog type, the URL is connected with TLS or TCP. Log Drain messages are formatted according to RFC5424 framed using octet counting defined in RFC6587.

Syslog messages resemble the following:

425 <142>1 2019-11-15T11:42:22.562Z example-4lp0kffgq.now.sh now proxy - [proxy@54735 requestId="q8k4w-1573818142562-9adfb40ce9d4" statusCode="200" method="GET" path="/api" userAgent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.97 Safari/537.36" referer="http://example.now.sh" clientIp="120.75.16.101" region="sfo1" signature="b847f4dd531d0b41094fb4b38fd62bde0b0e29a5"]587 <150>1 2019-11-15T11:42:22.833Z example-4lp0kffgq.now.sh now lambda - [lambda@54735 requestId="q8k4w-1573818142562-9adfb40ce9d4" statusCode="200" path="api/index.js" signature="0900101157dac2a2e555524c2f8d61229b15307d"] BOMSTART RequestId: ec00309f-4514-4128-8b8a-9a0e74900283 Version: $LATEST
2019-11-15T11:42:23.176Z\\tec00309f-4514-4128-8b8a-9a0e74900283\\tINFO\\thello
END RequestId: ec00309f-4514-4128-8b8a-9a0e74900283
REPORT RequestId: ec00309f-4514-4128-8b8a-9a0e74900283\\tDuration: 20.08 ms\\tBilled Duration: 100 ms Memory Size: 1024 MB\\tMax Memory Used: 77 MB\\tInit Duration: 157.97 ms

Similar to JSON and NDJSON drains, a syslog message contains a hash signature for verifying messages on the signature key of structured data. On syslog drains, the signature is computed using an OAuth2 secret and the MSG section of the syslog format.

Securing your Log Drains

All drains support transport-level encryption using HTTPS or TLS protocols, and we strongly recommend using them on production and use others only for development and testing.

When your server starts receiving payloads, it could be a third party sending log messages to your server if they know the URL. Therefore, it is recommended to use HTTP Basic Authentication, or verify messages are sent from Vercel using an OAuth2 secret and hash signature.

For example, if you have a basic HTTP server subscribing to Log Drains, the payload can be validated like so:

const http = require('http');
const crypto = require('crypto');
http.createServer((req, res) => {
  var body = '';
  req.on('data', function (chunk) {
    body += chunk;
  });
  req.on('end', function() {
    if (!verifySignature(req, body)) {
      res.statusCode = 403;
      res.end("signature didn't match");
      return;
    }
    res.end("ok");
  });
}).listen(3000);
function verifySignature(req, body) {
  const signature = crypto.createHmac('sha1', process.env.OAUTH2_SECRET)
    .update(body)
    .digest('hex');
  return signature === req.headers['x-vercel-signature'];
}

You can compute the signature using an HMAC hexdigest from the secret token of the OAuth2 app and request body, then compare it with the value of the x-vercel-signature header to validate the payload.

Errors

Generic Errors

These error codes are consistent for all endpoints.

Forbidden

You're not authorized to use the endpoint. This usually happens due to missing an user token.

Note: Similar to the HTTP 403 Forbidden error.
{
  "error": {
    "code": "forbidden",
    "message": "Not authorized"
  }
}

Rate Limited

You exceeded the maximum allotted requests.

The limit of request is per endpoint basis so you could continue using another endpoints even if some of them give you this error.

{
  "error": {
    "code": "rate_limited",
    "message": "The rate limit of 6 exceeded for 'api-www-user-update-username'. Try again in 7 days",
    "limit": {
      "remaining": 0,
      "reset": 1571432075,
      "resetMs": 1571432075563,
      "total": 6
    }
  }
}

Bad Request

There was an error with the request, the error.message would contain information about the issue.

{
  "error": {
    "code": "bad_request",
    "message": "An english description of the error that just occurred",
  }
}

Internal Server Error

This errors is similar to the HTTP 500 Internal Server Error error code.

{
  "error": {
    "code": "internal_server_error",
    "message": "An unexpected internal error occurred"
  }
}

Resource Not Found

The requested resource could not be found

{
  "error": {
    "code": "not_found",
    "message": "Could not find the RESOURCE: ID"
  }
}

Method Unknown

The endpoint you're requesting does not handle the method you defined. The error message will contain the methods the endpoint responds to.

{
  "error": {
    "code": "method_unknown",
    "message": "This endpoint only responds to METHOD"
  }
}

Deployment Errors

These error code could happen when using any deployment related endpoint.

Missing Files

Some of the files you defined when creating the deployment are missing.

{
  "error": {
    "code": "missing_files",
    "message": "Missing files",
    "missing": []
  }
}

No Files in the Deployment

You tried to create an empty deployment.

{
  "error": {
    "code": "no_files",
    "message": "No files in the deployment"
  }
}

Too Many Environment Variables

The limit of environment variables per deployment is 100 and you defined more. The error message indicates the amount you define.

{
  "error": {
    "code": "env_too_many_keys",
    "message": "Too many env vars have been supplied (100 max allowed, but got #)"
  }
}
Note: # is your number of variables.

Environment Variable Key with Invalid Characters

Some environment variable name contains an invalid character. The only valid characters are letters, digits and _.

The error message will contain the KEY with the problem.

{
  "error": {
    "code": "env_key_invalid_characters",
    "message": "The env key "KEY" contains invalid characters. Only letters, digits and `_` are allowed",
    "key": KEY
  }
}

Environment Variable Key with a Long Name

An environment variable name is too long, the maximum permitted name is 256 characters.

The error message contains the environment KEY.

{
  "error": {
    "code": "env_key_invalid_length",
    "message": "The env key "KEY" exceeds the 256 length limit",
    "key": KEY
  }
}

Environment Variable Value with a Long Name

An environment variable value contains a value too long, the maximum permitted value is 65536 characters.

The error message contains the environment KEY.

{
  "error": {
    "code": "env_value_invalid_length",
    "message": "The env value for "KEY" exceeds the 65536 length limit",
    "key": KEY,
    "value": VALUE
  }
}

Environment Variable Value Is an Object without UID

The value of an environment variable is object but it doesn't have a uid.

The error message contains the environment KEY which has the error.

{
  "error": {
    "code": "env_value_invalid_type_missing_uid",
    "message": "The env key "KEY" passed an object as a value with no `uid` key"
  }
}

Environment Variable Value Is an Object with Unknown Props

The value of an environment variable is an object with unknown attributes, it only can have a uid key inside the object.

{
  "error": {
    "code": "env_value_invalid_type_unknown_props",
    "message": "The env key "KEY" passed an object with unknown properties. Only `uid` is allowed when passing an object"
  }
}

Environment Variable Value with an Invalid Type

An environment variable value passed is of an unsupported type.

The error message contains the environment KEY.

{
  "error": {
    "code": "env_value_invalid_type",
    "message": "The env key "KEY" passed an unsupported type for its value",
    "key": KEY
  }
}

Not Allowed to Access a Secret

You're tryin to use a secret but you don't have access to it.

{
  "error": {
    "code": "env_secret_forbidden",
    "message": "Not allowed to access secret \"NAME\"",
    "uid": UID
  }
}

Missing Secret

You're trying to use a secret as an environment value and it doesn't exists.

{
  "error": {
    "code": "env_secret_missing",
    "message": "Could not find a secret by uid "UID"",
    "uid": UID
  }
}

Domain Errors

These error code could happen when using any domains related endpoints.

Domain Forbidden

You don't have access to the domain, this usually mean this domains is owned by another account or team.

The domain is specified in the message and the DOMAIN key.

{
  "error": {
    "code": "forbidden",
    "message": "You don't have access to \"DOMAIN\"",
    "domain": DOMAIN
  }
}

Domain Not Found

The domain name could not be found in our system. Try to add it first.

{
  "error": {
    "code": "not_found",
    "message": "Domain name not found"
  }
}

Missing Domain Name

The domain name wasn't specified in the URL. This means you tried to use an endpoint which require you to define the domain name in the URL but didn't defined it.

{
  "error": {
    "code": "missing_name",
    "message": "The URL was expected to include the domain name. Example: /domains/google.com"
  }
}

Conflicting Certificates

You must remove the certificates described in the error before removing the domains.

The certificates are specified in the CERT_CNS key.

{
  "error": {
    "code": "conflict_certs",
    "message": "The following certificates must be removed before removing the domain: CERT_CNS",
    "certCNs": CERT_CNS
  }
}

Conflicting Aliases

You must remove the aliases described in the error before removing the domains.

The aliases are specified in the ALIASES key.

{
  "error": {
    "code": "conflict_aliases",
    "message": "The following aliases must be removed before removing the domain: ALIASES",
    "aliases": ALIASES
  }
}

Not Modified

When trying to modify a domain nothing was required to change.

{
  "error": {
    "code": "not_modified",
    "message": "Nothing to do"
  }
}

Missing Name for Domain

When trying to add a domain the name wasn't present in the request body.

{
  "error": {
    "code": "missing_name",
    "message": "The `name` field in the body was expected but is not present in the body payload. Example value: `example.com`"
  }
}

Invalid Name for Domain

The domain name defined in the request body is invalid.

The name is specified in the error as the NAME key.

{
  "error": {
    "code": "invalid_name",
    "message": "The `name` field contains an invalid domain name ("NAME")",
    "name": NAME
  }
}

Custom Domain Needs a Plan Upgrade

In order to add a custom domain to your account or team you need to upgrade to a paid plan.

{
  "error": {
    "code": "custom_domain_needs_upgrade",
    "message": "Domain name creation requires a premium account."
  }
}

Domain Already Exists

The domain name you're trying to add already exists.

The domain name and its current ID are received in the NAME and DOMAIN_ID keys.

{
  "error": {
    "code": "not_modified",
    "message": "The domain "NAME" already exists",
    "name": NAME,
    "uid": DOMAIN_ID
  }
}

Can't Create the Domain

The domain name can't be created. Most probably it couldn't be verified.

{
  "error": {
    "code": "forbidden",
    "message": "You don't have permission to create a domain"
  }
}

Failed to Add Domain after Purchase

We were able to purchase a domain for you but we had an error when trying to add it to your account. Please contact us on vercel.com/support or via support@vercel.com.

{
  "error": {
    "code": "failed_to_add_domain",
    "message": "The domain was bought but couldn't be added.
  }
}

Unable to Determine the Domain Price

We're unable to determine the domain price of a domain.

{
  "error": {
    "code": "service_unavailable",
    "message": "Failed to determine the domain price"
  }
}

Domain price mismatch

The expectedPrice supplied in the request body does not match the actual domain price, which is specified in the actualPrice key.

{
  "error": {
    "code": "price_mismatch",
    "message": "The expected price does not match the actual price",
    "price": ACTUAL_PRICE
  }
}

Domain Is Not Available

The domain name is not available to be purchased.

{
  "error": {
    "code": "not_available",
    "message": "Domain is not available"
  }
}

Invalid Domain Name

The domain name or TLD is invalid or not supported.

{
  "error": {
    "code": "invalid_domain",
    "message": "Invalid domain or TLD"
  }
}

Missing DNS Record Name

The DNS record key name is required and was not provided. It could be any valid DNS record.

{
  "error": {
    "code": "missing_type",
    "message": "Missing `type` parameter"
  }
}

DNS Errors

These error code could happen when using any DNS related endpoint.

Missing DNS Record Name

The DNS record key name is required and was not provided. It should be either a subdomain or @ for the domain itself.

{
  "error": {
    "code": "missing_name",
    "message": "Missing `name` parameter"
  }
}

Missing DNS Record Type

The DNS record key name is required and was not provided. It could be any valid DNS record.

{
  "error": {
    "code": "missing_type",
    "message": "Missing `type` parameter"
  }
}

OAuth2 Errors

These errors could occur when using any OAuth2 related endpoint.

Client Not Found

The OAuth2 client ID could not be found or doesn't exists.

{
  "error": {
    "code": "not_found",
    "message": "OAuth client doesn't not found: CLIENT_ID"
  }
}