The Now API gives you full control over our entire platform by providing you with all the resources available to our official clients, exposed as simple HTTP endpoints.
curl -X POST https://api.zeit.co/v3/now/deployments \
-H 'Authorization: Bearer $TOKEN' \
-d '{
  "name": "my-instant-deployment",
  "deploymentType": "NPM",
  "public": true,
  "files": [
    {
      "file": "index.js",
      "data": "const { Server } = require(\"http\")\nconst bunny = require(\"sign-bunny\")\n\nconst server = Server((req, res) => {\n  res.setHeader(\"Content-Type\", \"text/plain; charset=utf-8\")\n  res.end(bunny(\"Hi there!\"))\n})\n\nserver.listen()"
    },
    {
      "file": "package.json",
      "data": "{\n  \"name\": \"my-instant-deployment\",\n  \"dependencies\": {\n    \"sign-bunny\": \"1.0.0\"\n  },\n  \"scripts\": {\n    \"start\": \"node index\"\n  }\n}"
    }
  ]
}'

You can curl the URL or click on DEPLOY NOW to see it live

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.

Content Type

All requests must be encoded as JSON with the Content-Type: application/json header. Most responses, including errors, are encoded exclusively as JSON as well.
Provide your API token as part of the Authorization header.
To act on resources owned by a team add teamId query string at the end of an API URL and use the teamId as the value.
If the authentication is unsuccessful, the status code 403 is returned.
Authorization: Bearer $TOKEN
https://api.zeit.co/example?teamId=team_123
NOTE: When logged in, the examples in the API will contain your secret token. Don't share them! For example, to get a list of deployments try the following:
curl -H "Authorization: Bearer $TOKEN" https://api.zeit.co/v2/now/deployments
The possible error_code values are documented on a per-endpoint basis in the Errors section.
Since the message is bound to change over time, we recommend you do not pass it along directly to end-users of your application.
All errors have the following format:
{
  "error": {
    "code": "error_code",
    "message": "An english description of the error that just occurred"
   }
}
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:
HeaderDescription
X-Rate-Limit-LimitThe maximum number of requests that the consumer is permitted to make per minute.
X-Rate-Limit-RemainingThe number of requests remaining in the current rate limit window.
X-Rate-Limit-ResetThe 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": "rate_limited",
    "message": "Rate limit exceeded",
  }
}
We try to avoid breaking backwards-compatibility as much as possible.
In the rare event that we would need to change an endpoint in a very substantial way, we simply will introduce an alternative way of accessing the resource, under a different path.
Some API endpoints, however, are flagged as EXPERIMENTAL. If this is the case, we might deprecate or change the shape of the response over time by appending a version prefix. For example, /create might evolve into /v2/create. When the experimental status is removed, so is the prefix.
Along the documentation we're going to use many different types of data. Here you can find a list of them and what they mean.
Name
Definition
Example
IDA unique value used to identify resources."V0fra8eEgQwEpFhYG2vTzC3K"
StringA string is a sequence of characters used to represent text."ZEIT"
IntegerAn integer is a number without decimals.1234
FloatA float is a number with decimals.12.34
MapA data structure with a list of values assigned to a unique key.{ "service": "ZEIT" }
ListA data structure with only a list of values separated by a comma.["ZEIT", 1234, 12.34]
EnumA enum is a String with only a few possible valid values."NPM" | "DOCKER"
DateA String representing a date with the ISO 8601 format."2018-09-03T19:48:46.555Z"
Endpoint
POST /v3/now/deployments
Create a new deployment on the fly by supplying all the required data.
Before you create the deployment, you need to upload any required files when they cannot be posted at once.
NOTE: The code and logs under the OSS plan will be public.

Input

KeyType?Required
Description
envMapNoAn object containing all the environment variables and his values. It could includes secret keys as values.
publicBooleanYesA boolean indicating if the deployment is public. For every deployment done under the OSS plan, this needs to be set to true.
forceNewBooleanNoA boolean indicating if a new deployment should be forced (this create a new deployment even if the files are the same as the latest one).
nameStringYesA string with the project name used in the deployment URL.
deploymentTypeEnumYesA string indicating the type of deployment, it could be NPM, DOCKER or STATIC.
registryAuthTokenStringNoA string with the authorization token for private npm modules.
filesListYesA list of maps with the files you want in the deploy.
enginesMapNoA map with the desired Node.js version (only for NPM deployments) defined as the package.json engines key.
sessionAffinityEnumNoA string indicating the session affinity algorithm. It could be ip or random.
configMapNoAn object containing any local configuration property. Not all of these properties lead to changes in behavior on the platform (some are designed to be used only by Now CLI).

