Vercel API and CLI: Deployments, Projects, Domains, and Env Vars

Overview

The Vercel platform API (https://api.vercel.com) exposes 200+ endpoints for deployments, projects, domains, DNS, environment variables, teams, and more. The CLI wraps most operations for local use.

Authentication

# Personal Access Token
curl -H "Authorization: Bearer $VERCEL_TOKEN" https://api.vercel.com/v2/user

# Team scope (append to all requests)
https://api.vercel.com/v6/deployments?teamId=team_xxxxx

# CLI team scope
vercel --scope my-team deploy --prod

Token types: Personal Access Token (vercel.com/account/tokens), OAuth (integrations), Scoped (limited-permission automation).

CLI Installation and Core Commands

npm i -g vercel

# Deploy
vercel deploy --prod

# Link project
vercel link

# Environment variables
vercel env pull .env.local        # Pull to local file
vercel env add KEY production     # Add to production
vercel env ls                     # List all

# Logs
vercel logs <deployment-url>
vercel logs --follow              # Stream live

# Domains
vercel domains add example.com
vercel domains ls

# Rollback
vercel rollback <deployment-url>

# Project info
vercel inspect <deployment-url>

REST API Endpoint Categories

| Category | Key Operations | |----------|----------------| | Projects (27 endpoints) | CRUD, domains, env vars, members, settings | | Deployments (10) | Create, get, list, cancel, delete | | Domains (6) | Add, remove, verify, transfer | | DNS (4) | List, add, update, remove records | | Environment (11) | Create, update, delete, list per target | | Aliases (6) | Set, remove, list custom domain aliases | | Teams (14) | Create, invite, manage members | | Logs (1) | Runtime log retrieval (streaming) | | Webhooks (4) | Create, list, get, delete | | Edge-Config (17) | Create, read, update, delete | | Checks (10) | Deployment checks for CI integration |

Common API Patterns

List Deployments

curl -H "Authorization: Bearer $VERCEL_TOKEN" \
  "https://api.vercel.com/v6/deployments?projectId=prj_xxx&limit=5"

Create Deployment via API

curl -X POST \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-app","gitSource":{"type":"github","repoId":"123","ref":"main"}}' \
  "https://api.vercel.com/v13/deployments"

Set Environment Variable

curl -X POST \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"DATABASE_URL","value":"postgres://...","target":["production"],"type":"encrypted"}' \
  "https://api.vercel.com/v10/projects/prj_xxx/env"

Add DNS Record

curl -X POST \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"api","type":"CNAME","value":"target.example.com"}' \
  "https://api.vercel.com/v2/domains/example.com/records"

Environment Variable Targets

| Target | When Used | |--------|-----------| | production | vercel deploy --prod | | preview | Branch and PR deployments | | development | vercel dev local server |

Always set sensitive keys in Vercel dashboard, not in .env files committed to git.

Deploy from GitHub Actions

- name: Deploy to Vercel
  env:
    VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
    VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
    VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
  run: |
    npm i -g vercel
    vercel pull --yes --environment=production --token=$VERCEL_TOKEN
    vercel build --prod --token=$VERCEL_TOKEN
    vercel deploy --prebuilt --prod --token=$VERCEL_TOKEN

Edge Config

Edge Config is a global key-value store with sub-millisecond reads at the edge. Use for feature flags and A/B config.

# Create via API
curl -X POST -H "Authorization: Bearer $VERCEL_TOKEN" \
  -d '{"slug":"my-flags"}' \
  "https://api.vercel.com/v1/edge-config"

# Read in code (Next.js)
import { get } from "@vercel/edge-config";
const isEnabled = await get("feature-x");

Webhooks

curl -X POST -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://api.example.com/webhook","events":["deployment.created","deployment.ready"]}' \
  "https://api.vercel.com/v1/webhooks"

Events: deployment.created, deployment.ready, deployment.error, deployment.canceled.

Project Settings via API

# Get project
curl -H "Authorization: Bearer $VERCEL_TOKEN" \
  "https://api.vercel.com/v9/projects/prj_xxx"

# Update build command
curl -X PATCH -H "Authorization: Bearer $VERCEL_TOKEN" \
  -d '{"buildCommand":"npm run build:prod"}' \
  "https://api.vercel.com/v9/projects/prj_xxx"