Vercel API

Use the Vercel API via direct curl calls to manage deployments, projects, domains, environment variables, and webhooks.

Official docs: https://vercel.com/docs/rest-api

When to Use

Use this skill when you need to:

List and manage projects - view, create, delete, and configure projects
Monitor and control deployments - list, redeploy, promote to production, cancel, and view build logs
Manage domains - list, add, and remove domains from projects
Handle environment variables - list, create, and delete env vars
Manage webhooks - create, list, and delete webhooks for deployment events

Prerequisites

Connect your Vercel account at vm0 Settings > Connectors and click vercel
The VERCEL_TOKEN environment variable is automatically configured

Verify authentication:

bash -c 'curl -s "https://api.vercel.com/v2/user" -H "Authorization: Bearer $VERCEL_TOKEN"' | jq '.user | {id, username, email}'

Important: When using $VAR in a command that pipes to another command, wrap the command containing $VAR in bash -c '...'. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'

How to Use

All examples below assume VERCEL_TOKEN is set.

Base URL: https://api.vercel.com

1. Get Current User

Get the authenticated user's profile:

bash -c 'curl -s "https://api.vercel.com/v2/user" -H "Authorization: Bearer $VERCEL_TOKEN"' | jq '.user | {id, username, email, name}'

2. List Projects

Get all projects:

bash -c 'curl -s "https://api.vercel.com/v9/projects" -H "Authorization: Bearer $VERCEL_TOKEN"' | jq '.projects[] | {id, name, framework, updatedAt}'

3. Get Project Details

Get details for a specific project:

Note: Replace my-project with your actual project name or ID from the "List Projects" output.

PROJECT=my-project bash -c 'curl -s "https://api.vercel.com/v9/projects/$PROJECT" -H "Authorization: Bearer $VERCEL_TOKEN"' | jq '{id, name, framework, nodeVersion, buildCommand, outputDirectory}'

4. Create Project

Create a new project:

bash -c 'curl -s -X POST "https://api.vercel.com/v11/projects" -H "Authorization: Bearer $VERCEL_TOKEN" -H "Content-Type: application/json" -d "{\"name\":\"my-new-project\",\"framework\":\"nextjs\"}"' | jq '{id, name, framework}'

Only name is required. Optional fields: framework, buildCommand, outputDirectory, rootDirectory, installCommand.

5. Delete Project

Delete a project:

Warning: This permanently deletes the project and all its deployments.

Note: Replace my-project with the project name or ID.

PROJECT=my-project bash -c 'curl -s -X DELETE "https://api.vercel.com/v9/projects/$PROJECT" -H "Authorization: Bearer $VERCEL_TOKEN" -w "\nHTTP Status: %{http_code}\n"'

Returns 204 No Content on success.

6. List Deployments

Get recent deployments:

bash -c 'curl -s "https://api.vercel.com/v6/deployments?limit=10" -H "Authorization: Bearer $VERCEL_TOKEN"' | jq '.deployments[] | {uid, name, url, state, created: .created}'

7. List Deployments for a Project

Get deployments for a specific project:

Note: Replace my-project with your actual project name or ID.

PROJECT=my-project bash -c 'curl -s "https://api.vercel.com/v6/deployments?projectId=$PROJECT&limit=10" -H "Authorization: Bearer $VERCEL_TOKEN"' | jq '.deployments[] | {uid, url, state, created: .created}'

8. Get Deployment Details

Get details for a specific deployment:

Note: Replace dpl_xxx with an actual deployment ID from the "List Deployments" output.

DEPLOY_ID=dpl_xxx bash -c 'curl -s "https://api.vercel.com/v13/deployments/$DEPLOY_ID" -H "Authorization: Bearer $VERCEL_TOKEN"' | jq '{id, url, state, readyState, createdAt, buildingAt, ready}'

9. Get Deployment Build Logs

Get build logs for a deployment:

Note: Replace dpl_xxx with an actual deployment ID. Use limit=-1 to get all logs.

DEPLOY_ID=dpl_xxx bash -c 'curl -s "https://api.vercel.com/v3/deployments/$DEPLOY_ID/events?limit=-1" -H "Authorization: Bearer $VERCEL_TOKEN"' | jq '.[] | select(.type == "command" or .type == "stdout" or .type == "stderr") | {type, text}'

10. Redeploy a Deployment

Trigger a redeployment of a previous deployment:

Note: Replace my-project with your project name and dpl_xxx with the deployment ID to redeploy.

PROJECT=my-project DEPLOY_ID=dpl_xxx bash -c 'curl -s -X POST "https://api.vercel.com/v13/deployments" -H "Authorization: Bearer $VERCEL_TOKEN" -H "Content-Type: application/json" -d "{\"name\":\"$PROJECT\",\"deploymentId\":\"$DEPLOY_ID\",\"target\":\"production\"}"' | jq '{id, url, readyState, target}'

Add "withLatestCommit": true to force using the latest commit instead of the original deployment's commit.

11. Promote Deployment to Production

Point all production domains to a specific deployment (rollback):

Note: Replace prj_xxx with your project ID and dpl_xxx with the deployment ID to promote.