File

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: Inline file either as plain or base64 strings is useful when a deployment have only a few small files you can upload in a single request.
KeyType?Required
Description
fileStringYesThe file name including the whole path, eg. folder/file.js
dataStringYesThe file content, it could be either a base64 (useful for images, etc.) of the files or the plain content for source code.
encodingEnumNoThe file encoding, it must be $base64 or $utf-8. Defaults to $utf-8
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: Upload each file and then create the deployment with the SHA1 string is specially useful when you have to either upload many or big files. That allow you to retry file uploads in case of a network error.
KeyType?Required
Description
fileStringYesThe file name including the whole path, eg. folder/file.js
shaStringYesThe file SHA1 used to check integrity
sizeIntegerYesThe file size in bytes
Example request:
curl "https://api.zeit.co/v3/now/deployments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "my-instant-deployment",
  "env": {
    "NODE_ENV": "production"
  },
  "public": false,
  "forceNew": true,
  "files": [
    {
      "file": "package.json",
      "sha": "514b5ffa5ef016df7f5f42370157d49f97526a42",
      "size": 145
    },
    {
      "file": "server/index.js",
      "sha": "9d8b952309b28f468919f4a585e18b63a14457f2",
      "size": 161
    }
  ],
  "deploymentType": "NPM",
  "registryAuthToken": "this-is-my-npm-token",
  "engines": {
    "node": "^8.0.0"
  },
  "sessionAffinity": "ip"
}'
Example successful (200) response:
{
  "totalSize": 0,
  "missing": [],
  "deploymentId": "o0kamOwnoWccUDCJCiC5ryLP",
  "url": "my-instant-deployment-vofohcltlm.now.sh",
  "warnings": [],
  "nodeVersion": "8.4.0"
}
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:
HeaderDescription
Content-TypeWith the value application/octet-stream
Content-LengthThe file size in bytes
x-now-digestThe file SHA1 used to check integrity.
x-now-sizeThe file size in bytes
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 "Content-Type: application/octet-stream" \
  -H "Content-Length: 145" \
  -H "x-now-digest: 514b5ffa5ef016df7f5f42370157d49f97526a42" \
  -H "x-now-size: 145" \
  -d '{
  "name": "my-instant-deployment",
  "dependencies": {
    "sign-bunny": "1.0.0"
  },
  "scripts": {
    "start": "node server/index.js"
  }
}'
curl -X POST "https://api.zeit.co/v2/now/files" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/octet-stream" \
  -H "Content-Length: 161" \
  -H "x-now-digest: 9d8b952309b28f468919f4a585e18b63a14457f2" \
  -H "x-now-size: 161" \
  -d 'require('http').Server((req, res) => {
  res.setHeader('Content-Type', 'text/plain; charset=utf-8');
  res.end(require('sign-bunny')('Hi there!'));
}).listen();''
Endpoint
GET /v2/now/deployments
List all the 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.
Each deployment is an object with the following keys:

Output

KeyType?
Description
uidIDA string with the unique deployment ID you can use to get more information or remove it.
nameStringA string with the deployment under which the deployment was created.
urlStringA string with the unique URL of the deployment. If it hasn't finished uploading (is incomplete), the value will be null.
createdStringA number containing the date when the deployment was created (in timestamp).
creatorMapA map with the ID of the user who created the deployment.
stateEnumA string with the current deployment state, it could be one of the following DEPLOYING, DEPLOYMENT_ERROR, BOOTED, BUILDING, READY, BUILD_ERROR or FROZEN
typeEnumA string defining the deployment type, it could be: NPM, DOCKER or STATIC
scaleMapAn object with the current scale configuration of the deployment.

Scale configuration

The scale configuration object always have the following structure:
KeyType?
Description
currentNumberA number with the current amount of instances.
minNumberA number with the minimum possible amount of instances.
maxNumberA number with the maximum possible amount of instances.
Example request:
curl "https://api.zeit.co/v2/now/deployments" \
  -H "Authorization: Bearer $TOKEN"
Example successful (200) response:
{
  "deployments": [
    {
      "uid": "7Npest0z1zW5QVFfNDBId4BW",
      "name": "project-a",
      "url": "project-bfzfxvjaewj.now.sh",
      "created": "1460801613968",
      "creator": {
        "uid": "2qDDuGFTWXBLDNnqZfWPDp1A"
      },
      "state": "READY",
      "type": "NPM",
      "scale": {
          "current": 1,
          "min": 1,
          "max": 10
      }
    },
    {
      "uid": "dOgCUIoovYiYmXbrLX0h9qDk",
      "name": "project-b",
      "url": "project-b-iipihlfrpa.now.sh",
      "created": "1462738579605",
      "creator": {
        "uid": "2qDDuGFTWXBLDNnqZfWPDp1A"
      },
      "state": "BUILD_ERROR",
      "type": "NPM",
      "scale": {
          "current": 0,
          "min": 0,
          "max": 1
      },
      {
        "uid": "32h0AAaCEFAYVCiCyDBTQ0HU",
        "name": "project-c",
        "url": "project-c-mqqsssshze.now.sh",
        "created": "1505254885404",
        "creator": {
          "uid": "2qDDuGFTWXBLDNnqZfWPDp1A"
        },
        "state": "FROZEN",
        "type": "NPM",
        "scale": {
            "current": 0,
            "min": 0,
            "max": 1
        }
      }
    }
  ]
}
Endpoint
GET /v2/now/deployments/:id
This API allows you to retrieve a deployment by supplying its :id in the URL.
You can obtain this, for example, by listing all deployments.

Output

KeyType?
Description
uidIDA string with the unique deployment ID you can use to get more information or remove it.
hostStringA string with the unique URL of the deployment. If it hasn't finished uploading (is incomplete), the value will be `null`.
stateEnumA string with the current deployment state, it could be one of the following: DEPLOYING, DEPLOYMENT_ERROR, BOOTED, BUILDING, READY, BUILD_ERROR or FROZEN
typeEnumA string defining the deployment type, it could be NPM, DOCKER or STATIC.
stateTsDateThe last time when the deployment state has changed.
scaleMapAn object with the current scale configuration of the deployment.

Scale configuration

