Quickstart

You'll need a Voxy workspace and an API key. The whole loop — create a key, fire a call, install the SDK — takes about five minutes. Before you start, skim Authentication to understand the voxy_sk_* prefix and scope model.

1 · Create an API key

Sign in to your workspace and head to Settings → API keys → New key. Pick a scope set that matches your integration — for a first outbound call, start with calls:write and contacts:read.

The full voxy_sk_live_* secret is shown exactly once. Drop it into your secret manager immediately — Voxy does not store the plaintext.

.env.local

# .env.local — never commit this file.
VOXY_API_KEY=voxy_sk_live_xxxxxxxxxxxxx
VOXY_WORKSPACE_ID=ws_01HXYZ4P8K2N3M9TQRSVWXY

Keep the workspace id handy too — every endpoint is scoped to /v1/workspaces/{id}/….

2 · Place your first call with curl

Substitute {workspaceId}, the agent id, and the dialed numbers, then run:

curl

# Substitute {workspaceId}, the agent id, and the dialed numbers.
curl -X POST https://voxyhq.com/v1/workspaces/{workspaceId}/calls/originate-manual \
  -H "Authorization: Bearer voxy_sk_live_xxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agt_01HXYZ",
    "to":      "+15551234567",
    "from":    "+15557654321"
  }'

A 202 Accepted means the call is queued — the agent will dial within a few seconds.

response

HTTP/1.1 202 Accepted
Content-Type: application/json
RateLimit-Limit:     600
RateLimit-Remaining: 599

{
  "success": true,
  "data": {
    "id": "call_01HXYZ4P8K2N3M9TQRSVWXY",
    "status": "queued",
    "agentId": "agt_01HXYZ",
    "to": "+15551234567",
    "from": "+15557654321",
    "createdAt": "2026-06-09T12:34:56.000Z"
  }
}

The Idempotency-Key header is what makes this safe to retry. If the request times out, replay the same payload with the same key — Voxy returns the cached 202 instead of dialing twice. See Idempotency for the full contract.

3 · Install the TypeScript SDK

The official SDK wraps the REST surface with typed helpers, an auto-injected Authorization header, and built-in idempotency key plumbing.

install

pnpm add @voxy/sdk
# or: npm install @voxy/sdk
# or: yarn add @voxy/sdk

Then place the same call:

first-call.ts

import { VoxyClient } from '@voxy/sdk';
import { randomUUID } from 'node:crypto';

const voxy = new VoxyClient({
  apiKey:      process.env.VOXY_API_KEY!,
  workspaceId: process.env.VOXY_WORKSPACE_ID!, // 'ws_01HXYZ…'
});

const call = await voxy.calls.originateManual(
  {
    agentId: 'agt_01HXYZ',
    to:      '+15551234567',
    from:    '+15557654321',
  },
  { idempotencyKey: randomUUID() },
);

console.log('call queued:', call.id, call.status);

The SDK throws VoxyApiError with a typed code + details on any 4xx/5xx — branch on err.code, never on the message text (see Errors).

Next steps

Authentication — scopes, key rotation, and how to keep secrets out of repos.
Idempotency — safe retries on every write.
Rate limits — theRateLimit-* headers, the 429 retry-after contract.
Webhooks — react to call.summary_ready, lead.created, and more.
Errors — every code the API can emit, grouped by domain.