Workspace API

Keys

An owner creates a key in the console under Settings → API and webhooks, and can turn the same right on for a manager. The key is shown once; only a fingerprint of it is kept. Revoke a key there and it stops working straight away. A key keeps only the rights of the person who made it: if they are removed, suspended or lose access to a page, the key loses it too.

Calling the API

Send the key as a bearer token, on your workspace's own address. A key from another workspace is refused.

curl https://your-workspace-address/api/workspace/v1/calls?limit=100 \
  -H "Authorization: Bearer ixw_..."

Read and write keys

Each key is Read, Write or Read and write, picked when it is made. A read key looks things up and cannot change anything. A write key makes changes and cannot read lists. Read and write does both, and is what a new key gets unless you pick another. Keys made before scopes existed are read keys. Making a write key needs someone who can change things in the console.

Endpoints

These three lists need a read key.

{
  "data": [
    {
      "id": "6f1c…",
      "created_at": "2026-11-03T14:02:11.482913+00:00",
      "ended_at": "2026-11-03T14:09:40.112004+00:00",
      "status": "completed",
      "campaign_id": "a2d0…",
      "duration_seconds": 449,
      "billable": true,
      "billable_seconds": 449,
      "disposition": "Sold",
      "ended_reason": "caller_hangup",
      "caller_state": "TX",
      "answered": true,
      "sold": true
    }
  ],
  "next_cursor": "WyIyMDI2LTEx…"
}

Tools: everything the AI connector can do

Every tool the AI connector has is also an endpoint: POST /api/workspace/v1/tools/TOOL_NAME, with the tool's input as a JSON body. GET /api/workspace/v1/tools lists the tools your key can call right now, each with its scope and input schema. A read tool needs a read key and a write tool a write key; the wrong one gets 403 with code scope.

Most changes are checked twice, as in the connector. Send one without an Idempotency-Key and you get a preview and a confirm_token; nothing changes until you send the same body again with confirm: true and that token. leave_call_feedback is the exception: it saves the review in the first request, with or without a key. Send an Idempotency-Key header (any unique value) and the change is applied in that one request. Retrying with the same key within 24 hours returns the first answer and never applies the change twice; the same key with a different body gets 422.

A tool that moves money also needs the Idempotency-Key and a key the owner made.

curl https://your-workspace-address/api/workspace/v1/tools/get_call \
  -H "Authorization: Bearer ixw_..." \
  -H "Content-Type: application/json" \
  -d '{"id": "6f1c..."}'

curl https://your-workspace-address/api/workspace/v1/tools/pause_campaign \
  -H "Authorization: Bearer ixw_..." \
  -H "Idempotency-Key: 2b7c9a1e-pause-1" \
  -H "Content-Type: application/json" \
  -d '{"campaign_id": "a2d0..."}'

Paging and filters

Lists return up to 100 rows (limit=1 to 500) and a next_cursor. Pass it back as cursor= to get the next page; it is null on the last page. Calls and stats take from= and to= (ISO times) and campaign_id=.

Errors

Every error is JSON: error.code, error.message and error.hint, plus error.reason when a change was refused. 400 means a bad value; 401 means no key, an unknown key or a revoked one; 403 means the key's scope does not allow it, the key belongs to another workspace, or its maker can no longer do this; 404 means no such tool or record; 409 means something changed meanwhile, or the same Idempotency-Key is still running; 422 means the change was refused (nothing changed) or the Idempotency-Key was used for another request; 429 means more than 60 requests a minute (wait for Retry-After).

Webhooks

An owner adds up to 5 https addresses in the console under Settings → API and webhooks and picks the events: call.completed when a call ends, call.converted when a call is marked sold. Each delivery is a POST with JSON: id, event, created_at and data.call (the same fields as a call above; call.converted adds sold_at). The Send test button sends a webhook.test event.

Every delivery carries X-Webhook-Signature: t=TIMESTAMP,v1=HEX. HEX is the HMAC-SHA256, with the endpoint's secret, of the timestamp, a dot and the raw body. The secret is shown once when you add the address. Refuse a timestamp more than five minutes off.

// Node: check X-Webhook-Signature over the raw body before you trust it.
const crypto = require("node:crypto");
function verifyWebhook(header, rawBody, secret) {
  const parts = Object.fromEntries(String(header ?? "").split(",").map((p) => p.trim().split("=", 2)));
  const t = parts.t, v1 = parts.v1;
  if (!/^\d{1,12}$/.test(t ?? "") || !/^[0-9a-f]{64}$/.test(v1 ?? "")) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(v1, "hex"), Buffer.from(expected, "hex"));
}

Answer with any 2xx within 10 seconds. Anything else is tried again after 1, 5, 30, 120 and 360 minutes, then marked failed. The id is the same on every try, so drop repeats by id. The console shows each endpoint's recent deliveries and their result. Addresses on private networks are refused.

What it never does

A key never does more than the person who made it can do in the AI connector, and never reaches another workspace. The calls, campaigns and stats lists never return prices, payouts, who sent a call, the caller's number or recordings.