The scale configuration object will always be an object with the following structure:
KeyType?
Description
minNumberA number with the minimum possible amount of instances.
maxNumberA number with the maximum possible amount of instances.
autoBooleanA boolean indicating if the deployment has auto-scale active.
Example request:
curl "https://api.zeit.co/v2/now/deployments/ChbZiZe84CKtod6rmCIRRvYR" \
  -H "Authorization: Bearer $TOKEN"
Example successful (200) response:
{
  "uid": "ChbZiZe84CKtod6rmCIRRvYR",
  "host": "my-instant-deployment-rrucptrbft.now.sh",
  "state": "READY",
  "stateTs": "2017-09-22T18:03:44.546Z",
  "scale": {
    "min": 0,
    "max": 1,
    "auto": true
  }
}
Endpoint
DELETE /v2/now/deployments/:id
This API allows you to delete a deployment by supplying its :id in the URL. You can obtain the ID, for example, by listing all deployments.
Example request:
curl -X DELETE "https://api.zeit.co/v2/now/deployments/ChbZiZe84CKtod6rmCIRRvYR" \
  -H "Authorization: Bearer $TOKEN"
Endpoint
GET /v2/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.

Output

KeyType?
Description
nameStringThe name of the file.
typeEnumIf it's a file or a directory.
uidIDThe unique ID of the file (only valid for file type)
childrenListThe children files of the directory (only valid for directory type).
Example request:
curl "https://api.zeit.co/v2/now/deployments/ChbZiZe84CKtod6rmCIRRvYR/files" \
  -H "Authorization: Bearer $TOKEN"
Example successful (200) response:
[
  {
    "name": "server",
    "type": "directory",
    "children": [
      {
        "name": "index.js",
        "type": "file",
        "uid": "2d4aad419917f15b1146e9e03ddc9bb31747e4d0"
      }
    ]
  },
  {
    "name": "package.json",
    "type": "file",
    "uid": "9acbc0dc48cb0e146a97db2ac386569dc4ff031d"
  }
]
Endpoint
GET /v2/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 -X https://api.zeit.co/v2/now/deployments/ChbZiZe84CKtod6rmCIRRvYR/files/2d4aad419917f15b1146e9e03ddc9bb31747e4d0 "undefined" \
  -H "Authorization: Bearer $TOKEN"
Example successful (200) response:
require("http").Server((req, res) => {
  res.setHeader("Content-Type", "text/plain; charset=utf-8");
  res.end(require("sign-bunny")("Hi there!"));
}).listen();
Endpoint
GET /v1/now/deployments/:id/instances
Get the list of instances unique URL of a deployment.

Output

KeyType?
Description
instancesListA list of maps with the instance information

Instance

KeyType?
Description
uidIDThe instance unique identifier.
urlStringThe instance unique url. Is the deployment unique URL with the instance $uid added before $.now.sh.
Example request:
curl "https://api.zeit.co/v1/now/deployments/DguxFCKb5RdNmTw20KGwb42H/instances" \
  -H "Authorization: Bearer $TOKEN"
Example response:
{
  "instances": [
    {
      "uid": "ce78d91573fedfff4e6577a8",
      "url": "my-app-oiqkcxsmuf-ce78d91573fedfff4e6577a8.now.sh"
    }
  ]
}
Endpoint
POST /v1/now/deployments/:id/instances
Configure the minimum and maximum amount of instances desired for the given deployment.
Note: The deployment must be on the READY state to scale it.

Input

KeyType?Required
Description
minIntegerYesThe desired minimum amount of instances.
maxIntegerYesThe desired maximum amount of instances.

Output

KeyType?
Description
minIntegerThe new minimum amount of instances.
maxIntegerThe new maximum amount of instances.
Example request:
curl -X POST "https://api.zeit.co/v1/now/deployments/2sS6QiQppD9moBzhmX34Y21H/instances" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "min": 1,
  "max": 10
}'
Example response:
{
  "min": 1,
  "max": 10
}
Endpoint
GET /v1/now/deployments/:id/logs
Get the logs of a deployment by his ID.

Output

KeyType?
Description
logsListThe list of objects representing each log.

Log

KeyType?
Description
objectMapThe log content as a map.
textStringThe log content as a string.
deploymentIdIDThe unique identified of the deployment
idIDThe unique identifier of the log
contextString
createdDateThe date when the log was created.
serialInt
typeEnumThe type of log, it could be request, response, command or stdout.
pidIDThe process unique identified which created the log.
appNameStringThe deployment application name.
dateDateThe date when the log was created.
regionEnumThe name of the region where the instance was running. It could be now-sfo.

Log object key

This are the usual keys of the key object of the logs.
KeyType?
Description
methodStringA valid HTTP method.
uriStringThe URL which received the request.
statusStringA valid HTTP status code.
protocolStringThe protocol used for the log.
bodyBytesSentStringThe amount of bytes sent in the body of the response.
remoteAddrStringThe IP address which sent the request.
userAgentStringThe user agent of the device which sent the request.

Types

These are the possible types of logs and what they mean.
Type
Description
requestThe log is a HTTP request.
responseThe log is a HTTP response.
commandThe log is a terminal command, e.g. npm start.
stdoutThe log is anything the application wrote to console.
Example request:
curl "https://api.zeit.co/v1/now/deployments/Cm6WigEH9EBI4Uzs2WA6qOGe/logs" \
  -H "Authorization: Bearer $TOKEN"
