REST API

Introduction

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

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


API Basics

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

Server Specs

HTTP and TLS

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

TLS versions 1.2 and 1.3 are supported, with resumption.

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

Content Type

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

Authentication

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

Authorization: Bearer <TOKEN>

The Authorization header with a token.

Note: Learn how to get this token for your Integration here.

Accessing Resources Owned by a Team

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

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

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

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

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

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

Failed Authentication

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

Errors

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

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

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

An example of an unauthorized request error.

Rate Limits

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

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

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

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

An example of a rate limit exceeded error.

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

Versioning

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

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

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

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

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

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

Using version 6 of the deployments endpoint.

Types

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

Name
Definition
Example
ID
A unique value used to identify resources.
"V0fra8eEgQwEpFhYG2vTzC3K"
String
A string is a sequence of characters used to represent text.
"value"
Integer
An integer is a number without decimals.
1234
Float
A float is a number with decimals.
12.34
Map
A data structure with a list of values assigned to a unique key.
{ "key": "value" }
List
A data structure with only a list of values separated by a comma.
["value", 1234, 12.34]
Enum
An Enum is a String with only a few possible valid values.
A | 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

Aliases

List aliases

get /v3/aliases

Retrieves a list of aliases for the authenticated User or Team. When domain is provided, only aliases for that domain will be returned. When projectId is provided, it will only return the given project aliases.

Get an Alias

get /v3/aliases/{idOrAlias}

Retrieves an Alias for the given host name or alias ID.

Delete an Alias

delete /v2/aliases/{aliasId}

Delete an Alias with the specified ID.

List Deployment Aliases

get /v2/deployments/{id}/aliases

Retrieves all Aliases for the Deployment with the given ID. The authenticated User must own the deployment.

Assign an Alias

post /v2/deployments/{id}/aliases

Creates a new alias for the deployment with the given deployment ID. The authenticated user must own this deployment. If the desired alias is already assigned to another deployment, then it will be removed from the old deployment and assigned to the new one.

Authentication

List Auth Tokens

get /v5/user/tokens

Retrieve a list of the current User's authentication tokens.

Create an Auth Token

post /v3/user/tokens

Creates and returns a new authentication token for the currently authenticated User. The bearerToken property is only provided once, in the response body, so be sure to save it on the client for use with API requests.

Get Auth Token Metadata

get /v5/user/tokens/{tokenId}

Retrieve metadata about an authentication token belonging to the currently authenticated User.

Delete an authentication token

delete /v3/user/tokens/{tokenId}

Invalidate an authentication token, such that it will no longer be valid for future HTTP requests.

Verify a login request to get an authentication token

get /registration/verify

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.

Login with email

post /registration

Request a new login for a user to get a token. This will respond with a verification token and send an email to confirm the request. Once confirmed you can use the verification token to get an authentication token.

Checks

Checks (Beta) are tests and assertions that run after each deployment has been built. They are powered by Integrations, which allow you to connect any third-party service of your choice with Vercel. Learn more about Checks for deployments.

Status and conclusion

Please update the Check status to running once you have begun performing the respective action within your service. Updating the Check with a conclusion will automatically set the Check status to completed.

Based on the conclusion, a deployment may fail:

Conclusion
blocking equals to true
 cancelled
Yes
 failed
Yes
 neutral
No
 succeeded
No
 skipped
No

Output

The output of a check can contain arbitrary data, or can contain Web Vitals and a Virtual Experience Score.

To include Web Vitals and a Virtual Experience Score, the following can be passed to output under a metrics field:

Key
Description
TBT
The Total Blocking Time, as measured by the Check
LCP
The Largest Contentful Paint, as measured by the Check
FCP
The First Contentful Paint, as measured by the Check
CLS
The Cumulative Layout Shift, as measured by the Check
virtualExperienceScore
The overall Virtual Experience Score measured by the Check

Each of these has the following properties:

Key
Description
value
The value measured for the particular metric, in milliseconds. For virtualExperienceScore this value is the percentage between 0 and 1
previousValue
A previous value for comparison purposes.
source
web-vitals

Creates a new Check

post /v1/deployments/{deploymentId}/checks

Creates a new check. This endpoint must be called with an OAuth2 or it will produce a 400 error.

