Working with the Vercel REST API

Offline reference for the Vercel REST API (api.vercel.com) and the @vercel/sdk TypeScript client. The centerpiece is the complete, machine-readable OpenAPI spec in references/openapi.yaml — the authoritative source for every endpoint, parameter, and schema.

Scope. This skill is the REST API + SDK. For the vercel CLI, the hosted MCP server, and platform concepts (deployments, domains, env vars, functions, storage), use the sibling skill working-with-vercel. For the Vercel AI SDK (ai package), use working-with-vercel-ai-sdk.

How to use this skill

1. For exact endpoint shapes, grep references/openapi.yaml. It's the full OpenAPI 3.x spec (paths, methods, params, request/response schemas, the bearerToken security scheme). Example: grep -n 'createDeployment\|/v13/deployments' references/openapi.yaml, then read the surrounding block. Never guess endpoint paths, params, or schemas from memory — read the spec.
2. Read references/rest-api-guide.md for the cross-cutting concerns the spec doesn't spell out narratively: auth, team scoping, versioning, pagination, errors, and rate limits.
3. Conceptual pages — references/docs__rest-api.md (overview), references/docs__rest-api__errors.md, and references/docs__rest-api__sdk.md carry source/fetched_at/sha256 frontmatter.
4. If something looks stale or missing, fetch the live spec (https://openapi.vercel.sh) or append .md to any vercel.com/docs/rest-api/... page URL.

Behavioral guidance

• Auth: every call needs Authorization: Bearer <token>. Use VERCEL_TOKEN from the environment; never hardcode tokens. The same token works for the CLI.
• Team scoping: resources owned by a team require a teamId (or slug) query param — a common source of 403/404s when omitted.
• Versioning is per-endpoint (/v1/…, /v9/…, /v13/…). Use the exact version path from the spec; don't assume a global version.
• Prefer @vercel/sdk (typed, generated from this same spec) over hand-rolled fetch for TypeScript automation. See references/docs__rest-api__sdk.md.

Keeping this current

references/ is regenerated by scripts/update_docs.js: it fetches the OpenAPI spec from openapi.vercel.sh (converting JSON → YAML via yq) and the conceptual REST pages from vercel.com. Per-endpoint doc pages are intentionally excluded — the spec already covers them, and bundling both would duplicate several MB (and exceed the skill-size limit). A weekly GitHub Action runs it. To refresh locally: make update-working-with-vercel-api.

The API is not URL-versioned at the docs level, so this is a snapshot at fetch time (tracked by fetched_at/sha256), not a version pin — no PINNED_VERSION file.