Getting Started

Introduction

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

The following example deploys a monorepo with a static file, served through our CDN, and a serverless request handler in Node.js. This example makes use of these simple API endpoints.

Use the editor to play with the HTML, CSS, and JS files to see how Now handles them in deployment. Click "Deploy to Now" or copy and paste the curl command into your terminal to deploy.

You can use the other commands with curl by providing your testing token found here.




API Basics

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

Server Specs

Origins

The Now API serves endpoints from Origin nodes located in bru1, hnd1, iad1, sfo1.

Each request to any api.zeit.co endpoint, will be automatically resolved to the closest Origin location using Anycast. Allowing requests to be routed this way is the recommended way to use our API.

If requests are desired to hit a certain location, however, the API can be accessed through individual URLs for each Origin. For example, sfo1 can be resolved through api-sfo1.zeit.co, and bru1 can be resolved through api-bru1.zeit.co.

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 Now API, including errors, are encoded exclusively as JSON as well.

Authentication

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

Authorization: Bearer <TOKEN>

The Authorization header with a token.

API queries for resources owned by a team require a teamId query string at the end of the API endpoint URL and use the team's ID as the value:

https://api.zeit.co/v6/now/deployments?teamId=[team ID]

An API endpoint using a team ID with the teamId query string.

Note: You can find your own team's ID using the teams endpoint.

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.zeit.co/v6/now/deployments

Using version 6 of the deployments endpoint.

Types

The following is a list of the types of data used within the Now 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.
"ZEIT"
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.
{ "service": "ZEIT" }
List
A data structure with only a list of values separated by a comma.
["ZEIT", 1234, 12.34]
Enum
An Enum is a String with only a few possible valid values.
"A" | "B"
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.zeit.co/www/user

Retrieves information related to the authenticated user.

Example Request
curl "https://api.zeit.co/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":"free",
      "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 /v11/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 max length of 52 characters.
files
Yes
A list of objects with the files to be deployed.
version
Yes
The version of Now Platform to use. Must have the value of 2.
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.zeit.co" }].
regions
No
An array of the regions the deployment 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.
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.
Example Request
curl -X POST "https://api.zeit.co/v11/now/deployments" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-instant-deployment",
  "version": 2,
  "files": [
    {
      "file": "index.html",
      "data": "<!doctype html>\n<html>\n  <head>\n    <title>A simple deployment with the Now API!</title>\n  </head>\n  <body>\n    <h1>Welcome to a simple static file</h1>\n    <p>Deployed with <a href=\"https://zeit.co/docs/api\">ZEIT&apos;s Now API</a>!</p>\n    </body>\n</html>"
    }
  ]
}'
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.zeit.co/v11/now/deployments" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-instant-deployment",
  "version": 2,
  "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": "unlimited",
  "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.zeit.co/v11/now/deployments" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-instant-deployment",
  "version": 2,
  "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": "unlimited",
  "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.zeit.co/v11/now/deployments?forceNew=1" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-instant-deployment",
  "version": 2,
  "files": [
    {
      "file": "index.html",
      "data": "<!doctype html>\n<html>\n  <head>\n    <title>A simple deployment with the Now API!</title>\n  </head>\n  <body>\n    <h1>Welcome to a simple static file</h1>\n    <p>Deployed with <a href=\"https://zeit.co/docs/api\">ZEIT&apos;s Now 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": "unlimited",
  "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.zeit.co/v11/now/deployments?forceNew=1" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-instant-deployment",
  "version": 2,
  "files": [
    {
      "file": "index.html",
      "data": "<!doctype html>\n<html>\n  <head>\n    <title>A simple deployment with the Now API!</title>\n  </head>\n  <body>\n    <h1>Welcome to a simple static file</h1>\n    <p>Deployed with <a href=\"https://zeit.co/docs/api\">ZEIT&apos;s Now API</a>!</p>\n    </body>\n</html>"
    }
  ]
}'

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": "unlimited",
  "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" }.