Retrieve a list of all checks

get /v1/deployments/{deploymentId}/checks

List all of the checks created for a deployment.

Get a single check

get /v1/deployments/{deploymentId}/checks/{checkId}

Return a detailed response for a single check.

Update a check

patch /v1/deployments/{deploymentId}/checks/{checkId}

Update an existing check. This endpoint must be called with an OAuth2 or it will produce a 400 error.

Deployments

Get a deployment by id or url

get /v13/deployments/{id}

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. It will include details in case the authenticated user is the owner of the deployment.

Delete a Deployment

delete /v13/deployments/{id}

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.

Get deployment events

get /v2/deployments/{idOrUrl}/events

Get the build logs of a deployment by deployment ID and build ID. It can work as an infinite stream of logs or as a JSON endpoint depending on the input parameters.

Cancel a deployment

patch /v12/deployments/{id}/cancel

This endpoint allows you to cancel a deployment which is currently building, by supplying its id in the URL.

Create a new deployment

post /v13/deployments

Create a new deployment with all the required and intended data. If the deployment is not a git deployment, all files must be provided with the request, either referenced or inlined.

Upload Deployment Files

post /v2/files

Before you create a deployment you need to upload the required files for that deployment. To do it, you need to first upload each file to this endpoint. Once that's completed, you can create a new deployment with the uploaded files. 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.

List deployments

get /v6/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.

List Deployment Files

get /v6/deployments/{id}/files

Allows to retrieve the file structure of a deployment by supplying the deployment unique identifier.

Get Deployment File Contents

get /v6/deployments/{id}/files/{fileId}

Allows to retrieve the content of a file by supplying the file identifier and the deployment unique identifier. The response body will contain the raw content of the file.

List Deployment Builds

get /v11/deployments/{deploymentId}/builds

Retrieves the list of builds given their deployment's unique identifier.

DNS

List existing DNS records

get /v4/domains/{domain}/records

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

Create a DNS record

post /v2/domains/{domain}/records

Creates a DNS record for a domain.

Delete a DNS record

delete /v2/domains/{domain}/records/{recordId}

Removes an existing DNS record from a domain name.

Domains

Check a Domain Availability

get /v4/domains/status

Check if a domain name is available for purchase.

Check the price for a domain

get /v4/domains/price

Check the price to purchase a domain and how long a single purchase period is.

Get Information for a Single Domain

get /v5/domains/{domain}

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

List all the domains

get /v5/domains

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

Purchase a domain

post /v4/domains/buy

Allows to purchase the specified domain.

Remove a domain by name

delete /v6/domains/{domain}

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

Register or transfer-in a new Domain

post /v4/domains

This endpoint is used for registering a new domain name with Vercel for the authenticating user, and also for initiating a domain transfer request from an external Registrar to Vercel.

Integrations

Gets integrations

get /integrations/integrations

Returns a list of integrations. Either all integrations or only public ones.

Gets a single integration

get /integrations/integration/{slugOrId}

Returns an integration by passing the integration id or slug in the URL. Either the full dataset or only publicly available fields only.

Updates an integration

patch /integrations/integration/{slugOrId}

Updates an integration based on provided fields by passing the integration id or slug in the URL.

Deletes an integration

delete /integrations/integration/{slugOrId}

Deletes an integration with all dependencies by passing the integration id or slug in the URL. This also includes deleting all provided env's from projects.

Creates an integration

post /integrations/integration

Creates an integration which is treated as an oauth2 client for 3rd parties

Get user and teams integration configurations

get /v1/integrations/integration/{slugOrId}/installed

Get all integration configurations for the authenticated user. This includes the most recent configuration for each of the teams the user is part of and the user configuration if it exists.

Get configurations for the authenticated user or team

get /v1/integrations/configurations

Allows to retrieve all configurations for an authenticated client. When the project view is used, configurations generated for the authorization flow will be filtered out of the results.

Retrieve an integration configuration

get /v1/integrations/configuration/{id}

Allows to retrieve a the configuration with the provided id in case it exists. The authenticated user or team must be the owner of the config in order to access it.

Delete an integration configuration

delete /v1/integrations/configuration/{id}

