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.

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.

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:

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.

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:

Endpoints

User

Get the authenticated user

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

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

Aliases

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

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:

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.

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.examples.vercel.com",
      "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"
        }
      }
    }
  }
}

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/rest-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.

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.vercel.app",
  "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"
  }
}'

Example Response

{
  "id": "dpl_6EZWg2tkQevMN76UQzFgKsD2gaNR",
  "url": "my-instant-deployment-2i7mwl1a1w.vercel.app",
  "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
}

Response Parameters

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/rest-api\">the Vercel API</a>!</p>\n    </body>\n</html>"
    }
  ],
  "projectSettings": {
    "framework": null
  }
}'

Example Response

{
  "id": "dpl_89qyp1cskzkLrVicDaZoDbjyHuDJ",
  "url": "my-instant-deployment-3ij3cxz9qr.vercel.app",
  "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

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.

Headers

The POST needs to have the following headers:

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.

Example Request

curl -X POST "https://api.vercel.com/v2/now/files" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "x-vercel-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

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.

Each deployment is an object with the following keys:

Response Parameters

Get a Single Deployment

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

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.vercel.app",
  "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.vercel.app"
  ],
  "aliasError": null,
  "aliasAssigned": true
}

Delete a Deployment

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

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

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

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

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:

Build Output Key

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

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

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.vercel.app",
  "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

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

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

Request Parameters

Response Parameters

Log Payload Key

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

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.vercel.com/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

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

Response Parameters

Log Payload Key

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

Types

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

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

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

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

Request Parameters

Response Parameters

Log Payload Key

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

Types

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

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

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.

Response Parameters

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

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

Response Parameters

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

POST /v4/domains

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

Request Parameters

Response Parameters

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

POST /v4/domains/:name/verify

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

Response Parameters

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

 /v4/domains/:name

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

Response Parameters

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

Get Auth Code for a Single Domain

 /v6/domains/:name/auth-code

Response Parameters

Example Request

curl "https://api.vercel.com/v6/domains/example.com/auth-code" \
  -H "Authorization: Bearer <TOKEN>"

Example Response (successful)

{
  "authCode": "abc123"
}

Example Response (unsuccessful)

{
  "error": {
    "code": "forbidden",
    "message": "Only team owners can access domain auth codes"
   }
}

Remove a domain by name

DELETE /v4/domains/:name

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

Response Parameters

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

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

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

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

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

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

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

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.

Response Parameters

Record

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

Pagination

This is the format of the pagination map.

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

POST /v2/domains/:domain/records

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

Request Parameters

Value

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

Response Parameters

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

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

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.

Response Parameters

Certificate

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

Pagination

This is the format of the pagination map.

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

GET /v3/now/certs/:id

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

Response Parameters

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

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

Response Parameters

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

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

Response Parameters

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

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

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.

The body will contain an entry for each alias.

Response Parameters

Deployment

This is the format of the deployment described above.

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.vercel.app"
      },
      "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.vercel.app"
          },
          {
              "dest": "my-api-ibzcpajvlo.vercel.app"
          }
      ]
    }
  ],
  "pagination": {
    "count": 2,
    "next": 1464807790000,
    "prev": 1464894100000
  }
}

Get a Single Alias

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

Example Request

curl "https://api.vercel.com/v2/now/aliases/2WjyKQmM8ZnGcJsPWMrHRHrE" \
  -H "Authorization: Bearer <TOKEN>"

Example Response

{
  "uid": "2WjyKQmM8ZnGcJsPWMrHRHrE",
  "alias": "my-alias.vercel.app",
  "deployment": {
    "id": "dpl_2MfpYzxMJiiPVRs7ZYqo8US9dynT",
    "url": "my-alias-repfs93ww.vercel.app"
  },
  "created": "2019-07-17T17:33:35.374Z",
  "projectId": "QmPMW4P9rKjheg6k3MckC7yZjRwMB6FdE8SZBerRvHWnYs",
  "deploymentId": "dpl_2MfpYzxMJiiPVRs7ZYqo8US9dynT"
}

Remove an Alias

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

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

PURGE /v2/now/aliases/:id

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

Response Parameters

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

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

Alias

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

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

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

Response Parameters

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.vercel.app"
}'

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

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.

Response Parameters

Secret

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

Pagination

This is the format of the pagination map.

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

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

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

POST /v2/now/secrets

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

Request Parameters

Response Parameters

Secret value

This is the format of the Map received as 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

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

Response Parameters

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

DELETE /v2/now/secrets/:name

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

Response Parameters

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

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

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

DELETE /v1/teams/:id

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

Request Parameters

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

GET /v1/teams

Get a list of all the team you belong to.

Response Parameters

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

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

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

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.

Request Parameters

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

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

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

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.

Request Parameters

Response Parameters

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

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.

Request Parameters

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

POST /v1/teams/:id/request

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

Request Parameters

Example Request

curl -X POST "https://api.vercel.com/v1/teams/team_ofwUZockJlL53hINUGCc1ONW/request" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "joinedFrom": "import"
}'

Check status of a join request

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

Example Request

curl "https://api.vercel.com/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

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

Remove the specified user from a team.

Example Request

curl -X DELETE "https://api.vercel.com/v1/teams/team_ofwUZockJlL53hINUGCc1ONW/members/kr1PsOIzqEL5Xg6M4VZcZosf" \
  -H "Authorization: Bearer <TOKEN>"

Projects

Create a Project

POST /v8/projects

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

Request Parameters

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.

Example Request

curl -X POST "https://api.vercel.com/v8/projects/" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "a-project-name"
}'

Example Response

{
  "id":"QmQKrt94KYKF3sDysJq19N87uMmE8Wicbt2GirePy1dH8U",
  "name":"a-project-name",
  "accountId":"K4amb7K9dAt5R2vBJWF32bmY",
  "updatedAt":1555413045188,
  "createdAt":1555413045188
}

Get Projects

GET /v8/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.

Query Parameters

Example Request

curl "https://api.vercel.com/v8/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

GET /v8/projects/:id
GET /v8/projects/:name

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

URL Parameters

Response Parameters

Example Request

curl "https://api.vercel.com/v8/projects/a-project-name" \
  -H "Authorization: Bearer <TOKEN>"

Example Response

{
  "id":"QmQKrt94KYKF3sDysJq19N8gvhmE8Wicbt2GirePy1dH8U",
  "name":"a-project-name",
  "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.vercel.app",
      "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.vercel.app",
      "userId": "K4amb7K9dAt5R2vBJWF32bmY"
    }
  ]
}

Update a Single Project

PATCH /v8/projects/:id
PATCH /v8/projects/:name

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

Request Parameters