Example response:
{
  "logs": [
    {
      "id": "log_EEQs4oPeDT3mK6qVDCg53xOA",
      "type": "command",
      "text": "npm install",
      "instanceId": "",
      "date": "2017-09-04T17:42:54.129Z",
      "created": "2017-09-04T17:42:54.207Z",
      "pid": "6268645745692858883",
      "serial": "150454697412962686457456928588830000000000000000000",
      "region": "now-sfo",
      "deploymentId": "Cm6WigEH9EBI4Uzs2WA6qOGe",
      "appName": "now-redirect"
    },
    {
      "id": "log_MABiQaH5ZQtsGldYCm2RnFna",
      "type": "command",
      "text": "npm start",
      "instanceId": "",
      "date": "2017-09-04T17:42:56.169Z",
      "created": "2017-09-04T17:42:56.248Z",
      "pid": "4858500117945524255",
      "serial": "150454697616948585001179455242550000000000000000000",
      "region": "now-sfo",
      "deploymentId": "Cm6WigEH9EBI4Uzs2WA6qOGe",
      "appName": "now-redirect"
    },
    {
      "id": "log_vGDj96qvUoG8fEJCjcFleRfk",
      "type": "stdout",
      "text": "\n> now-redirect@1.0.0 start /home/nowuser/src\n> node server.js\n",
      "instanceId": "996f12b74403b51f62310d82",
      "date": "2017-09-04T17:42:57.209Z",
      "created": "2017-09-04T17:42:57.236Z",
      "pid": "4858500117945524255",
      "serial": "150454697720948585001179455242550000000000000000001",
      "region": "now-sfo",
      "deploymentId": "Cm6WigEH9EBI4Uzs2WA6qOGe",
      "appName": "now-redirect"
    },
    {
      "object": {
        "method": "GET",
        "uri": "/",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36",
        "remoteAddr": "181.67.7.237",
        "protocol": "HTTP/2.0"
      },
      "deploymentId": "Cm6WigEH9EBI4Uzs2WA6qOGe",
      "id": "log_DZlBA1IeSdfezFy962gURCpf",
      "context": "9HrrSAr7bqUz3V7aVcsbyYT3",
      "created": "2017-09-04T17:42:59.212Z",
      "serial": "150454697921258192117963931524070000000000000705393",
      "type": "request",
      "pid": "5819211796393152407",
      "appName": "now-redirect",
      "date": "2017-09-04T17:42:59.212Z"
    },
    {
      "object": {
        "method": "GET",
        "uri": "/",
        "status": "301",
        "protocol": "HTTP/2.0",
        "bodyBytesSent": "79"
      },
      "deploymentId": "Cm6WigEH9EBI4Uzs2WA6qOGe",
      "id": "log_tw8g2Xu2AEVp2H4u7FJc05NB",
      "context": "9HrrSAr7bqUz3V7aVcsbyYT3",
      "created": "2017-09-04T17:42:59.233Z",
      "serial": "150454697923358192117963931524070000000000000705395",
      "type": "response",
      "pid": "5819211796393152407",
      "appName": "now-redirect",
      "date": "2017-09-04T17:42:59.233Z"
    }
  ]
}
Endpoint
GET /v2/domains
Retrieves a list of domains registered for the authenticating user. Each domain entry contains an aliases array listing every alias associated with the domain. The field isExternal is a boolean value telling wheter an external nameserver is used to manage DNS records for the domain.

Output

KeyType?
Description
uidIDThe unique ID of the domain.
nameStringThe domain name
createdAtDateThe date when it was created the registry.
boughtAtDateIf it was purchased through Now the date when it was purchased.
expiresAtDateThe date when the domain is going to expire and need to be renewed.
isExternalBooleanIf it is an externally handled domain
verifiedBooleanIf the domain has the ownership verified.
aliasesListThe list of aliases using the domain.
certsListThe list domains or subdomains with a SSL certificated provisioned.
Example request:
curl "https://api.zeit.co/v2/domains" \
  -H "Authorization: Bearer $TOKEN"
Example successful (200) response:
{
  "domains": [
    {
      "uid": "HVXAOskvQK8ILaF8d8gmwdRx",
      "name": "zeit.rocks",
      "created": "2017-09-03T19:48:50.120Z",
      "boughtAt": "2017-09-03T19:48:46.000Z",
      "expiresAt": "2018-09-03T19:48:46.555Z",
      "isExternal": false,
      "verified": true,
      "aliases": [
          "tyyBofjOQzbTS5Q8Orif6YS1"
      ],
      "certs": [
          "zeit.rocks"
      ]
    }
  ]
}
Endpoint
POST /v2/domains
Register a new domain name with Now for the authenticating user. The field serviceType selects whether the domains is going to use zeit.world DNS or an external nameserver. In the latter case a CNAME/ALIASrecord(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 returnverified: true, if the domain was verified succesfully.

Input

KeyType?Required
Description
nameStringYesThe domain name you want to add.
serviceTypeEnumNoexternal for externally handled domain; zeit.world for managed.

Output

KeyType?
Description
uidIDThe unique identifier of the domain.
verifiedBooleanIf the domain has the ownership verified.
verifyTokenStringThe token required to verify the ownership of an external domain.
createdDateThe date when the new domain was created.
Example request adding a zeit.world domain:
curl -X POST "https://api.zeit.co/v2/domains" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "zeit.rocks",
  "serviceType": "zeit.world"
}'
Successful (200) response:
{
  uid: "V0fra8eEgQwEpFhYG2vTzC3K",
  verified: true,
  created: "2016-09-23T11:53:38.600Z"
}
Example request adding a unverified external domain:
curl -X POST "https://api.zeit.co/v2/domains" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "awesome-now.us",
  "serviceType": "zeit.world"
}'
Successful (200) response:
{
  uid: "V0fra8eEgQwEpFhYG2vTzC3K",
  verified: false,
  verifyToken: "3f786850e387550fdab836ed7e6dc881de23001b",
  created: "2016-09-23T11:53:38.600Z"
}
Endpoint
DELETE /v2/domains/:name
Delete a previously registered domain name from Now. Deleting a domain will automatically remove any associated aliases.