Allows to remove the configuration with the id provided in the parameters. The configuration and all of its resources will be removed. This includes Webhooks, LogDrains and Project Env variables.

Log Drains

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

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

Format and Transport

We support 3 types of Log Drains:

  • JSON
  • NDJSON
  • Syslog

JSON drains

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

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

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

NDJSON Drains

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

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

The following are two example POST bodies:

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

Syslog Drain

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

Syslog messages resemble the following:

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

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

Securing your Log Drains

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

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

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

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

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

Retrieves a list of log drains

get /v1/integrations/log-drains

Retrieves a list of all log drains that are defined for the authorized account. When using an OAuth2 token, the list is limited to log drains created by the authenticated client.

Creates a new log drain

post /v1/integrations/log-drains

Creates a log drain. This endpoint must be called with an OAuth2 client since log drains are tight to clients. If it is called with a different token it will produce a 400 error.

Deletes the log drain with the provided `id`

delete /v1/integrations/log-drains/{id}

Deletes the log drain with the provided id. When using an OAuth2 Token, the log drain can be deleted only if the client owns it.

Projects

Retrieve a list of projects

get /v8/projects

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

Create a new project

post /v8/projects

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

Find a project by id or name

get /v8/projects/{idOrName}

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

Update an existing project

patch /v8/projects/{idOrName}

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

Delete a Project

delete /v8/projects/{idOrName}

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

Retrieve project domains by project by id or name

get /v8/projects/{idOrName}/domains

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

Add a domain to a project

post /v8/projects/{idOrName}/domains

Add a domain to the project by passing its domain name and by specifying the project by either passing the project id or name in the URL. If the domain already exists on the project, the request will fail with a 400 status code.

Get a project domain

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

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

Update a project domain

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

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

Remove a domain from a project

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

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

Retrieve the environment variables of a project by id or name

get /v8/projects/{idOrName}/env

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

Create one or more environment variables

post /v8/projects/{idOrName}/env

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

Remove an environment variable

delete /v8/projects/{idOrName}/env/{keyOrId}

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

Edit an environment variable

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

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

Secrets

List secrets

get /v3/secrets

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

Create a new secret

post /v2/secrets/{name}

Allows to create a new secret.

Change secret name

patch /v2/secrets/{name}

Enables to edit the name of a user's secret. The name has to be unique to that user's secrets.

Get a single secret

get /v3/secrets/{idOrName}

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

Delete a secret

delete /v2/secrets/{idOrName}

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

Teams

Get a Team

get /v2/teams/{teamId}

Get information for the Team specified by the teamId parameter.

Update a Team

patch /v2/teams/{teamId}

Update the information of a Team specified by the teamId parameter. The request body should contain the information that will be updated on the Team.

List all teams

get /v2/teams

Get a paginated list of all the Teams the authenticated User is a member of.

Create a Team

post /v1/teams

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

Delete a Team

delete /v1/teams/{teamId}

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

Delete a Team invite code

delete /v1/teams/{teamId}/invites/{inviteId}

Delete an active Team invite code.

List team members

get /v2/teams/{teamId}/members

Get a paginated list of team members for the provided team.

Invite a user

post /v1/teams/{teamId}/members

Invite a user to join the team specified in the URL. The authenticated user needs to be an OWNER in order to successfully invoke this endpoint. The user can be specified with an email or an ID. If both email and ID are provided, ID will take priority.

Request access to a team

post /v1/teams/{teamId}/request

Request access to a team as a member. An owner has to approve the request. Only 10 users can request access to a team at the same time.

Get access request status

get /v1/teams/{teamId}/request/{userId}

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

Join a team

post /v1/teams/{teamId}/members/teams/join

Join a team with a provided invite code or team ID.

Update a Team Member

patch /v1/teams/{teamId}/members/{uid}

Update the membership of a Team Member on the Team specified by teamId, such as changing the role of the member, or confirming a request to join the Team for an unconfirmed member. The authenticated user must be an OWNER of the Team.

Remove a Team Member

delete /v1/teams/{teamId}/members/{uid}

Remove a Team Member from the Team, or dismiss a user that requested access, or leave a team.

User

List User Events

get /v3/events

