A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Vercel API is how an app or AI agent works with a Vercel account: creating and canceling deployments, reading and updating projects, managing domains and DNS records, and setting environment variables. Access is granted through an access token sent as a Bearer token, scoped at creation to a personal account or one specific team, and a request acts within that scope. Vercel versions each endpoint on its own and can push events to a webhook when a deployment is created, succeeds, fails, or is canceled.
How an app or AI agent connects to Vercel determines what it can reach. There is a route for making calls, an official hosted server that exposes Vercel to agents, and each is governed by the access token behind it and the account or team that token is scoped to.
The REST API answers at https://api.vercel.com and returns JSON. Each endpoint carries its own version number in the path, like /v13/deployments or /v9/projects, and a call authenticates with an access token sent as a Bearer token. The team or account a token is scoped to is selected with the teamId query parameter.
Vercel's official hosted Model Context Protocol server at https://mcp.vercel.com connects a Vercel account to AI clients. It authenticates through an OAuth consent screen on every connection and, at launch, is read-only, with tools for searching docs and managing teams, projects, and deployments. It is in public beta.
Vercel POSTs an event to an HTTPS endpoint registered on an account or team, for events like a deployment being created, succeeding, failing, or being canceled. The receiver verifies the x-vercel-signature header against the webhook's secret to confirm the request came from Vercel.
An access token is created in account settings and sent as a Bearer token. Its scope is chosen at creation, either the full personal account or one specific team, so the token only reaches what that scope covers. Setting an expiration, from one day to one year, is recommended.
Vercel's hosted MCP server uses OAuth, prompting a consent screen on every connection rather than a long-lived token pasted into a client. The resulting access is read-only at launch and scoped to the connected account or team.
The Vercel API is split into areas an agent can act on, such as deployments, projects, domains, DNS records, environment variables, and teams. Each area has its own methods, and writes in some areas ship code to production, change live domains, or delete projects.
List deployments, create a new deployment, read one by ID or hostname, cancel a building deployment, delete a deployment, and read build and runtime events.
List projects, create a project, read one by ID or name, update its settings, and delete a project.
Read a project's environment variables and create one or more on a project.
List domains, read a single domain's details, and remove a domain from an account or team.
List a domain's DNS records, create a record, and delete a record.
List the aliases that map domains to deployments for the account or team.
List the teams the token can see and read a single team's details.
List Edge Configs, create an Edge Config, and update its items in batch.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
DeploymentsList deployments, create a new deployment, read one by ID or hostname, cancel a building deployment, delete a deployment, and read build and runtime events.6 | ||||||
| GET | /v7/deployments | List deployments under the authenticated account or team, filterable by project, state, branch, and time. | read | — | Current | |
Any valid access token can call this; what it returns is bounded by the account or team the token is scoped to. Acts ondeployment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v13/deployments | Create a new deployment, either from inlined or referenced files or by redeploying an existing deployment ID. | write | — | Current | |
Ships code. The token must be scoped to the team that owns the project, and creating production deployments can require elevated team permissions. Acts ondeployment Permission (capability)None required VersionAvailable since the API’s base version Webhook event deployment.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v13/deployments/{idOrUrl} | Retrieve a deployment by its ID or hostname; owners see additional private fields. | read | — | Current | |
Private deployment details are returned only when the token's account or team owns the deployment. Acts ondeployment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v12/deployments/{id}/cancel | Cancel a deployment that is currently building. | write | — | Current | |
Only affects a deployment still in the building state. Acts ondeployment Permission (capability)None required VersionAvailable since the API’s base version Webhook event deployment.canceledRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v13/deployments/{id} | Delete a deployment by its ID, or by its URL passed as a query parameter. | write | — | Current | |
Permanent. The token must be scoped to the account or team that owns the deployment. Acts ondeployment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/deployments/{idOrUrl}/events | Get the build and runtime events for a deployment, as a JSON list or a live stream. | read | — | Current | |
Returns logs such as stdout, stderr, and deployment-state changes; setting follow streams new events as they happen. Acts ondeployment event Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ProjectsList projects, create a project, read one by ID or name, update its settings, and delete a project.5 | ||||||
| GET | /v9/projects | Retrieve a list of the account or team's projects. | read | — | Current | |
Returns the projects visible to the token's account or team scope. Acts onproject Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v11/projects | Create a new project under the account or team. | write | — | Current | |
Creating a project can require the CreateProject team permission on the token's team. Acts onproject Permission (capability)None required VersionAvailable since the API’s base version Webhook event project.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v9/projects/{idOrName} | Find a project by its ID or name. | read | — | Current | |
Visible only within the token's account or team scope. Acts onproject Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v9/projects/{idOrName} | Update a project's settings, such as its framework, build command, or root directory. | write | — | Current | |
Changes how every future deployment of the project builds and runs. Acts onproject Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v9/projects/{idOrName} | Delete a project by its ID or name. | write | — | Current | |
Permanent, and removes the project's deployments and configuration. Acts onproject Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Environment variablesRead a project's environment variables and create one or more on a project.2 | ||||||
| GET | /v10/projects/{idOrName}/env | Retrieve the environment variables for a project, optionally decrypting their values. | read | — | Current | |
Passing decrypt=true returns plaintext values, so this read can expose secrets. Acts onenvironment variable Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v10/projects/{idOrName}/env | Create one or more environment variables on a project, for chosen target environments. | write | — | Current | |
Adding production variables can require additional team permissions beyond a plain token. Acts onenvironment variable Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DomainsList domains, read a single domain's details, and remove a domain from an account or team.3 | ||||||
| GET | /v5/domains | List the domains registered for the account or team. | read | — | Current | |
Returns the domains within the token's account or team scope; defaults to the last 20. Acts ondomain Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v5/domains/{domain} | Get the details of a single domain, including its nameservers and verification state. | read | — | Current | |
Visible only within the token's account or team scope. Acts ondomain Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v6/domains/{domain} | Remove a registered domain from Vercel. | write | — | Current | |
Removing a domain automatically removes any aliases associated with it. Acts ondomain Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DNS recordsList a domain's DNS records, create a record, and delete a record.3 | ||||||
| GET | /v5/domains/{domain}/records | List the DNS records created for a domain. | read | — | Current | |
Returns up to 20 records by default, with timestamp-based pagination for the rest. Acts ondns record Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/domains/{domain}/records | Create a DNS record on a domain, such as an A, AAAA, CNAME, MX, or TXT record. | write | — | Current | |
Changes how a live domain resolves, which can redirect mail or traffic. Acts ondns record Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/domains/{domain}/records/{recordId} | Remove an existing DNS record from a domain. | write | — | Current | |
Removing a record can take a live service offline if it is in use. Acts ondns record Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AliasesList the aliases that map domains to deployments for the account or team.1 | ||||||
| GET | /v4/aliases | List the aliases for the account or team, filterable by domain or project. | read | — | Current | |
An alias maps a domain, such as a .vercel.app subdomain or a custom domain, to a deployment. Acts onalias Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TeamsList the teams the token can see and read a single team's details.2 | ||||||
| GET | /v2/teams | Get a paginated list of the teams the authenticated user belongs to. | read | — | Current | |
A team the token lacks privileges to fully read is returned in a limited form. Acts onteam Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/teams/{teamId} | Get the details of a single team by its ID. | read | — | Current | |
Returns the team only when the token is authorized to access it. Acts onteam Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Edge ConfigList Edge Configs, create an Edge Config, and update its items in batch.3 | ||||||
| GET | /v1/edge-config | Return all Edge Configs for the account or team. | read | — | Current | |
An Edge Config is a low-latency store of key-value data read by deployed apps. Acts onedge config Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/edge-config | Create an Edge Config, optionally seeding it with items. | write | — | Current | |
The slug must start with a letter and use only letters, numbers, and underscores. Acts onedge config Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/edge-config/{edgeConfigId}/items | Update multiple Edge Config items in a single batch. | write | — | Current | |
Changes values read live at the edge by running apps that depend on this Edge Config. Acts onedge config item Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Vercel can notify an app or AI agent when something happens in an account, like a deployment finishing or failing. It sends the event to a webhook registered on the account or team, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
deployment.created | Fires when a deployment is created for a project. | /v13/deployments |
deployment.succeeded | Fires when a deployment finishes building and is ready. | In-app only |
deployment.error | Fires when a deployment fails to build or deploy. | In-app only |
deployment.canceled | Fires when a deployment that was building is canceled. | /v12/deployments/{id}/cancel |
project.created | Fires when a project is created. | /v11/projects |
Vercel limits how fast an app or AI agent can call, through a per-token request rate reported in response headers, with tighter limits on some individual endpoints.
Vercel limits requests per access token and reports the current state in response headers, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset, with a Retry-After header on a 429 response. Some individual endpoints carry their own tighter limit on top of the token-wide rate. Vercel does not publish a single fixed number that applies to every endpoint and plan, so an integration should read the headers rather than assume a value, and back off when X-RateLimit-Remaining reaches zero. Exceeding a limit returns HTTP 429 Too Many Requests.
List endpoints page by timestamp rather than a page number. A response includes a pagination object with count, next, and prev, where next is the timestamp to pass on the following request to fetch older items, and a limit parameter sets the page size. When next is null there are no more pages.
Most list endpoints default to about 20 items per page when no limit is given. Edge Config slugs are capped at 64 characters, an environment variable comment at 500 characters, and a DNS record comment at 500 characters.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | bad_request | One of the provided values in the request body or query is invalid. | Read the error message, correct the named parameter, and resend. |
| 401 | unauthorized | The request is not authorized, usually a missing, invalid, or expired access token. | Send a valid access token in the Authorization header as a Bearer token. |
| 402 | payment_required | The account is missing a payment method, so the request cannot proceed. | Update the billing details on the account, then retry. |
| 403 | forbidden | The token is valid but lacks permission for this resource, for example a token not scoped to the team, or a missing team permission for a production action. | Scope the token to the right account or team, or grant the team permission the action needs. |
| 404 | not_found | The resource does not exist, or is not visible to the token's account or team scope. | Confirm the ID and that the token is scoped to the account or team that owns the resource. |
| 409 | conflict | The request conflicts with the current state, such as creating an environment variable that already exists or acting on a project being transferred. | Refetch the current state and retry once the conflict is resolved. |
| 429 | too_many_requests | The rate limit was exceeded for the token. | Honor the Retry-After header, and slow the request rate using the X-RateLimit headers. |
Vercel versions each endpoint independently, with a version number carried in the path of every call, so the deployment and project endpoints can sit at different versions at the same time.
Vercel does not version the API as a whole. Each endpoint carries its own version number in the path, so deployments sit at /v13, projects at /v9 and /v11, domains at /v5 and /v6, DNS records at /v2, aliases at /v4, teams at /v2, and Edge Config at /v1. Different endpoints advance independently. Older versions stay supported until a deprecation is announced, and a response shape can gain new keys without a version bump. Notable platform changes ship through the changelog rather than a single dated API version.
Vercel launched its official hosted Model Context Protocol server at mcp.vercel.com in public beta, a remote interface with OAuth authorization for AI tools to interact with a Vercel account. At launch it is read-only, with tools for searching docs, managing projects and deployments, and analyzing deployment logs, and it implements the MCP Authorization and Streamable HTTP specifications. It was announced on Monday 4 August 2025.
Vercel's REST API reference became automatically generated and kept in sync with the API, so every endpoint, its parameters, and field types are documented from the source rather than maintained by hand. This is the same machine-readable basis now published as an OpenAPI spec. It was announced on Tuesday 23 November 2021.
Each endpoint is pinned to its own version in the path, and older versions stay supported until a deprecation is announced.
Vercel changelog ↗Bollard AI sits between a team's AI agents and Vercel. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.