Output

KeyType?
Description
uidIDThe unique ID of the removed domain.
Example request:
curl -X DELETE "https://api.zeit.co/v2/domains/zeit.rocks" \
  -H "Authorization: Bearer $TOKEN"
Example successful (200) response:
{
  uid: "V0fra8eEgQwEpFhYG2vTzC3K"
}
Endpoint
GET /v2/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.

Output

KeyType?
Description
statusBooleanIf the domain is available or not.
Example request:
curl "https://api.zeit.co/v2/domains/status?name=zeit.rocks" \
  -H "Authorization: Bearer $TOKEN"
Example successful (200) response:
{
  "status": false
}
Endpoint
GET /v2/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 amount of years the domains could be hold before paying again.

Output

KeyType?
Description
priceIntegerThe domain price.
periodIntegerThe time period by which the domain is purchased.
Example request:
curl "https://api.zeit.co/v2/domains/price?name=zeit.rocks" \
  -H "Authorization: Bearer $TOKEN"
Example successful (200) response:
{
  "price": 17,
  "period": 1
}
Endpoint
POST /v2/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.

Input

KeyType?Required
Description
nameStringYesThe domain name you want to purchase.
expectedPriceNumberNoThe price you expect to be charged for the purchase.
Example request:
curl -X POST "https://api.zeit.co/v2/domains/buy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "zeit.rocks"
}'
Example failed 403 response:
{
  "error": {
    "code": "not_available",
    "message": "Domain is not available"
  }
}
Endpoint
GET /v2/domains/:domain/records
Get a list of DNS records created for a domain name specified in the URL.

Output

KeyType?
Description
idIDThe unique ID of the DNS record. Always prepended with rec_.
typeEnumThe type of record, it could be any valid DNS record.
nameStringThe subdomain which we're configuring or @ for the domain itself.
valueStringThe record value.
createdStringA timestamp with the date when the record was created.
updatedStringA 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 successful (200) response:
{
  "records": [
    {
      "id": "rec_38OtX1f51szRA03atCybBuZ3",
      "slug": "zeit.rocks.-address",
      "type": "ALIAS",
      "name": "",
      "value": "alias.zeit.co",
      "created": "1474631621542",
      "updated": null
    },
    {
      "id": "rec_Pxo2HEfutmlIYECtTE4SpDzY",
      "slug": "*.zeit.rocks.-address",
      "type": "CNAME",
      "name": "*",
      "value": "alias.zeit.co",
      "created": "1474631619960",
      "updated": null
    }
  ]
}
Endpoint
POST /v2/domains/:domain/records
Create a DNS record for a domain specified in the URL. mxPriorityfield should be set for MX records and left out otherwise.

Input

KeyType?Required
Description
nameStringYesThe subdomain which we're configuring or @ for the domain itself.
typeEnumYesThe type of record, it could be any valid DNS record.
valueStringYesThe record value.
mxPriorityIntegerNoThe priority for MX records, is only required if the record type is MX.

Output

KeyType?
Description
uidIDThe 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": "mail.zeit.rocks",
  "mxPriority": 10
}'
Example successful (200) response:
{
  uid: "rec_V0fra8eEgQwEpFhYG2vTzC3K"
}
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 succesfully 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"
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.

Output

KeyType?
Description
certsListThe list of issued certificates.

Certificate

This is the format of each item in the certs list.
KeyType?
Description
uidIDThe unique identifier of the certificate.
cnsList<String>The common names for which domain the certificate was issued.
createdDateThe date when the certificate was created.
expirationDateThe date when the certificate is going to expire.
autoRenewBooleanIf the certificate is going to be automatically renewed.
Example request:
curl "https://api.zeit.co/v3/now/certs" \
  -H "Authorization: Bearer $TOKEN"
Example successful (200) 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
    }
  ]
}
Endpoint
GET /v3/now/certs/:id
Retrieves the information about the certificate issued for certificate id specified in the URL.

Output

KeyType?
Description
uidIDThe unique identifier of the certificate.
cnsList<String>The common names for which domain the certificate was issued.
createdDateThe date when the certificate was created.
expirationDateThe date when the certificate is going to expire.
autoRenewBooleanIf the certificate is going to be automatically renewed.
Example request:
curl "https://api.zeit.co/v3/now/certs/oAjf6y9pxZgCJyQfrclN" \
  -H "Authorization: Bearer $TOKEN"
Example successful (200) response:
{
  "cns": ["wow.zeit.co"],
  "uid": "oAjf6y9pxZgCJyQfrclN",
  "created": "2016-08-23T18:13:09.773Z",
  "expiration": "2016-12-16T16:00:00.000Z",
  "autoRenew": true
}
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.

Input

KeyType?Required
Description
domainsList<String>YesA list of Common Names for which the certificate is being provisioned.

Output