Retrieves a list of "events" generated by the User on Vercel. Events are generated when the User performs a particular action, such as logging in, creating a deployment, and joining a Team (just to name a few). When the teamId parameter is supplied, then the events that are returned will be in relation to the Team that was specified.

Get the User

get /v2/user

Retrieves information related to the currently authenticated User.

Delete User Account

delete /v1/user

Initiates the deletion process for the currently authenticated User, by sending a deletion confirmation email. The email contains a link that the user needs to visit in order to proceed with the deletion process.

Interfaces

Shared interfaces referenced across multiple endpoints.

Pagination

/** This object contains information related to the pagination of the current request, including the necessary parameters to get the next or previous page of data. */
interface Pagination {
/** Amount of items in the current page. */
count: number
/** Timestamp that must be used to request the next page. */
next: number | null
/** Timestamp that must be used to request the previous page. */
prev: number | null
}

UserEvent

/** Array of events generated by the User. */
interface UserEvent {
/** The unique identifier of the Event. */
id: string
/** The human-readable text of the Event. */
text: string
/** A list of "entities" within the event `text`. Useful for enhancing the displayed text with additional styling and links. */
entities: {
/** The type of entity. */
type:
| "author"
| "bitbucket_login"
| "bold"
| "deployment_host"
| "dns_record"
| "git_link"
| "github_login"
| "gitlab_login"
| "hook_name"
| "link"
| "project_name"
| "scaling_rules"
| "env_var_name"
| "target"
| "system"
/** The index of where the entity begins within the `text` (inclusive). */
start: number
/** The index of where the entity ends within the `text` (non-inclusive). */
end: number
}[]
/** Timestamp (in milliseconds) of when the event was generated. */
createdAt: number
/** Metadata for the User who generated the event. */
user?: {
avatar: string
email: string
slug?: string
uid: string
username: string
}
/** The unique identifier of the User who generated the event. */
userId: string
}

AuthUser

