Vapi Platform Skill
Manage the full Vapi voice AI platform through CLI scripts wrapping the REST API (https://api.vapi.ai).
Authentication
| Key |
Env Variable |
Use For |
| Private Key |
VAPI_PRIVATE_API_KEY |
All API operations (required) |
| Public Key |
VAPI_PUBLIC_API_KEY |
Client-side SDK only |
Add to .env:
VAPI_PRIVATE_API_KEY=your-private-key-here
Scripts auto-load from .env using grep (not source). Override path with VAPI_ENV_FILE=/path/to/.env.
CLI Scripts
All scripts live in .claude/skills/vapi-platform/scripts/. Each handles one resource type with subcommands.
Quick Reference
| Script |
Resource |
Operations |
vapi-assistants.sh |
Assistants |
list, list-summary, get, create, update, delete |
vapi-calls.sh |
Calls |
list, get, create, update, delete |
vapi-phone-numbers.sh |
Phone Numbers |
list, list-summary, get, create, update, delete |
vapi-squads.sh |
Squads |
list, list-summary, get, create, update, delete |
vapi-tools.sh |
Tools |
list, list-summary, get, create, update, delete |
vapi-files.sh |
Files |
list, list-summary, get, upload, delete |
vapi-knowledge-bases.sh |
Knowledge Bases |
list, list-summary, get, create, update, delete |
vapi-blocks.sh |
Blocks |
list, list-summary, get, create, update, delete |
vapi-sessions.sh |
Sessions |
list, get, create |
vapi-chats.sh |
Chats |
list, create |
vapi-campaigns.sh |
Campaigns |
list, list-summary, get, create, update |
vapi-logs.sh |
Logs |
list, get |
vapi-evals.sh |
Evals |
list, list-summary, get, create, update, delete |
vapi-eval-runs.sh |
Eval Runs |
list, list-summary, get, run, poll |
Usage Pattern
SCRIPTS=".claude/skills/vapi-platform/scripts"
# List resources
bash $SCRIPTS/vapi-assistants.sh list
bash $SCRIPTS/vapi-assistants.sh list-summary
# Get by ID
bash $SCRIPTS/vapi-assistants.sh get <id>
# Create (pass JSON body)
bash $SCRIPTS/vapi-assistants.sh create '{"name": "My Assistant", ...}'
# Update (pass ID + JSON body)
bash $SCRIPTS/vapi-assistants.sh update <id> '{"name": "New Name"}'
# Delete
bash $SCRIPTS/vapi-assistants.sh delete <id>
# Upload file (special case)
bash $SCRIPTS/vapi-files.sh upload /path/to/document.pdf
# Filter with query params
bash $SCRIPTS/vapi-logs.sh list "limit=10" "createdAtGt=2026-01-01T00:00:00Z"
Common Workflows
Create an assistant and make a call:
# 1. Create assistant
bash $SCRIPTS/vapi-assistants.sh create '{
"name": "Receptionist",
"firstMessage": "Hello! How can I help?",
"transcriber": {"provider": "deepgram", "model": "nova-3", "language": "en"},
"model": {"provider": "openai", "model": "gpt-4o", "systemPrompt": "You are a helpful receptionist."},
"voice": {"provider": "11labs", "voiceId": "rachel"}
}'
# 2. List phone numbers
bash $SCRIPTS/vapi-phone-numbers.sh list-summary
# 3. Make outbound call
bash $SCRIPTS/vapi-calls.sh create '{
"assistantId": "ASSISTANT_ID",
"phoneNumberId": "PHONE_NUMBER_ID",
"customer": {"number": "+1XXXXXXXXXX"}
}'
Batch outbound calls:
bash $SCRIPTS/vapi-calls.sh create '{
"assistantId": "ASSISTANT_ID",
"phoneNumberId": "PHONE_NUMBER_ID",
"customers": [{"number": "+1XXXXXXXXXX"}, {"number": "+1YYYYYYYYYY"}]
}'
Scheduled call:
bash $SCRIPTS/vapi-calls.sh create '{
"assistantId": "ASSISTANT_ID",
"phoneNumberId": "PHONE_NUMBER_ID",
"customer": {"number": "+1XXXXXXXXXX"},
"schedulePlan": {"earliestAt": "2026-03-01T10:00:00Z", "latestAt": "2026-03-01T12:00:00Z"}
}'
Web call (no phone number):
bash $SCRIPTS/vapi-calls.sh create '{"assistantId": "ASSISTANT_ID", "type": "webCall"}'
Import Twilio number:
bash $SCRIPTS/vapi-phone-numbers.sh create '{
"provider": "twilio",
"number": "+1XXXXXXXXXX",
"twilioAccountSid": "AC...",
"twilioAuthToken": "TOKEN",
"assistantId": "ASSISTANT_ID"
}'
Create function tool:
bash $SCRIPTS/vapi-tools.sh create '{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get weather for a location",
"parameters": {
"type": "object",
"properties": {"location": {"type": "string", "description": "City name"}},
"required": ["location"]
}
},
"server": {"url": "https://your-server.com/api/weather"}
}'
Upload file and create knowledge base:
bash $SCRIPTS/vapi-files.sh upload /path/to/faq.pdf
bash $SCRIPTS/vapi-knowledge-bases.sh create '{
"name": "Product FAQ",
"fileIds": ["FILE_ID_1"],
"provider": "google"
}'
Create multi-assistant squad:
bash $SCRIPTS/vapi-squads.sh create '{
"name": "Customer Service Squad",
"members": [{"assistantId": "GREETER_ID"}, {"assistantId": "BOOKING_ID"}]
}'
Create eval and run it against an assistant:
# 1. Create an eval definition
bash $SCRIPTS/vapi-evals.sh create '{
"name": "Greeting test",
"type": "chat.mockConversation",
"messages": [
{"role": "user", "content": "Hello"},
{
"role": "assistant",
"judgePlan": {
"type": "ai",
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [{"role": "system", "content": "Did the assistant greet warmly and offer help? Output pass or fail."}]
}
}
}
]
}'
# 2. Run eval against assistant (type: "eval" is required)
bash $SCRIPTS/vapi-eval-runs.sh run '{
"type": "eval",
"evalId": "EVAL_ID",
"target": {"type": "assistant", "assistantId": "ASSISTANT_ID"}
}'
# 3. Poll for results
bash $SCRIPTS/vapi-eval-runs.sh poll <RUN_ID>
Run inline eval (without saving, type: "eval" is always required):
bash $SCRIPTS/vapi-eval-runs.sh run '{
"type": "eval",
"eval": {
"type": "chat.mockConversation",
"messages": [
{"role": "user", "content": "Book me for tomorrow at 10am"},
{
"role": "assistant",
"judgePlan": {
"type": "exact",
"toolCalls": [{"name": "bookAppointment", "arguments": {"date": "2026-03-07", "time": "10:00"}}]
}
}
]
},
"target": {"type": "assistant", "assistantId": "ASSISTANT_ID"}
}'
Argument Handling
When the user provides arguments like /vapi list assistants, map to scripts:
list {resource} → bash $SCRIPTS/vapi-{resource}.sh list
get {resource} {id} → bash $SCRIPTS/vapi-{resource}.sh get {id}
create {resource} → Guide through creation, then bash $SCRIPTS/vapi-{resource}.sh create '<json>'
update {resource} {id} → Guide through update, then bash $SCRIPTS/vapi-{resource}.sh update {id} '<json>'
delete {resource} {id} → Confirm, then bash $SCRIPTS/vapi-{resource}.sh delete {id}
call {number} → Create outbound call (ask for assistant/phone number IDs)
status → bash $SCRIPTS/vapi-calls.sh list + bash $SCRIPTS/vapi-assistants.sh list-summary
Operational Guidelines
- Scripts use
grep-based key loading — not source .env (avoids side effects from other env vars)
- Always use the Private Key (
$VAPI_PRIVATE_API_KEY) — public key can list but not get/mutate
- PATCH replaces nested objects entirely — when updating any field inside
model (e.g., temperature, provider), you MUST include the full model object including messages, toolIds, etc. Otherwise they get wiped. Top-level fields (firstMessage, voice, transcriber) are safe to patch individually.
- Always GET before PATCH — fetch the current assistant config first, then merge your changes into the full object before sending the update
- Confirm destructive operations (delete) before executing
- Validate IDs look like UUIDs before making requests
- Use
list-summary for quick overviews, list for full JSON
- Never expose the API key in output or logs
- On 401 errors — verify using Private Key, check
.env file has the key
Configuration Reference
For detailed schemas, voice pipeline config, transcribers, LLM providers, TTS providers, hooks, and analysis plans:
- api-reference.md — Full endpoint schemas and response formats
- configuration-guide.md — Voice pipeline, hooks, analysis plans
Provider Quick Reference
Transcribers (STT): deepgram (nova-3), assembly-ai, azure, gladia, google, elevenlabs, openai (whisper), speechmatics, custom
LLM: openai (gpt-4o, gpt-4o-mini), anthropic (claude-3-5-sonnet), google (gemini-1.5-pro), groq (llama, mixtral), custom
Voice/TTS: 11labs, playht, azure, deepgram, lmnt, cartesia, rime, neets, custom
Telephony: twilio, vonage, telnyx, vapi (built-in, limited)
1---2name: vapi3description: Manages the Vapi voice AI platform API. Use when the user wants to create, list, update, or delete Vapi resources (assistants, calls, phone numbers, squads, tools, files, knowledge bases, blocks, sessions, campaigns, logs, evals, eval runs), make outbound calls, configure voice pipelines, run eval tests against assistants, or manage their Vapi account. Handles all CRUD operations against the Vapi REST API.4allowed-tools: Bash, Read, Grep, Glob, WebFetch5metadata:6 source: https://skillmd.com/skills/profsynapse/vapi7---89# Vapi Platform Skill1011Manage the full Vapi voice AI platform through CLI scripts wrapping the REST API (`https://api.vapi.ai`).1213## Authentication1415| Key | Env Variable | Use For |16|-----|-------------|---------|17| **Private Key** | `VAPI_PRIVATE_API_KEY` | All API operations (required) |18| **Public Key** | `VAPI_PUBLIC_API_KEY` | Client-side SDK only |1920Add to `.env`:21```22VAPI_PRIVATE_API_KEY=your-private-key-here23```2425Scripts auto-load from `.env` using `grep` (not `source`). Override path with `VAPI_ENV_FILE=/path/to/.env`.2627## CLI Scripts2829All scripts live in `.claude/skills/vapi-platform/scripts/`. Each handles one resource type with subcommands.3031### Quick Reference3233| Script | Resource | Operations |34|--------|----------|------------|35| `vapi-assistants.sh` | Assistants | list, list-summary, get, create, update, delete |36| `vapi-calls.sh` | Calls | list, get, create, update, delete |37| `vapi-phone-numbers.sh` | Phone Numbers | list, list-summary, get, create, update, delete |38| `vapi-squads.sh` | Squads | list, list-summary, get, create, update, delete |39| `vapi-tools.sh` | Tools | list, list-summary, get, create, update, delete |40| `vapi-files.sh` | Files | list, list-summary, get, upload, delete |41| `vapi-knowledge-bases.sh` | Knowledge Bases | list, list-summary, get, create, update, delete |42| `vapi-blocks.sh` | Blocks | list, list-summary, get, create, update, delete |43| `vapi-sessions.sh` | Sessions | list, get, create |44| `vapi-chats.sh` | Chats | list, create |45| `vapi-campaigns.sh` | Campaigns | list, list-summary, get, create, update |46| `vapi-logs.sh` | Logs | list, get |47| `vapi-evals.sh` | Evals | list, list-summary, get, create, update, delete |48| `vapi-eval-runs.sh` | Eval Runs | list, list-summary, get, run, poll |4950### Usage Pattern5152```bash53SCRIPTS=".claude/skills/vapi-platform/scripts"5455# List resources56bash $SCRIPTS/vapi-assistants.sh list57bash $SCRIPTS/vapi-assistants.sh list-summary5859# Get by ID60bash $SCRIPTS/vapi-assistants.sh get <id>6162# Create (pass JSON body)63bash $SCRIPTS/vapi-assistants.sh create '{"name": "My Assistant", ...}'6465# Update (pass ID + JSON body)66bash $SCRIPTS/vapi-assistants.sh update <id> '{"name": "New Name"}'6768# Delete69bash $SCRIPTS/vapi-assistants.sh delete <id>7071# Upload file (special case)72bash $SCRIPTS/vapi-files.sh upload /path/to/document.pdf7374# Filter with query params75bash $SCRIPTS/vapi-logs.sh list "limit=10" "createdAtGt=2026-01-01T00:00:00Z"76```7778### Common Workflows7980**Create an assistant and make a call:**81```bash82# 1. Create assistant83bash $SCRIPTS/vapi-assistants.sh create '{84 "name": "Receptionist",85 "firstMessage": "Hello! How can I help?",86 "transcriber": {"provider": "deepgram", "model": "nova-3", "language": "en"},87 "model": {"provider": "openai", "model": "gpt-4o", "systemPrompt": "You are a helpful receptionist."},88 "voice": {"provider": "11labs", "voiceId": "rachel"}89}'9091# 2. List phone numbers92bash $SCRIPTS/vapi-phone-numbers.sh list-summary9394# 3. Make outbound call95bash $SCRIPTS/vapi-calls.sh create '{96 "assistantId": "ASSISTANT_ID",97 "phoneNumberId": "PHONE_NUMBER_ID",98 "customer": {"number": "+1XXXXXXXXXX"}99}'100```101102**Batch outbound calls:**103```bash104bash $SCRIPTS/vapi-calls.sh create '{105 "assistantId": "ASSISTANT_ID",106 "phoneNumberId": "PHONE_NUMBER_ID",107 "customers": [{"number": "+1XXXXXXXXXX"}, {"number": "+1YYYYYYYYYY"}]108}'109```110111**Scheduled call:**112```bash113bash $SCRIPTS/vapi-calls.sh create '{114 "assistantId": "ASSISTANT_ID",115 "phoneNumberId": "PHONE_NUMBER_ID",116 "customer": {"number": "+1XXXXXXXXXX"},117 "schedulePlan": {"earliestAt": "2026-03-01T10:00:00Z", "latestAt": "2026-03-01T12:00:00Z"}118}'119```120121**Web call (no phone number):**122```bash123bash $SCRIPTS/vapi-calls.sh create '{"assistantId": "ASSISTANT_ID", "type": "webCall"}'124```125126**Import Twilio number:**127```bash128bash $SCRIPTS/vapi-phone-numbers.sh create '{129 "provider": "twilio",130 "number": "+1XXXXXXXXXX",131 "twilioAccountSid": "AC...",132 "twilioAuthToken": "TOKEN",133 "assistantId": "ASSISTANT_ID"134}'135```136137**Create function tool:**138```bash139bash $SCRIPTS/vapi-tools.sh create '{140 "type": "function",141 "function": {142 "name": "get_weather",143 "description": "Get weather for a location",144 "parameters": {145 "type": "object",146 "properties": {"location": {"type": "string", "description": "City name"}},147 "required": ["location"]148 }149 },150 "server": {"url": "https://your-server.com/api/weather"}151}'152```153154**Upload file and create knowledge base:**155```bash156bash $SCRIPTS/vapi-files.sh upload /path/to/faq.pdf157bash $SCRIPTS/vapi-knowledge-bases.sh create '{158 "name": "Product FAQ",159 "fileIds": ["FILE_ID_1"],160 "provider": "google"161}'162```163164**Create multi-assistant squad:**165```bash166bash $SCRIPTS/vapi-squads.sh create '{167 "name": "Customer Service Squad",168 "members": [{"assistantId": "GREETER_ID"}, {"assistantId": "BOOKING_ID"}]169}'170```171172**Create eval and run it against an assistant:**173```bash174# 1. Create an eval definition175bash $SCRIPTS/vapi-evals.sh create '{176 "name": "Greeting test",177 "type": "chat.mockConversation",178 "messages": [179 {"role": "user", "content": "Hello"},180 {181 "role": "assistant",182 "judgePlan": {183 "type": "ai",184 "model": {185 "provider": "openai",186 "model": "gpt-4o",187 "messages": [{"role": "system", "content": "Did the assistant greet warmly and offer help? Output pass or fail."}]188 }189 }190 }191 ]192}'193194# 2. Run eval against assistant (type: "eval" is required)195bash $SCRIPTS/vapi-eval-runs.sh run '{196 "type": "eval",197 "evalId": "EVAL_ID",198 "target": {"type": "assistant", "assistantId": "ASSISTANT_ID"}199}'200201# 3. Poll for results202bash $SCRIPTS/vapi-eval-runs.sh poll <RUN_ID>203```204205**Run inline eval (without saving, type: "eval" is always required):**206```bash207bash $SCRIPTS/vapi-eval-runs.sh run '{208 "type": "eval",209 "eval": {210 "type": "chat.mockConversation",211 "messages": [212 {"role": "user", "content": "Book me for tomorrow at 10am"},213 {214 "role": "assistant",215 "judgePlan": {216 "type": "exact",217 "toolCalls": [{"name": "bookAppointment", "arguments": {"date": "2026-03-07", "time": "10:00"}}]218 }219 }220 ]221 },222 "target": {"type": "assistant", "assistantId": "ASSISTANT_ID"}223}'224```225226## Argument Handling227228When the user provides arguments like `/vapi list assistants`, map to scripts:229- `list {resource}` → `bash $SCRIPTS/vapi-{resource}.sh list`230- `get {resource} {id}` → `bash $SCRIPTS/vapi-{resource}.sh get {id}`231- `create {resource}` → Guide through creation, then `bash $SCRIPTS/vapi-{resource}.sh create '<json>'`232- `update {resource} {id}` → Guide through update, then `bash $SCRIPTS/vapi-{resource}.sh update {id} '<json>'`233- `delete {resource} {id}` → Confirm, then `bash $SCRIPTS/vapi-{resource}.sh delete {id}`234- `call {number}` → Create outbound call (ask for assistant/phone number IDs)235- `status` → `bash $SCRIPTS/vapi-calls.sh list` + `bash $SCRIPTS/vapi-assistants.sh list-summary`236237## Operational Guidelines2382391. **Scripts use `grep`-based key loading** — not `source .env` (avoids side effects from other env vars)2402. **Always use the Private Key** (`$VAPI_PRIVATE_API_KEY`) — public key can list but not get/mutate2413. **PATCH replaces nested objects entirely** — when updating any field inside `model` (e.g., temperature, provider), you MUST include the **full `model` object** including `messages`, `toolIds`, etc. Otherwise they get wiped. Top-level fields (`firstMessage`, `voice`, `transcriber`) are safe to patch individually.2424. **Always GET before PATCH** — fetch the current assistant config first, then merge your changes into the full object before sending the update2435. **Confirm destructive operations** (delete) before executing2446. **Validate IDs** look like UUIDs before making requests2457. **Use `list-summary`** for quick overviews, `list` for full JSON2468. **Never expose the API key** in output or logs2479. **On 401 errors** — verify using Private Key, check `.env` file has the key248249## Configuration Reference250251For detailed schemas, voice pipeline config, transcribers, LLM providers, TTS providers, hooks, and analysis plans:252- [api-reference.md](references/api-reference.md) — Full endpoint schemas and response formats253- [configuration-guide.md](references/configuration-guide.md) — Voice pipeline, hooks, analysis plans254255## Provider Quick Reference256257**Transcribers (STT):** `deepgram` (nova-3), `assembly-ai`, `azure`, `gladia`, `google`, `elevenlabs`, `openai` (whisper), `speechmatics`, `custom`258259**LLM:** `openai` (gpt-4o, gpt-4o-mini), `anthropic` (claude-3-5-sonnet), `google` (gemini-1.5-pro), `groq` (llama, mixtral), `custom`260261**Voice/TTS:** `11labs`, `playht`, `azure`, `deepgram`, `lmnt`, `cartesia`, `rime`, `neets`, `custom`262263**Telephony:** `twilio`, `vonage`, `telnyx`, `vapi` (built-in, limited)