KeyType?
Description
uidIDThe unique identifier of the issued certificate.
created_atDateThe 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 successful (200) response:
{
  "uid": "zWsFytQUFlkUWaR7nWdwS7xR"
  "created_at": 2016-06-01T21:03:10.420Z"
}
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.

Input

KeyType?Required
Description
caStringYesPEM formatted CA chain
certStringYesPEM formatted certificate
keyStringYesPEM formatted private key

Output

KeyType?
Description
created_atDateThe 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 successful (200) response:
{
  "created_at": 2016-06-01T21:03:10.420Z"
}
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"
Endpoint
GET /v2/now/aliases
Retrieves all of the active now aliases for the authenticating user. The body will contain an entry for each alias.

Output

KeyType?
Description
uidIDThe unique identifier of the alias.
aliasStringThe alias name, it could be a .now.sh subdomain or a custom domain.
createdDateThe date when the alias was created.
deploymentMapA map with the deployment ID and url.
deploymentIdIDThe deployment ID.
rulesListThe configured rules for path alias

Deployment

This is the format of the deployment above described above.
KeyType?
Description
idIDThe deployment unique identifier.
urlStringThe deployment unique URL.
Example request:
curl "https://api.zeit.co/v2/now/aliases" \
  -H "Authorization: Bearer $TOKEN"
Example successful (200) 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"
          }
      ]
    }
  ]
}
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.

Output

KeyType?
Description
statusStringIf the alias was successfully removed.
Example request:
curl -X DELETE "https://api.zeit.co/v2/now/aliases/2WjyKQmM8ZnGcJsPWMrHRHrE" \
  -H "Authorization: Bearer $TOKEN"
Example successful (200) response:
{
  "status": "SUCCESS"
}
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.

Output

KeyType?
Description
aliasesListA list of the aliases asigned to the deployment.

Alias

This is the format of each item in the aliases list.
KeyType?
Description
uidIDThe unique identifier of the alias.
aliasStringThe alias name, it could be a .now.sh subdomain or a custom domain.
createdDateThe date when the alias was created.
Example request:
curl "https://api.zeit.co/v2/now/deployments/7Npest0z1zW5QVFfNDBId4BW/aliases" \
  -H "Authorization: Bearer $TOKEN"
Example successful (200) response:
{
  "aliases": [
    {
      "uid": "2WjyKQmM8ZnGcJsPWMrHRHrE",
      "alias": "my-alias",
      "created": "2016-06-02T21:01:40.950Z",
    }
  ]
}
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.

Input

KeyType?Required
Description
aliasStringYesThe alias we want to assign to the deployment defined in the URL.

Output

KeyType?
Description
oldIDIDThe unique identifier of the previously aliased deployment, only received when the alias was used before.
uiIDThe unique identifier of the alias.
createdDateThe 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 successful (200) response for new alias:
{
  "uid": "2WjyKQmM8ZnGcJsPWMrHRHrE",
  "created": "2016-06-02T21:01:40.950Z"
}
Example successful (200) response for alias with existing deployment (oldId is the id of the previous deployment):
{
  "oldId": "c9MrOWGzdJSfPxqyTDYhdEGN",
  "uid": "2WjyKQmM8ZnGcJsPWMrHRHrE",
  "created": "2016-06-02T21:01:40.950Z"
}
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.

Output

KeyType?
Description
secretsListThe list of active secrets.

Secret

This is the format of each item in the secrets list.
KeyType?
Description
uidIDThe unique identifier of the secret. Always prepended with sec_
nameStringThe name of the secret. This is what you could use in your environment variables after a @.
createdDateThe date when the secret was created.
Example request:
curl -X https://api.zeit.co/v2/now/secrets "undefined" \
  -H "Authorization: Bearer $TOKEN"
Example successful (200) response:
{
  "secrets": [
    {
      "uid": "sec_T70JHBhR1gqaxXVrLTsHr6B9",
      "name": "guillermo",
      "created": '2016-09-02T01:03:50.000Z'
    }
  ]
}
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.

Input

KeyType?Required
Description
nameStringYesThe name of the secret (max 100 characters).
valueStringYesThe value of the new secret.

Output

KeyType?
Description
uidIDThe unique identifier of the secret. Always prepended with sec_
nameStringThe name of the secret
createdDateThe date when the secret was created.
userIdIDThe unique identifier of the user who created the secret.
valueMapA map with the value of the secret.

Secret value

This is the format of the Map received as value.
KeyType?
Description
typeStringThe type of structure used to save the secret value (always Buffer).
dataListA 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 successful (200) 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
    ]
  }
}
Endpoint
PATCH /v2/now/secrets/:name
This endpoint provides an opportunity to edit the nameof 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.

Input

KeyType?Required
Description
nameStringYesThe new name of the secret.

Output

KeyType?
Description
uidIDThe unique identifier of the secret. Always prepended with sec_
nameStringThe new name of the secret
createdDateThe date when the secret was created.
oldNameStringThe 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 successful (200) 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.
Endpoint
DELETE /v2/now/secrets/:name
:
This deletes the user's secret defined in the URL.

Output

KeyType?
Description
uidIDThe unique identifier of the secret. Always prepended with sec_
nameStringThe name of the secret
createdDateThe 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 successful (200) 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.
Endpoint
POST /teams
Create a new team under your account. You need to send a POST request with the desired team slug.

Input