/** Data for the currently authenticated User. */
interface AuthUser {
/** UNIX timestamp (in milliseconds) when the User account was created. */
createdAt: number
/** When the User account has been "soft blocked", this property will contain the date when the restriction was enacted, and the identifier for why. */
softBlock: {
blockedAt: number
reason: "FAIR_USE_LIMITS_EXCEEDED" | "ENTERPRISE_TRIAL_ENDED"
} | null
/** An object containing billing infomation associated with the User account. */
billing: {
currency?: "usd" | "eur"
addons?: ("custom-deployment-suffix" | "live-support")[] | null
cancelation?: number | null
period: {
start: number
end: number
} | null
contract?: {
start: number
end: number
} | null
plan:
| "free"
| "hobby"
| "premium"
| "legacy_pro"
| "on-demand"
| "unlimited"
| "old-pro"
| "business"
| "enterprise"
| "pro"
platform?: "stripe"
trial?: {
start: number
end: number
} | null
email?: string | null
tax?: {
type: string
id: string
} | null
language?: string | null
address?: {
line1: string
line2?: string
postalCode?: string
city?: string
country?: string
state?: string
} | null
name?: string | null
overdue?: boolean | null
invoiceItems?: {
/** Will be used to create an invoice item. The price must be in cents: 2000 for $20. */
pro?: {
price: number
quantity: number
name?: string
hidden: boolean
createdAt?: number
frequency?: {
interval: "month"
intervalCount: 1 | 3 | 2 | 6 | 12
}
}
/** Will be used to create an invoice item. The price must be in cents: 2000 for $20. */
enterprise?: {
price: number
quantity: number
name?: string
hidden: boolean
createdAt?: number
frequency?: {
interval: "month"
intervalCount: 1 | 3 | 2 | 6 | 12
}
}
/** Will be used to create an invoice item. The price must be in cents: 2000 for $20. */
concurrentBuilds?: {
price: number
quantity: number
name?: string
hidden: boolean
createdAt?: number
frequency?: {
interval: "month"
intervalCount: 1 | 3 | 2 | 6 | 12
}
}
/** Will be used to create an invoice item. The price must be in cents: 2000 for $20. */
saml?: {
price: number
quantity: number
name?: string
hidden: boolean
createdAt?: number
frequency?: {
interval: "month"
intervalCount: 1 | 3 | 2 | 6 | 12
}
}
/** Will be used to create an invoice item. The price must be in cents: 2000 for $20. */
teamSeats?: {
price: number
quantity: number
name?: string
hidden: boolean
createdAt?: number
frequency?: {
interval: "month"
intervalCount: 1 | 3 | 2 | 6 | 12
}
}
/** Will be used to create an invoice item. The price must be in cents: 2000 for $20. */
customCerts?: {
price: number
quantity: number
name?: string
hidden: boolean
createdAt?: number
frequency?: {
interval: "month"
intervalCount: 1 | 3 | 2 | 6 | 12
}
}
/** Will be used to create an invoice item. The price must be in cents: 2000 for $20. */
previewDeploymentSuffix?: {
price: number
quantity: number
name?: string
hidden: boolean
createdAt?: number
frequency?: {
interval: "month"
intervalCount: 1 | 3 | 2 | 6 | 12
}
}
/** Will be used to create an invoice item. The price must be in cents: 2000 for $20. */
passwordProtection?: {
price: number
quantity: number
name?: string
hidden: boolean
createdAt?: number
frequency?: {
interval: "month"
intervalCount: 1 | 3 | 2 | 6 | 12
}
}
/** Will be used to create an invoice item. The price must be in cents: 2000 for $20. */
ssoProtection?: {
price: number
quantity: number
name?: string
hidden: boolean
createdAt?: number
frequency?: {
interval: "month"
intervalCount: 1 | 3 | 2 | 6 | 12
}
}
/** Will be used to create an invoice item. The price must be in cents: 2000 for $20. */
analytics?: {
price: number
quantity: number
name?: string
hidden: boolean
createdAt?: number
frequency?: {
interval: "month"
intervalCount: 1 | 3 | 2 | 6 | 12
}
}
analyticsUsage?: {
price: number
batch: number
threshold: number
name?: string
hidden: boolean
}
bandwidth?: {
price: number
batch: number
threshold: number
name?: string
hidden: boolean
}
builds?: {
price: number
batch: number
threshold: number
name?: string
hidden: boolean
}
serverlessFunctionExecution?: {
price: number
batch: number
threshold: number
name?: string
hidden: boolean
}
sourceImages?: {
price: number
batch: number
threshold: number
name?: string
hidden: boolean
}
} | null
invoiceSettings?: {
footer?: string
}
subscriptions?:
| {
id: string
trial: {
start: number
end: number
} | null
period: {
start: number
end: number
}
frequency: {
interval: "month" | "day" | "week" | "year"
intervalCount: number
}
discount: {
id: string
coupon: {
id: string
name: string | null
amountOff: number | null
percentageOff: number | null
durationInMonths: number | null
duration: "forever" | "repeating" | "once"
}
} | null
items: {
id: string
priceId: string
productId: string
amount: number
quantity: number
}[]
}[]
| null
controls?: {
analyticsSampleRateInPercent?: number | null
analyticsSpendLimitInDollars?: number | null
} | null
purchaseOrder?: string | null
} | null
/** An object containing infomation related to the amount of platform resources may be allocated to the User account. */
resourceConfig: {
nodeType?: string
concurrentBuilds?: number
awsAccountType?: string
awsAccountIds?: string[]
cfZoneName?: string
}
/** Prefix that will be used in the URL of "Preview" deployments created by the User account. */
stagingPrefix: string
importFlowGitNamespace?: (string | number) | null
importFlowGitNamespaceId?: (string | number) | null
importFlowGitProvider?: "github" | "gitlab" | "bitbucket"
preferredScopesAndGitNamespaces?: {
scopeId: string
gitNamespaceId: (string | number) | null
}[]
/** The User's unique identifier. */
id: string
/** Email address associated with the User account. */
email: string
/** Name associated with the User account, or `null` if none has been provided. */
name: string | null
/** Unique username associated with the User account. */
username: string
/** SHA1 hash of the avatar for the User account. Can be used in conjuction with the ... endpoint to retrieve the avatar image. */
avatar: string | null
}

AuthUserLimited