version
The Now platform version the deployment is associated with.
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.zeit.co" }].
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.zeit.co/v11/now/deployments" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-instant-deployment",
  "version": 2,
  "files": [
    {
      "file": "index.html",
      "data": "<!doctype html>\n<html>\n  <head>\n    <title>A simple deployment with the Now API!</title>\n  </head>\n  <body>\n    <h1>Welcome to a simple static file</h1>\n    <p>Deployed with <a href=\"https://zeit.co/docs/api\">ZEIT&apos;s Now API</a>!</p>\n    </body>\n</html>"
    }
  ]
}'
Example Response
{
  "id": "dpl_89qyp1cskzkLrVicDaZoDbjyHuDJ",
  "url": "my-instant-deployment-3ij3cxz9qr.now.sh",
  "name": "my-instant-deployment",
  "meta": {},
  "plan": "unlimited",
  "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.zeit.co/v2/now/files" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "x-now-digest: 6938e4ed47a23f17ceb6dbd880ab18d2787e7946" \
  -d '<!doctype html>
<html>
 <head>
 <title>My Instant Deployment</title>
 </head>
 <body>
 <h1>My Instant Now 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" }.
version
The Now platform version the deployment is associated with.
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.zeit.co" }].
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.zeit.co/v11/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": "unlimited",
  "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.zeit.co/v11/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.zeit.co/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.zeit.co/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 Now 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 @now/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.zeit.co/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": "@now/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
    }
  ]
}

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.
types
The type of log; either: request, response, command or stdout.
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.

Types

These are the possible types of logs and 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.zeit.co/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 @now/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.zeit.co/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.zeit.co/v2/now/deployments/Cm6WigEH9EBI4Uzs2WA6qOGe/events?name=team_nLlpyC6REAzxudGFKbrMDlud-5916ac0d61abdb050d45f579aaa77c70a7&statusCode=5xx" \
  -H "Authorization: Bearer <TOKEN>"

Domains

List all the domains

Endpoint
GET /v4/domains

Retrieves a list of domains registered for the authenticating user.

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 ZEIT.
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 ZEIT CDN 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 ZEIT.
boughtAt
If it was purchased through Now 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 ZEIT DNS.
creator
An object containing information of the domain creator, including the user's id, username, and email.
Example Request
curl "https://api.zeit.co/v4/domains" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "domains": [
    {
      "id": "EmTbe5CEJyTk2yVAHBUWy4A3sRusca3GCwRjTC1bpeVnt1",
      "name": "my-zeit-domain.website",
      "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@zeit.co"
      }
    }
}

Add a New Domain

Endpoint
POST /v4/domains

Register a new domain name with Now 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 alias.zeit.co.

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 ZEIT.
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 ZEIT CDN 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 ZEIT.
boughtAt
If it was purchased through Now the date when it was purchased.
transferStartedAt
If transferred into ZEIT, The date when the domain transfer was initiated
transferredAt
The date at which the domain was successfully transferred into ZEIT. 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 ZEIT 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.zeit.co/v4/domains" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-zeit-domain.website"
}'
Example Response
{
  "domain": {
    "id": "EmTbe5CEJyTk2yVAHBUWy4A3sRusca3GCwRjTC1bpeVnt1",
    "name": "my-zeit-domain.website",
    "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@zeit.co"
    }
  }
}

Transfer In a Domain