KeyType?Required
Description
slugStringYesThe desired slug for the team.
Example request:
curl -X POST "https://api.zeit.co/teams" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "slug": "a-random-team"
}'
Example response:
{
  "id": "team_LLHUOMOoDlqOp8wPE4kFo9pE"
}
Endpoint
GET /teams
Get a list of all the team you belong to.

Output

KeyType?
Description
teamsListThe list of each team member as described on Get single team information
Example request:
curl "https://api.zeit.co/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
    }/
  ]
}
Endpoint
GET /teams/:id
GET /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.

Output

KeyType?
Description
idIDThe team unique identifier. Always prepended by $team_.
slugStringThe team slug. A slugified version of the $name
nameStringThe name of the team.
creatorIdIDThe ID of the user who created the team.
avatarString
Example request:
curl "https://api.zeit.co/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
}
Endpoint
PATCH /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.

Input

KeyType?Required
Description
slugStringNoThe new team slug.
nameStringNoThe new team name.
Example request:
curl -X PATCH "https://api.zeit.co/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"
}
Endpoint
GET /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.

Output

KeyType?
Description
uidIDThe team member unique identifier.
roleEnumThe role inside the team, it could be OWNER or MEMBER.
emailStringThe email address of the team member.
usernameStringThe username of the team member
Example request:
curl "https://api.zeit.co/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"
  }
]
Endpoint
POST /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.

Input

KeyType?Required
Description
emailStringYesThe email address of the user to invite.

Output

KeyType?
Description
uidIDThe ID of the invited user.
usernameStringThe username of the invited user.
Example request:
curl -X POST "https://api.zeit.co/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"
}
Endpoint
PATCH /teams/:id/members/:userId
Change the role 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.

Input

KeyType?Required
Description
roleEnumYesThe new role of the team member, it could be OWNER or MEMBER.
Example request:
curl -X PATCH "https://api.zeit.co/teams/team_ofwUZockJlL53hINUGCc1ONW/members/kr1PsOIzqEL5Xg6M4VZcZosf" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "OWNER"
}'
Endpoint
DELETE /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 itself.
Example request:
curl -X DELETE "https://api.zeit.co/teams/team_ofwUZockJlL53hINUGCc1ONW/members/kr1PsOIzqEL5Xg6M4VZcZosf" \
  -H "Authorization: Bearer $TOKEN'"
Endpoint
POST /now/registration
Request a new login for an user to get a token.

Input

KeyType?Required
Description
emailStringYesThe user email.
tokenNameStringYesThe desired name for the token. It will be displayed on the user account details.

Output

KeyType?
Description
tokenStringThe token used to verify the user accepted the login request.
securityCodeStringThe code the user is going to receive on the email. Must be displayed to the user so he 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"
}
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.

Output

KeyType?
Description
tokenStringThe 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 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'll need to register your app before getting started. For registration, please contact us.
You can reference an OAuth2 example application here.
Your app should redirect users to the following URL:
https://zeit.co/oauth/authorize
You will pass the following values as query paremeters.
KeyRequiredDescription
client_idYesID of your application.
redirect_uriNoURL to redirect back.
stateNoRandom string to be passed back upon completion. It is used to protect against CSRF attacks.
If the user grants your request, we redirects back to your site with a code paremeter and with a state parameter if you provided one in previous step.
The process should be aborted if the states don't match.
Example request url:
https://zeit.co/oauth/authorize?client_id=oac_s4cllbR9Ao8307IDSkluOQBS
Example successful redirect url:
https://example.com/oauth/callback?code=jMIukZ1DBCKXHje3X14BCkU0&state=t2eh4KHwNyGbo5g65VNvoFhl
If all goes well, exchange the authorization code for an access token using the following API.
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.
KeyRequiredDescription
client_idYesID of your application.
client_secretYesSecret of your application.
codeYesThe code you received.
You'll receive a JSON response containing an access_token.
Example access token exchange request.
POST https://api.zeit.co/v2/oauth/access_token