/** A limited form of data for the currently authenticated User, due to the authentication token missing privileges to read the full User data. */
interface AuthUserLimited {
/** Property indicating that this User data contains only limited information, due to the authentication token missing privileges to read the full User data. Re-login with email, GitHub, GitLab or Bitbucket in order to upgrade the authentication token with the necessary privileges. */
limited: boolean
/** The User's unique identifier. */
id: string
/** Email address associated with the User account. */
email: string
/** Name associated with the User account, or `null` if none has been provided. */
name: string | null
/** Unique username associated with the User account. */
username: string
/** SHA1 hash of the avatar for the User account. Can be used in conjuction with the ... endpoint to retrieve the avatar image. */
avatar: string | null
}

AuthToken

/** Authentication token metadata. */
interface AuthToken {
/** The unique identifier of the token. */
id: string
/** The human-readable name of the token. */
name: string
/** The type of the token. */
type: string
/** The origin of how the token was created. */
origin?: string
/** The access scopes granted to the token. */
scopes?: (
| {
type: "user"
origin: "saml" | "github" | "gitlab" | "bitbucket" | "email" | "manual"
createdAt: number
expiresAt?: number
}
| {
type: "team"
teamId: string
origin: "saml" | "github" | "gitlab" | "bitbucket" | "email" | "manual"
createdAt: number
expiresAt?: number
}
)[]
/** Timestamp (in milliseconds) of when the token expires. */
expiresAt?: number
/** Timestamp (in milliseconds) of when the token was most recently used. */
activeAt: number
/** Timestamp (in milliseconds) of when the token was created. */
createdAt: number
}

Team

/** Data representing a Team. */
interface Team {
[key: string]: unknown
}

TeamLimited

/** A limited form of data representing a Team, due to the authentication token missing privileges to read the full Team data. */
interface TeamLimited {
/** Property indicating that this Team data contains only limited information, due to the authentication token missing privileges to read the full Team data. Re-login with the Team's configured SAML Single Sign-On provider in order to upgrade the authentication token with the necessary privileges. */
limited: boolean
/** When "Single Sign-On (SAML)" is configured, this object contains information that allows the client-side to identify whether or not this Team has SAML enforced. */
saml?: {
/** Information for the SAML Single Sign-On configuration. */
connection?: {
/** The Identity Provider "type", for example Okta. */
type: string
/** Current status of the connection. */
status: string
/** Current state of the connection. */
state: string
/** Timestamp (in milliseconds) of when the configuration was connected. */
connectedAt: number
}
/** When `true`, interactions with the Team **must** be done with an authentication token that has been authenticated with the Team's SAML Single Sign-On provider. */
enforced: boolean
}
/** The Team's unique identifier. */
id: string
/** The Team's slug, which is unique across the Vercel platform. */
slug: string
/** Name associated with the Team account, or `null` if none has been provided. */
name: string | null
/** The ID of the file used as avatar for this Team. */
avatar: string | null
membership:
| {
confirmed: boolean
accessRequestedAt?: number
role: "OWNER" | "MEMBER"
teamId?: string
uid: string
createdAt: number
created: number
joinedFrom?: {
origin:
| "mail"
| "link"
| "import"
| "teams"
| "github"
| "gitlab"
| "bitbucket"
| "saml"
| "dsync"
commitId?: string
repoId?: string
repoPath?: string
gitUserId?: string | number
gitUserLogin?: string
ssoUserId?: string
ssoConnectedAt?: number
idpUserId?: string
dsyncUserId?: string
dsyncConnectedAt?: number
}
}
| {
confirmed: boolean
accessRequestedAt: number
role: "OWNER" | "MEMBER"
teamId?: string
uid: string
createdAt: number
created: number
joinedFrom?: {
origin:
| "mail"
| "link"
| "import"
| "teams"
| "github"
| "gitlab"
| "bitbucket"
| "saml"
| "dsync"
commitId?: string
repoId?: string
repoPath?: string
gitUserId?: string | number
gitUserLogin?: string
ssoUserId?: string
ssoConnectedAt?: number
idpUserId?: string
dsyncUserId?: string
dsyncConnectedAt?: number
}
}
/** Will remain undocumented. Remove in v3 API. */
created: string
/** UNIX timestamp (in milliseconds) when the Team was created. */
createdAt: number
}

FileTree