Endpoint
POST /v4/domains

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

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 ZEIT.
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 ZEIT CDN 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 ZEIT.
boughtAt
If it was purchased through Now 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 ZEIT. 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 ZEIT 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.zeit.co/v4/domains" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "method": "transfer-in",
  "name": "my-zeit-domain.website",
  "authCode": "fdhfr820ad#@FAdlj$$",
  "expectedPrice": 8
}'
Example Response
{
  "domain": {
    "id": "EmTbe5CEJyTk2yVAHBUWy4A3sRusca3GCwRjTC1bpeVnt1",
    "name": "my-zeit-domain.website",
    "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@zeit.co"
    }
  }
}

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 ZEIT.
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 ZEIT CDN 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 ZEIT.
boughtAt
If it was purchased through Now 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 ZEIT 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.
aliases
The list of aliases created using the domain.
certs
The list of SSL certificates created for the domain.
Example Request
curl -X POST "https://api.zeit.co/v4/domains/my-zeit-domain.website/verify" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{}'
Example Response (successful)
{
  "domain": {
    "id": "EmTbe5CEJyTk2yVAHBUWy4A3sRusca3GCwRjTC1bpeVnt1",
    "name": "my-zeit-domain.website",
    "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@zeit.co"
    }
  }
}
Example Response (unsuccessful)
{
  "error": {
    "code": "verification_failed",
    "message": "The domain my-zeit-domain.website couldn't be verified. Both nameservers and TXT verification methods failed",
    "name": "my-zeit-domain.website",
    "nsVerification": {
      "name": "my-zeit-domain.website",
      "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": "my-zeit-domain.website",
      "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 ZEIT.
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 ZEIT CDN 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 ZEIT.
boughtAt
If it was purchased through Now 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 ZEIT 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.
aliases
The list of aliases created using the domain.
certs
The list of SSL certificates created for the domain.
Example Request
curl "https://api.zeit.co/v4/domains/my-zeit-domain.website" \
  -H "Authorization: Bearer <TOKEN>"
Example Response (successful)
{
  "domain": {
    "id": "EmTbe5CEJyTk2yVAHBUWy4A3sRusca3GCwRjTC1bpeVnt1",
    "name": "my-zeit-domain.website",
    "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@zeit.co"
    },
    "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 Now. 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.zeit.co/v4/domains/my-zeit-domain.website" \
  -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.zeit.co/v4/domains/status?name=my-zeit-domain.website" \
  -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.zeit.co/v4/domains/price?name=zeit.rocks" \
  -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.zeit.co/v4/domains/buy" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "zeit.rocks"
}'
Example Response (unsuccessful)
{
  "error": {
    "code": "not_available",
    "message": "Domain is not available"
  }
}

DNS

List all the DNS records of a domain

Endpoint
GET /v2/domains/:domain/records

Get a list of DNS records created for a domain name specified in the URL.

Response Parameters

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
A timestamp with the date when the record was created.
updated
A timestamp with the date when we created the deployment.
Example Request
curl "https://api.zeit.co/v2/domains/zeit.rocks/records" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "records": [
    {
      "id": "rec_38OtX1f51szRA03atCybBuZ3",
      "slug": "zeit.rocks.-address",
      "type": "ALIAS",
      "name": "",
      "value": "alias.zeit.co",
      "creator": "EvQtLv2F0FvfB5Vx4eK0R3Mf",
      "created": "1474631621542",
      "updated": null
    },
    {
      "id": "rec_Pxo2HEfutmlIYECtTE4SpDzY",
      "slug": "",
      "type": "CNAME",
      "name": "*",
      "value": "alias.zeit.co",
      "creator": "system",
      "created": "1474631619960",
      "updated": null
    }
  ]
}

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.
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
alias.zeit.co
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
alias.zeit.co
MX
An MX record specifying the mail server responsible for accepting messages on behalf of the domain name.
priority host
10 mail.zeit.rocks.
SRV
A SRV record defining servers for specified services.
priority weight port target
10 10 500 sip.zeit.rocks.
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.zeit.co/v2/domains/zeit.rocks/records" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "subdomain",
  "type": "MX",
  "value": "10 mail.zeit.rocks"
}'
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.zeit.co/v2/domains/zeit.rocks/records/rec_V0fra8eEgQwEpFhYG2vTzC3K" \
  -H "Authorization: Bearer <TOKEN>"

Certificates

List all the certificates

Endpoint
GET /v3/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.

Response Parameters

Key
Description
certs
The list of issued certificates.

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.
autoRenew
If the certificate is going to be automatically renewed.
Example Request
curl "https://api.zeit.co/v3/now/certs" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "certs": [
    {
      "cns": ["testing.zeit.co", "*.zeit.co"],
      "uid": "oAjf6y9pxZgCJyQfrclN",
      "created": "2016-08-23T18:13:09.773Z",
      "expiration": "2016-12-16T16:00:00.000Z",
      "autoRenew": true
    }
  ]
}

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.zeit.co/v3/now/certs/oAjf6y9pxZgCJyQfrclN" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "cns": ["wow.zeit.co"],
  "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.zeit.co/v3/now/certs" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "domains": [
    "testing.zeit.co"
  ],
  "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.zeit.co/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.zeit.co/v3/now/certs/zWsFytQUFlkUWaR7nWdwS7xR" \
  -H "Authorization: Bearer <TOKEN>"

