--- name: vercel description: | Vercel API integration with managed OAuth. Manage projects, deployments, domains, teams, and environment variables. Use this skill when users want to interact with Vercel - deploying apps, managing projects, checking deployment status, or configuring domains. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). compatibility: Requires network access and valid Maton API key metadata: author: maton version: "1.0" clawdbot: emoji: "▲" homepage: "https://maton.ai" requires: env: - MATON_API_KEY --- # Vercel Access the Vercel API with managed OAuth authentication. Manage projects, deployments, domains, teams, and environment variables. ## Quick Start ```bash # List projects python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/vercel/v9/projects?limit=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ## Base URL ``` https://api.maton.ai/vercel/ ``` Only the endpoints listed in the API Reference section below are supported. Maton proxies requests to `api.vercel.com` and automatically injects your OAuth token. ## Authentication All requests require the Maton API key in the Authorization header: ``` Authorization: Bearer $MATON_API_KEY ``` **Environment Variable:** Set your API key as `MATON_API_KEY`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ### Getting Your API Key 1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key ## Connection Management Manage your Vercel OAuth connections at `https://api.maton.ai`. ### List Connections ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/connections?app=vercel&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Create Connection ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'vercel'}).encode() req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Get Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "connection": { "connection_id": "{connection_id}", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "vercel", "metadata": {} } } ``` Open the returned `url` in a browser to complete OAuth authorization. ### Delete Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Specifying Connection If you have multiple Vercel connections, specify which one to use with the `Maton-Connection` header: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/vercel/v9/projects') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '{connection_id}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` If you have multiple connections, always include this header to ensure requests go to the intended account. ## Security & Permissions - Access is scoped to projects, deployments, domains, teams, and environment variables within the connected Vercel account. - **All write operations require explicit user approval.** Before executing any create, update, or delete call, confirm the target resource and intended effect with the user. - **Production impact**: Deployments, domain changes, team modifications, and environment variable updates directly affect live applications and collaborators. Confirm before modifying production resources. ## API Reference ### User #### Get Current User ```bash GET /vercel/v2/user ``` **Response:** ```json { "user": { "id": "srL5ucia16R88imgFgrn9XHH", "email": "user@example.com", "username": "username", "name": "User Name", "avatar": null, "defaultTeamId": "team_abc123", "billing": { "plan": "hobby", "status": "active" } } } ``` ### Teams #### List Teams ```bash GET /vercel/v2/teams ``` **Response:** ```json { "teams": [ { "id": "team_1xPDNnVvmKxzxPs2x2XQRoKu", "slug": "my-team", "name": "My Team", "createdAt": 1732138693523, "membership": { "role": "OWNER" }, "billing": { "plan": "hobby", "status": "active" } } ], "pagination": { "count": 1, "next": null, "prev": null } } ``` ### Projects #### List Projects ```bash GET /vercel/v9/projects?limit=20 ``` **Response:** ```json { "projects": [ { "id": "prj_ET9o8o6WAQTfWbtF8NeFe4XF9uYG", "name": "my-project", "accountId": "team_abc123", "framework": "nextjs", "nodeVersion": "22.x", "createdAt": 1733304037737, "updatedAt": 1766947708146, "targets": {}, "latestDeployments": [] } ], "pagination": { "count": 20, "next": 1733304037737, "prev": null } } ``` #### Get Project ```bash GET /vercel/v9/projects/{projectId} ``` **Response:** ```json { "id": "prj_ET9o8o6WAQTfWbtF8NeFe4XF9uYG", "name": "my-project", "accountId": "team_abc123", "framework": "nextjs", "nodeVersion": "22.x", "createdAt": 1733304037737, "updatedAt": 1766947708146, "buildCommand": null, "devCommand": null, "installCommand": null, "outputDirectory": null, "rootDirectory": null, "serverlessFunctionRegion": "iad1" } ``` #### Create Project ```bash POST /vercel/v9/projects Content-Type: application/json { "name": "my-new-project", "framework": "nextjs", "gitRepository": { "type": "github", "repo": "username/repo" } } ``` #### Update Project ```bash PATCH /vercel/v9/projects/{projectId} Content-Type: application/json { "name": "updated-project-name", "buildCommand": "npm run build" } ``` #### Delete Project ```bash DELETE /vercel/v9/projects/{projectId} ``` ### Deployments #### List Deployments ```bash GET /vercel/v6/deployments?limit=20 ``` **Query Parameters:** - `limit` - Number of results (default: 20) - `projectId` - Filter by project ID - `target` - Filter by target (`production`, `preview`) - `state` - Filter by state (`BUILDING`, `READY`, `ERROR`, `CANCELED`) **Response:** ```json { "deployments": [ { "uid": "dpl_8gFe6M8XZsQ1ohP86VWTemcBAmZJ", "name": "my-project", "url": "my-project-abc123.vercel.app", "created": 1759739951209, "state": "READY", "readyState": "READY", "target": "production", "source": "git", "creator": { "uid": "srL5ucia16R88imgFgrn9XHH", "username": "username" }, "meta": { "githubCommitRef": "main", "githubCommitSha": "6e88c2d..." } } ], "pagination": { "count": 20, "next": 1759739951209, "prev": null } } ``` #### Get Deployment ```bash GET /vercel/v13/deployments/{deploymentId} ``` **Response:** ```json { "id": "dpl_8gFe6M8XZsQ1ohP86VWTemcBAmZJ", "name": "my-project", "url": "my-project-abc123.vercel.app", "created": 1759739951209, "buildingAt": 1759739952144, "ready": 1759740085170, "state": "READY", "readyState": "READY", "target": "production", "source": "git", "creator": { "uid": "srL5ucia16R88imgFgrn9XHH", "username": "username" } } ``` #### Get Deployment Build Logs ```bash GET /vercel/v3/deployments/{deploymentId}/events ``` **Response:** ```json [ { "created": 1759739951860, "deploymentId": "dpl_8gFe6M8XZsQ1ohP86VWTemcBAmZJ", "text": "Running build in Washington, D.C., USA (East) – iad1", "type": "stdout", "info": { "type": "build", "name": "bld_b3go7zd2k" } } ] ``` #### Cancel Deployment ```bash PATCH /vercel/v12/deployments/{deploymentId}/cancel ``` ### Environment Variables #### List Environment Variables ```bash GET /vercel/v10/projects/{projectId}/env ``` **Response:** ```json { "envs": [ { "id": "6EwQRCd32PVNHORP", "key": "API_KEY", "value": "...", "type": "encrypted", "target": ["production", "preview", "development"], "createdAt": 1732148489672, "updatedAt": 1745542152381 } ] } ``` #### Create Environment Variable ```bash POST /vercel/v10/projects/{projectId}/env Content-Type: application/json { "key": "MY_ENV_VAR", "value": "my-value", "type": "encrypted", "target": ["production", "preview"] } ``` #### Update Environment Variable ```bash PATCH /vercel/v10/projects/{projectId}/env/{envId} Content-Type: application/json { "value": "updated-value" } ``` #### Delete Environment Variable ```bash DELETE /vercel/v10/projects/{projectId}/env/{envId} ``` ### Domains #### List Domains ```bash GET /vercel/v5/domains ``` **Response:** ```json { "domains": [ { "name": "example.com", "apexName": "example.com", "projectId": "prj_abc123", "verified": true, "createdAt": 1732138693523 } ], "pagination": { "count": 10, "next": null, "prev": null } } ``` #### Get Domain ```bash GET /vercel/v5/domains/{domain} ``` #### Add Domain ```bash POST /vercel/v5/domains Content-Type: application/json { "name": "example.com" } ``` #### Remove Domain ```bash DELETE /vercel/v6/domains/{domain} ``` ### Artifacts (Remote Caching) #### Get Artifacts Status ```bash GET /vercel/v8/artifacts/status ``` **Response:** ```json { "status": "enabled" } ``` ## Pagination Vercel uses cursor-based pagination with `next` and `prev` cursors: ```bash GET /vercel/v9/projects?limit=20&until=1733304037737 ``` **Parameters:** - `limit` - Results per page (varies by endpoint, typically max 100) - `until` - Cursor for next page (use `next` from response) - `since` - Cursor for previous page (use `prev` from response) **Response includes:** ```json { "pagination": { "count": 20, "next": 1733304037737, "prev": 1759739951209 } } ``` ## Code Examples ### JavaScript ```javascript const response = await fetch( 'https://api.maton.ai/vercel/v9/projects?limit=10', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const data = await response.json(); ``` ### Python ```python import os import requests response = requests.get( 'https://api.maton.ai/vercel/v9/projects', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, params={'limit': 10} ) data = response.json() ``` ### List Deployments for a Project ```python import os import requests project_id = 'prj_abc123' response = requests.get( 'https://api.maton.ai/vercel/v6/deployments', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, params={'projectId': project_id, 'limit': 10} ) deployments = response.json()['deployments'] ``` ## Notes - API versions vary by endpoint (v2, v5, v6, v9, v10, v13, etc.) - Timestamps are in milliseconds since Unix epoch - Project IDs start with `prj_`, deployment IDs start with `dpl_`, team IDs start with `team_` - Deployment states: `BUILDING`, `READY`, `ERROR`, `CANCELED`, `QUEUED` - Environment variable types: `plain`, `encrypted`, `secret`, `sensitive` - Environment targets: `production`, `preview`, `development` - IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets to disable glob parsing - IMPORTANT: When piping curl output to `jq`, environment variables may not expand correctly in some shells ## Error Handling | Status | Meaning | |--------|---------| | 400 | Missing Vercel connection or invalid request | | 401 | Invalid or missing Maton API key | | 403 | Insufficient permissions | | 404 | Resource not found | | 429 | Rate limited | | 4xx/5xx | Passthrough error from Vercel API | ## Resources - [Vercel REST API Documentation](https://vercel.com/docs/rest-api) - [Vercel API Reference](https://vercel.com/docs/rest-api/endpoints) - [Maton Community](https://discord.com/invite/dBfFAcefs2) - [Maton Support](mailto:support@maton.ai)

Vercel

Description

Latest Changes

Install Vercel with One Click