Build a voice channel in three calls.

Quickstart

Every VoiceKernel object is an API call. Authenticate with a key from Settings → API keys, then create an agent and put it on a line.

1 · Create an agent

# An agent is a prompt, a model, a voice and the actions it may call.
curl http://localhost:8080/v1/agents \
  -H "Authorization: Bearer $VK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Card disputes",
    "systemPrompt": "You are a card disputes specialist for a retail bank. Answer only from the supplied policy documents. If unsure, escalate to a human.",
    "firstMessage": "Thanks for calling - how can I help with your card today?",
    "model": { "provider": "anthropic", "model": "claude-sonnet-5", "temperature": 0.3 },
    "voice": { "provider": "11labs", "voiceId": "matilda" },
    "transcriber": { "provider": "deepgram", "model": "nova-3" }
  }'

2 · Place a call

curl http://localhost:8080/v1/calls \
  -H "Authorization: Bearer $VK_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "to": "+61400000000", "agentId": "asst_…", "metadata": { "ticket": "INC-9912" } }'

3 · Receive the outcome

curl http://localhost:8080/v1/webhook-endpoints \
  -H "Authorization: Bearer $VK_KEY" \
  -d '{ "url": "https://crm.example.com/hooks/voicekernel", "events": ["call.ended"] }'

# The response carries the signing secret, once. Store it.

Authentication & conventions

Pass your key as a bearer token. X-API-Key is also accepted, for gateways that will not forward Authorization.

Authorization: Bearer vk_live_…

Keys are scoped. A key that lacks a scope is refused with 403 and told which scope it needed - it does not silently return an empty list.

Errors

Every failure has the same shape. Quote requestId when reporting a problem.

{
  "error": {
    "type":      "permission_error",
    "code":      "permission_denied",
    "message":   "This API key lacks the \"agents:write\" scope.",
    "requestId": "req_8f21…"
  }
}

Idempotency

Send Idempotency-Key on any POST or PATCH. A replay returns the original response rather than repeating the operation - so a timeout you retry cannot place a second call. Reusing a key with a different body is a 409, because that is a client bug worth surfacing loudly.

Pagination

?limit=&offset=. Responses carry { data, pagination }.

Rate limits

X-RateLimit-Limit, -Remaining and -Reset on every response. A 429 carries Retry-After.

SDKs

TypeScript available

npm install @voicekernel/sdk

import { VoiceKernel } from '@voicekernel/sdk';

const vk = new VoiceKernel({ apiKey: process.env.VK_API_KEY });

const agent = await vk.agents.create({
  name: 'Card disputes',
  systemPrompt: 'You are a card disputes specialist…',
  model: { provider: 'anthropic', model: 'claude-sonnet-5' },
});

// An idempotency key is attached automatically - a retried timeout
// must never place a second call.
await vk.calls.create({ to: '+61400000000', agentId: agent.id });

// Walks every page.
for await (const call of vk.calls.iterate({ status: 'ended' })) { … }

// Anything not wrapped by a typed method.
await vk.provider('GET', '/assistant/abc123');

verifyWebhook() throws rather than returning false - a caller who forgets to check a boolean silently accepts forgeries.

Python not yet available

Go not yet available

Until those ship, generate a client from the OpenAPI document.

Webhooks

Register an endpoint and VoiceKernel posts every event to it, signed, retried with exponential backoff, and individually replayable from the console.

Events

Subscribe to * for everything, or a prefix like call.*.

Verifying a delivery

This is the security-critical half of the integration. Without it, anyone who learns your endpoint URL can forge call events.

X-VoiceKernel-Signature: t=1785668467,v1=9f2c…

const [t, v1] = header.split(',').map(p => p.split('=')[1]);
const expected = crypto
  .createHmac('sha256', process.env.VK_WEBHOOK_SECRET)
  .update(`${t}.${rawBody}`)
  .digest('hex');

// Constant time, and over the RAW body - re-serialising changes key order.
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))) return res.sendStatus(401);

// A valid signature replayed next week is still an attack.
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.sendStatus(401);

API surface

Providers & models

Any agent can move between these without touching its prompt. Generated from the upstream spec, so a value listed here is a value the API will accept - GET /v1/catalog returns the same data at runtime.

Language models 17

Voices 20

Transcribers 14

Actions 26

Upstream operations

97 operations, generated from the upstream OpenAPI document - so this list is what the API accepts, not what someone remembered to write down.

Analytics

Assistants

Board

Calls

Campaigns

Chats

Eval

Files

Insight

Observability/Scorecard

Phone Numbers

Provider Resources

Sessions

Squads

Structured Outputs

Tools

Operations marked shared-key restricted aggregate an entire upstream account. On the shared platform key that would span tenants, so they are refused and answered from VoiceKernel's own org-scoped data instead. Adding your own provider key enables them.