Aliases

List all the aliases

Endpoint
GET /v2/now/aliases

Retrieves all of the active aliases for the authenticated account.

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.
from
Get aliases created after 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.
deployment
A map with the deployment ID and URL.
deploymentId
The deployment ID.

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.zeit.co/v2/now/aliases" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "aliases": [
    {
      "uid": "2WjyKQmM8ZnGcJsPWMrHRHrE",
      "alias": "my-alias",
      "created": "2016-06-02T21:01:40.950Z",
      "deployment": {
        "id": "c9MrOWGzdJSfPxqyTDYhdEGN",
        "url": "my-app-fjvngszyiq.now.sh"
      },
      "deploymentId": "c9MrOWGzdJSfPxqyTDYhdEGN"
    },
    {
      "uid": "CR3bdJZkiaAuh9yr0OHXJJPG",
      "alias": "my-alias-2",
      "created": "2016-06-01T21:03:10.420Z",
      "rules": [
          {
              "pathname": "/",
              "dest": "my-app-fjvngszyiq.now.sh"
          },
          {
              "dest": "my-api-ibzcpajvlo.now.sh"
          }
      ]
    }
  ]
}

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.zeit.co/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.zeit.co/v2/now/aliases/2WjyKQmM8ZnGcJsPWMrHRHrE" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "status": "SUCCESS"
}

Purge Alias in Now 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.zeit.co/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.zeit.co/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.zeit.co/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 all the secrets

Endpoint
GET /v2/now/secrets

Retrieves all of the active now secrets for the authenticating user. The body will contain an entry for each secret.

Response Parameters

Key
Description
secrets
The list of active secrets.

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.
Example Request
curl "https://api.zeit.co/v2/now/secrets" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
{
  "secrets": [
    {
      "uid": "sec_T70JHBhR1gqaxXVrLTsHr6B9",
      "name": "guillermo",
      "created": "2016-09-02T01:03:50.000Z"
    }
  ]
}

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.zeit.co/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.zeit.co/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.zeit.co/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.

Request Parameters

Key
Required
Description
slug
Yes
The desired slug for the team.
Example Request
curl -X POST "https://api.zeit.co/v1/teams" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "slug": "a-random-team"
}'
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.zeit.co/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.zeit.co/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.zeit.co/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.zeit.co/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 /v1/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.
Example Request
curl "https://api.zeit.co/v1/teams/team_ofwUZockJlL53hINUGCc1ONW/members" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
[
  {
    "uid": "2qDDuGFTWXBLDNnqZfWPDp1A",
    "role": "OWNER",
    "email": "user-emailgmail.com",
    "username": "some-user"
  },
  {
    "uid": "JJHkdv6NaPOTH88pXn8FEuGz",
    "role": "OWNER",
    "email": "another-user@mail.com",
    "username": "another-user"
  }
]

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: You need to be OWNER to use it.

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.zeit.co/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.
rejected
No
Whether the team member is prevented from ever joining the team.
Example Request
curl -X PATCH "https://api.zeit.cov/v1/teams/team_ofwUZockJlL53hINUGCc1ONW/members/kr1PsOIzqEL5Xg6M4VZcZosf" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "OWNER",
  "rejected": true
}'

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.zeit.co/v1/teams/team_ofwUZockJlL53hINUGCc1ONW/members/kr1PsOIzqEL5Xg6M4VZcZosf" \
  -H "Authorization: Bearer <TOKEN>"

Projects

