vapi

name	vapi
description	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.
allowed-tools	Bash, Read, Grep, Glob, WebFetch

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

1. Scripts use grep-based key loading — not source .env (avoids side effects from other env vars)
2. Always use the Private Key ($VAPI_PRIVATE_API_KEY) — public key can list but not get/mutate
3. 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.
4. Always GET before PATCH — fetch the current assistant config first, then merge your changes into the full object before sending the update
5. Confirm destructive operations (delete) before executing
6. Validate IDs look like UUIDs before making requests
7. Use list-summary for quick overviews, list for full JSON
8. Never expose the API key in output or logs
9. 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)