PROJECT_ID=prj_xxx DEPLOY_ID=dpl_xxx bash -c 'curl -s -X POST "https://api.vercel.com/v1/projects/$PROJECT_ID/rollback/$DEPLOY_ID" -H "Authorization: Bearer $VERCEL_TOKEN" -w "\nHTTP Status: %{http_code}\n"'

Returns 201 Created on success.

12. Cancel Deployment

Cancel a deployment that is currently BUILDING or QUEUED. Deployments already in READY state cannot be canceled.

Note: Replace dpl_xxx with an actual deployment ID of a building/queued deployment.

DEPLOY_ID=dpl_xxx bash -c 'curl -s -X PATCH "https://api.vercel.com/v12/deployments/$DEPLOY_ID/cancel" -H "Authorization: Bearer $VERCEL_TOKEN"' | jq '{id, readyState}'

13. List Domains

Get all domains:

bash -c 'curl -s "https://api.vercel.com/v5/domains" -H "Authorization: Bearer $VERCEL_TOKEN"' | jq '.domains[] | {name, verified, createdAt}'

14. List Project Domains

Get domains configured for a specific project:

Note: Replace my-project with your actual project name or ID.

PROJECT=my-project bash -c 'curl -s "https://api.vercel.com/v9/projects/$PROJECT/domains" -H "Authorization: Bearer $VERCEL_TOKEN"' | jq '.domains[] | {name, redirect, gitBranch}'

15. Add Domain to Project

Add a domain to a project:

Note: Replace my-project with your project name or ID and example.com with the domain to add.

PROJECT=my-project bash -c 'curl -s -X POST "https://api.vercel.com/v10/projects/$PROJECT/domains" -H "Authorization: Bearer $VERCEL_TOKEN" -H "Content-Type: application/json" -d "{\"name\":\"example.com\"}"' | jq '{name, verified, verification}'

If verified is false, complete the DNS verification challenge shown in the verification array.

16. Remove Domain from Project

Remove a domain from a project:

Note: Replace my-project with your project name or ID and example.com with the domain.

PROJECT=my-project DOMAIN=example.com bash -c 'curl -s -X DELETE "https://api.vercel.com/v9/projects/$PROJECT/domains/$DOMAIN" -H "Authorization: Bearer $VERCEL_TOKEN" -w "\nHTTP Status: %{http_code}\n"'

17. List Environment Variables

Get environment variables for a project:

Note: Replace my-project with your actual project name or ID.

PROJECT=my-project bash -c 'curl -s "https://api.vercel.com/v9/projects/$PROJECT/env" -H "Authorization: Bearer $VERCEL_TOKEN"' | jq '.envs[] | {id, key, target, type}'

18. Create Environment Variable

Add an environment variable to a project:

Note: Replace my-project with your actual project name or ID.

PROJECT=my-project bash -c 'curl -s -X POST "https://api.vercel.com/v10/projects/$PROJECT/env" -H "Authorization: Bearer $VERCEL_TOKEN" -H "Content-Type: application/json" -d "{\"key\":\"MY_VAR\",\"value\":\"my-value\",\"type\":\"encrypted\",\"target\":[\"production\",\"preview\",\"development\"]}"' | jq '.created | {key, target, type}'

19. Delete Environment Variable

Delete an environment variable from a project:

Note: Replace my-project with the project name or ID. Get the env var id from "List Environment Variables" output.

PROJECT=my-project ENV_ID=xxx bash -c 'curl -s -X DELETE "https://api.vercel.com/v9/projects/$PROJECT/env/$ENV_ID" -H "Authorization: Bearer $VERCEL_TOKEN"' | jq '{id, key}'

20. List Webhooks

Get all webhooks:

bash -c 'curl -s "https://api.vercel.com/v1/webhooks" -H "Authorization: Bearer $VERCEL_TOKEN"' | jq '.[] | {id, url, events, projectIds}'

21. Create Webhook

Create a webhook for deployment events:

Note: Replace the url with your webhook endpoint. Optionally scope to specific projects with projectIds.

bash -c 'curl -s -X POST "https://api.vercel.com/v1/webhooks" -H "Authorization: Bearer $VERCEL_TOKEN" -H "Content-Type: application/json" -d "{\"url\":\"https://example.com/webhook\",\"events\":[\"deployment.created\",\"deployment.succeeded\",\"deployment.error\"]}"' | jq '{id, url, events, secret}'

The secret is only returned at creation time. Save it to verify webhook payloads via the x-vercel-signature header.

Common events: deployment.created, deployment.succeeded, deployment.error, deployment.canceled, deployment.ready, project.created, project.removed.

22. Delete Webhook

Delete a webhook:

Note: Replace hook_xxx with the webhook ID from "List Webhooks" output.

HOOK_ID=hook_xxx bash -c 'curl -s -X DELETE "https://api.vercel.com/v1/webhooks/$HOOK_ID" -H "Authorization: Bearer $VERCEL_TOKEN" -w "\nHTTP Status: %{http_code}\n"'

Returns 204 No Content on success.

Deployment States

State	Description
`BUILDING`	Build in progress
`READY`	Deployment is live
`ERROR`	Build or deployment failed
`CANCELED`	Deployment was canceled
`QUEUED`	Waiting to build

Guidelines

Pagination: Use ?limit=N&until=<timestamp> for paginated results
Rate limits: Vercel has rate limits; implement backoff for 429 responses
Project references: You can use either project ID or project name in most endpoints