Create a Project

Endpoint
POST /v1/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.
Example Request
curl -X POST "https://api.zeit.co/v1/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.zeit.co/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 All Projects

Endpoint
GET /v2/projects/

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

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.
from
No
The updatedAt point where the list should start.
search
No
Search projects by the name field.
Example Request
curl "https://api.zeit.co/v2/projects/?limit=2" \
  -H "Authorization: Bearer <TOKEN>"
Example Response

[
  {
    "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": []
  }
]

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.zeit.co/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": [
    {
      "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": "unlimited",
      "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": "unlimited",
      "private": true,
      "readyState": "READY",
      "requestedAt": 1571239348998,
      "target": "production",
      "teamId": null,
      "type": "LAMBDAS",
      "url": "a-project-name-rjtr4pz3f.now.sh",
      "userId": "K4amb7K9dAt5R2vBJWF32bmY"
    }
  ]
}

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 "https://api.zeit.co/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 /v1/projects/:id/env

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

URL Parameters

Key
Required
Description
id
Yes
The unique project identifier.
Example Request
curl "https://api.zeit.co/v1/projects/QmXtXGhXF6mZQ5ete2AwbeV3zAS17wEj7LYM3LuQ3Y45FF/env" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
[
  {
    "key": "API_SECRET",
    "value": "@a-new-secret",
    "configurationId": null,
    "updatedAt": 1557241361455,
    "createdAt": 1557241361455
  }
]

Create a Project Environment Variable

Endpoint
POST /v1/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, only secrets can be used for these environment variables.
Note: Only deployments made after this call will receive the environment variables set.

URL Parameters

Key
Required
Description
id
Yes
The unique project identifier.

Request Parameters

Key
Required
Description
key
Yes
The name of the environment variable.
value
Yes
The value of the environment variable.
Example Request
curl -X POST "https://api.zeit.co/v1/projects/QmXtXGhXF6mZQ5ete2AwbeV3zAS17wEj7LYM3LuQ3Y45FF/env" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "API_SECRET",
  "value": "@a-new-secret"
}'
Example Response
[
  {
    "key": "API_SECRET",
    "value": "@a-new-secret",
    "configurationId": null,
    "updatedAt": 1557241361455,
    "createdAt": 1557241361455
  }
]
Note: The response will include all environment variables for the project.
Note: The configurationId depends on the token used to make the request.

Delete a Specific Environment Variable

Endpoint
DELETE /v1/projects/:id/env/:key

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

URL Parameters

Key
Required
Description
id
Yes
The unique project identifier.
key
Yes
The environment variable key.
Example Request
curl -X DELETE "https://api.zeit.co/v1/projects/QmXtXGhXF6mZQ5ete2AwbeV3zAS17wEj7LYM3LuQ3Y45FF/env/API_SECRET" \
  -H "Authorization: Bearer <TOKEN>"
Example Response
[]
Note: The response will include all remaining environment variables for the project.

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.zeit.co/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.zeit.co/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.zeit.co/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.zeit.co/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.zeit.co/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 ZEIT 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://zeit.co/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://zeit.co/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.zeit.co/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.zeit.co/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"
}

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.

Webhooks

Webhooks allow you to subscribe to certain events on ZEIT. For this, you can setup a URL using your OAuth2 app credentials so that it is associated with your app.

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

Each OAuth2 app 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 comma separated 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.zeit.co/v1/integrations/webhooks" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "My first webhook",
  "url": "https://my-webhook-handler.com/zeit"
}'
Example Response
{
  "id": "hook_XCG7t7AIHuO2SBA8667zNUiM",
  "url": "https://my-webhook-handler.com/zeit",
  "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

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. (unlimited, free)
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 ZEIT or not.

The recommended method to check is to use the x-zeit-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-zeit-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-zeit-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: `zeit.co`"
  }
}

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 zeit.chat or via support@zeit.com.

{
  "error": {
    "code": "failed_to_add_domain",
    "message": "The domain was bought but couldn't be added. Please contact us on https://zeit.chat"
  }
}

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