Developer API

The API your AI agents use to make and receive phone calls.

Full REST API, MCP server, typed webhooks, SSE events. No SDK required. Bot-native from day one.

90-Second Quickstart Full API Reference →

REST API v2MCP ServerTyped webhooksSSE eventsOpenAPI 3.1

API At a Glance

40+

Endpoints

Webhook events

~90s

Avg provisioning time

$50

Free credit on signup

Base URL

https://api.workforcewave.com/v2/

Quickstart

From zero to deployed agent in 90 seconds.

Three curl commands. A service account, a business URL, and an operation ID is all it takes to provision a fully configured voice agent.

Get an access token

bash

curl -X POST https://api.workforcewave.com/v2/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "sa_xxx",
    "client_secret": "sk_live_xxx",
    "grant_type": "client_credentials"
  }'

# Returns:
# { "access_token": "eyJ...", "expires_in": 3600, "token_type": "Bearer" }

Service account credentials from your dashboard under Settings → API Keys.

Create an agent — Workforce Wave provisions it automatically

bash

curl -X POST https://api.workforcewave.com/v2/agents \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: provision-smile-dental-001" \
  -d '{
    "payload": {
      "name": "My Dental AI",
      "platform": "elevenlabs",
      "business_url": "https://smile-dental.com",
      "template_id": "dental_receptionist"
    }
  }'

# Returns immediately — async operation:
# { "operation_id": "op_abc123", "status": "pending", "estimated_seconds": 90 }

Workforce Wave reads the URL, generates the system prompt and KB, and deploys. The template_id sets the industry vertical.

Poll until active

bash

curl https://api.workforcewave.com/v2/operations/op_abc123 \
  -H "Authorization: Bearer {token}"

# When complete:
# {
#   "status": "active",
#   "agent_id": "agt_xyz789",
#   "phone_number": "+18005551234",
#   "provisioning_time_seconds": 84
# }

Or subscribe to the agent.activated webhook to be notified without polling.

Full API Reference →OpenAPI 3.1 Spec (JSON)

MCP Server

Or use the MCP server.

Add WFW to any MCP-compatible AI assistant with a single command. Claude, Cursor, or any agent using the Model Context Protocol can provision voice agents, retrieve call transcripts, and update agent knowledge bases — all with a single tool call.

The MCP server exposes 14 tools covering the full API surface: agent management, call data retrieval, KB sync, webhook management, and AI-powered improvements. No wrapper code. No HTTP client to configure.

View MCP server documentation →

Install (Claude Code CLI)

bash

claude mcp add workforcewave -- \
  npx @workforcewave/mcp-server \
  --api-key YOUR_KEY

claude_desktop_config.json

{
  "mcpServers": {
    "workforcewave": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@workforcewave/mcp-server",
        "--api-key", "YOUR_KEY"
      ]
    }
  }
}

Available MCP Tools

provision_agent

get_agent

list_agents

update_agent

get_call_transcript

list_calls

get_extractions

sync_knowledge_base

propose_kb_update

list_webhooks

create_webhook

get_operation

scout_research

list_templates

Webhook Events

Everything your agent does, delivered to your endpoint.

Subscribe to typed webhook events per-agent or globally. Every payload is structured JSON — no parsing required, no ambiguous strings.

Event	Description	Example Payload Shape
`agent.activated`	Agent provisioning complete and live on the phone number.	`{ "agent_id": "agt_...", "phone_number": "+1...", "status": "active" }`
`call.completed`	A call ended. Includes duration, caller ID, and disposition.	`{ "call_id": "call_...", "duration_seconds": 142, "disposition": "booked" }`
`call.transcript_ready`	Full turn-by-turn transcript available for retrieval.	`{ "call_id": "call_...", "transcript_url": "https://..." }`
`call.extractions_ready`	Structured data extracted from the call (intent, entities, slots).	`{ "call_id": "call_...", "extractions": { "intent": "book_appointment", ... } }`
`extraction.low_confidence`	An extraction field scored below the configured confidence threshold.	`{ "call_id": "call_...", "field": "insurance_provider", "confidence": 0.42 }`
`kb.synced`	Knowledge base document updated — via automated improvement or manual edit.	`{ "agent_id": "agt_...", "doc_id": "kb_...", "version": 4 }`
`agent.updated`	Agent configuration changed (system prompt version, voice, phone number).	`{ "agent_id": "agt_...", "changed_fields": ["system_prompt_version"] }`

All events include a webhook_id,event_type,created_at, and idempotency_key in the envelope. Retries use exponential backoff with a 5-attempt limit.

API Design

Built for bot consumption.

The API is designed with autonomous systems as the primary consumer. Every pattern is chosen to make bot orchestration predictable and safe.

Idempotency Keys

Safe retries for bots

Every mutating request accepts an Idempotency-Key header. Send the same key twice and you get the same response — no duplicate agents, no double-charges. Essential for retry logic in agentic pipelines.

Idempotency-Key: "provision-acme-dental-2026-04-16"

Async Operations

Provision 50 agents, check back later

Agent provisioning is async by design. POST /v2/agents returns an operation_id immediately. Poll GET /v2/operations/{id} to check status. Provision a hundred agents in parallel and check the results in one batch.

{ "operation_id": "op_xyz", "status": "pending|active|failed" }

Structured Errors

Retryable flag, recovery actions

Every error response includes a retryable boolean and a suggested recovery action. Bot consumers don't need to parse error messages — they read structured fields and act accordingly.

{ "error": { "code": "RATE_LIMITED", "retryable": true, "retry_after": 30 } }

Scoped Tokens

Limit what each bot can do

Service account tokens are scoped to specific capabilities: agents:read, agents:write, calls:read, webhooks:manage. Give each bot or reseller only the permissions it needs — nothing more.

"scopes": ["agents:write", "calls:read"]

API Surface Guide

Which API surface do you need?

Match your integration pattern to the right surface — REST API for programmatic control, MCP for AI orchestrators, webhooks for async pipelines, SSE for real-time streams.

Use Case	API Surface	Notes
Provision a new agent for a customer	REST API — POST /v2/agents	Async operation — poll for completion
AI assistant creates agents on demand	MCP Server	One tool call from Claude, Cursor, or any MCP host
Receive structured call data in real time	Webhook subscriptions	Subscribe per-agent or globally
Stream live call events to a dashboard	SSE Stream — GET /v2/events	Server-Sent Events, no long-poll needed
Query agent or call data from code	REST API — GET endpoints	Paginated, filterable, consistent envelope
Trigger agent logic from a human UI	REST API + Dashboard	All dashboard actions have API equivalents

$50 free API credit on signup. No credit card required.

Start building with the API today.

Sign up, grab your service account credentials, and have a deployed agent in 90 seconds. The free credit covers roughly 300 minutes of voice calls.

Get $50 Free API Credit Read the full docs

Need a custom enterprise plan? Talk to our team →