/** A deployment file tree entry */
interface FileTree {
/** The name of the file tree entry */
name: string
/** String indicating the type of file tree entry. */
type: "directory" | "file" | "symlink" | "lambda" | "invalid"
/** The unique identifier of the file (only valid for the `file` type) */
uid?: string
/** The list of children files of the directory (only valid for the `directory` type) */
children?: FileTree[]
/** The content-type of the file (only valid for the `file` type) */
contentType?: string
/** The file "mode" indicating file type and permissions. */
mode: number
/** Not currently used. See `file-list-to-tree.ts`. */
symlink?: string
}

DeploymentCreatedEvent

interface DeploymentCreatedEvent {
type: "deployment"
payload: {
alias?: string[]
deployment: {
id: string
meta?: { [key: string]: string }
name: string
url: string
inspectorUrl: string
}
deploymentId: string
name: string
plan: string
project: string
target?: ("staging" | "production") | null
projectId: string
regions: string[]
type: "LAMBDAS"
url: string
}
clientId: string
createdAt: number
id: string
ownerId: string
region?: string | null
teamId?: string | null
userId: string
webhookId: string
}

DeploymentErrorEvent

interface DeploymentErrorEvent {
type: "deployment-error"
payload: {
deployment: {
id: string
meta?: { [key: string]: string }
name: string
url: string
inspectorUrl: string
}
deploymentId: string
name: string
plan: string
project: string
projectId: string
regions: string[]
target?: ("staging" | "production") | null
type: "LAMBDAS"
url: string
}
clientId: string
createdAt: number
id: string
ownerId: string
region?: string | null
teamId?: string | null
userId: string
webhookId: string
}

DeploymentPreparedEvent

interface DeploymentPreparedEvent {
type: "deployment-prepared"
payload: {
deployment: {
id: string
meta?: { [key: string]: string }
name: string
url: string
inspectorUrl: string
}
deploymentId: string
name: string
plan: string
project: string
projectId: string
regions: string[]
target?: ("staging" | "production") | null
type: "LAMBDAS"
url: string
}
clientId: string
createdAt: number
id: string
ownerId: string
region?: string | null
teamId?: string | null
userId: string
webhookId: string
}

DeploymentReadyEvent

interface DeploymentReadyEvent {
type: "deployment-ready"
payload: {
deployment: {
id: string
meta?: { [key: string]: string }
name: string
url: string
inspectorUrl: string
}
deploymentId: string
name: string
plan: string
project: string
projectId: string
regions: string[]
target?: ("staging" | "production") | null
type: "LAMBDAS"
url: string
}
clientId: string
createdAt: number
id: string
ownerId: string
region?: string | null
teamId?: string | null
userId: string
webhookId: string
}

DomainCreatedEvent

interface DomainCreatedEvent {
type: "domain-created"
payload: {
domain: {
name: string
delegated: boolean
}
}
clientId: string
createdAt: number
id: string
ownerId: string
region?: string | null
teamId?: string | null
userId: string
webhookId: string
}

IntegrationConfigurationCreatedEvent

interface IntegrationConfigurationCreatedEvent {
type: "integration-configuration-created"
payload: {
configuration: {
id: string
projects: string[]
}
authorization: {
code: string
}
}
clientId: string
createdAt: number
id: string
ownerId: string
region?: string | null
teamId?: string | null
userId: string
webhookId: string
}

IntegrationConfigurationRemovedEvent

interface IntegrationConfigurationRemovedEvent {
type: "integration-configuration-removed"
payload: {
configuration: {
id: string
projectSelection: "selected" | "all"
projects: string[]
}
}
clientId: string
createdAt: number
id: string
ownerId: string
region?: string | null
teamId?: string | null
userId: string
webhookId: string
}

IntegrationConfigurationPermissionUpdatedEvent

interface IntegrationConfigurationPermissionUpdatedEvent {
type: "integration-configuration-permission-updated"
payload: {
configuration: {
id: string
projectSelection: "selected" | "all"
projects: string[]
}
projects: {
added: string[]
removed: string[]
}
}
clientId: string
createdAt: number
id: string
ownerId: string
region?: string | null
teamId?: string | null
userId: string
webhookId: string
}