client_id=oac_s4cllbR9Ao8307IDSkluOQBS&client_secret=EOBPvZuBYAtb3SbYo8H1iWFP&code=jMIukZ1DBCKXHje3X14BCkU0
Example successful (200) 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.
These error codes are consistent for all endpoints.
You're not authorized to use the endpoint. This usually happends due to missing an user token.
Is similar to the HTTP 403 Forbidden error.
{
  "error": {
    "code": "forbidden",
    "message": "Not authorized"
  }
}
You exceeded the maximum alloted 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": "Rate limit exceeded",
  }
}
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",
   }
}
This errors is similar to the HTTP 500 Internal Server Error error code.
{
  "error": {
    "code": "internal_server_error",
    "message": "An unexpected internal error occurred"
  }
}
The endpoint you're requesting doens't 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"
  }
}
The endpoint you're requesting doens't 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"
  }
}
These error code could happen when using any deployment related endpoint.
Some of the files you defined when creating the deployment are missing.
{
  "error": {
    "code": "missing_files",
    "message": "Missing files",
    "missing": []
  }
}
You tried to create an empty deployment.
{
  "error": {
    "code": "no_files",
    "message": "No files in the deployment"
  }
}
You reached the limit of running instances, you need to remove or scale down another deployment before creating a new one.
{
  "error": {
    "code": "instance_concurrency_exceeded",
    "message": "Too many active deployment instances"
  }
}
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 #)"
  }
}
# is your number of variables.
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
  }
}
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
  }
}
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
  }
}
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"
  }
}
The value of an environment variable is an object with unknow 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"
  }
}
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
  }
}
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
  }
}
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
  }
}
You tried to set session affinity with an invalid value. Only allowed values are ip or random.
{
  "error": {
    "code": "invalid_session_affinity",
    "message": "Session affinity must be ip or random"
  }
}
You tried to create a deployment on the OSS plan with the public property either set to false or not set at all.
On the OSS plan, it is required that you set this property to true in order to explicitly acknowledge that the deployment's code will be publicly accessibly.
{
  "error": {
    "code": "plan_requires_public",
    "message": "Your plan (OSS) requires the deployment to be marked as public."
  }
}
These error code could happen when using any domains related endpoints.
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
  }
}
The domain name could not be found in our system. Try to add it first
{
  "error": {
    "code": "not_found",
    "message": "Domain name not found"
  }
}
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"
  }
}
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
  }
}
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
  }
}
When trying to modify a domain nothing was required to change.
{
  "error": {
    "code": "not_modified",
    "message": "Nothing to do"
  }
}
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`"
  }
}
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
  }
}
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."
  }
}
The domain name you're trying to add already exists.
The domain name and his 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
  }
}
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"
  }
}
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"
  }
}
We're unable to determine the domain price of a domain.
{
  "error": {
    "code": "service_unavailabe",
    "message": "Failed to determine the domain price"
  }
}
The expectedPrice supplied in the request body doesn't match the actual domain price, which is specificed in the actualPrice key.
{
  "error": {
    "code": "price_mismatch",
    "message": "The expected price doesn't match the actual price",
    "price": ACTUAL_PRICE
  }
}
The domain name is not available to be purchased.
{
  "error": {
    "code": "not_available",
    "message": "Domain is not available"
  }
}
The domain name or TLD is invalid or not supported.
{
  "error": {
    "code": "invalid_domain",
    "message": "Invalid domain or TLD"
  }
}
The domain you're trying to get information about could not be found or doesn't exists.
{
  "error": {
    "code": "not_found",
    "message": "The domain was not found"
  }
}
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"
  }
}
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"
  }
}
These error code could happen when using any DNS related endpoint.
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"
  }
}
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"
  }
}
These error code could happen when using any OAuth2 related endpoint.
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"
  }
}
The v2 endpoint has been deprecated. Use the v3 endpoint instead.
Each certificate in the certs list now contains a cns list inside, with Common Names strings as children.
Previously, there was a cn field with a unique common name string inside.
The v2 endpoint has been deprecated. Use the v3 endpoint instead.
Like the certificates list endpoint, it now returns a cns array instead of the cn string.
The v2 endpoint has been deprecated. Use the v3 endpoint instead. It's now labeled Submit a Certificate.
Certificates can no longer be replaced. You can use this PUT endpointto upload your own new certificate.
The domains field is no longer accpeted. The Common Names are extracted from the certificate itself automatically.
The v2 endpoint has been deprecated. Use the v3 endpoint instead.
In order to delete a certificate, the only allowed way is to pass its unique identifier.
Previously, it was possible pass a domain name. This was error-prone and imprecise as a domain name can be present in multiple certificates, as a Common Name (CN).
The v2 endpoint has been deprecated. Use the v3 endpoint instead.
We removed the renew option. Renewals now happen by issuing new certificates, instead of replacing them.
Certificates are now effectively immutable. Our load balancers will pick a non-expired suitable certificate to serve your requests automatically.
The v2 endpoint has been deprecated. Use the v3 endpoint instead.
Starting with this release, the public property in the POST request for creating the deployment needs to be set to true for all deployments made on the OSS plan.
For higher plans, the value can be either:
  • true for making the deployment's code publicly accessible under the /_src path.
  • false for protecting the deployment's code from public access (/_src results in a 403 error).
If the property is not set and the plan is OSS, an error will be thrown. This opportunity can be used for showing a confirmation message to the user (asking them if they really want to deploy):
As an example, Now CLI and Now Desktop firstly send public: false (even on the OSS plan). Then, once the API responds with the error, the confirmation prompt gets shown. If the user agrees to the prompt, another request will be sent with public: true.
Endpoint:
POST /v3/now/deployments
Example request (user is on the OSS plan):
curl -X POST https://api.zeit.co/v3/now/deployments -H 'Authorization: Bearer $TOKEN' -d '{
  "name": "my-instant-deployment",
  "deploymentType": "NPM",
  "public": true,
  "files": [
    {
      "file": "index.js",
      "data": "const { Server } = require("http")\nconst bunny = require("sign-bunny")\n\nconst server = Server((req, res) => {\n  res.setHeader("Content-Type", "text/plain; charset=utf-8")\n  res.end(bunny("Hi there!"))\n})\n\nserver.listen()"
    },
    {
      "file": "package.json",
      "data": "{\n  "name": "my-instant-deployment",\n  "dependencies": {\n    "sign-bunny": "1.0.0"\n  },\n  "scripts": {\n    "start": "node index"\n  }\n}"
    }
  ]
}'
Error response (because public is not set):
{
  "error": {
    "code": "plan_requires_public",
    "message": "Your plan (OSS) requires the deployment to be marked as public."
  }
}
The v1 endpoint has been deprecated. Use the v2 endpoint instead.
Create a new deployment on the fly by supplying an :id in the URL and the necessary file data in the body.
The body contains a special key package that has the package.json JSON structure. Other keys will represent a file path, with their respective values containing the file contents.
NOTE: The code and logs under the OSS plan will be public.