API Reference

v1 · Stable since 2026-05

REST + JSON, hosted at https://app.viciagent.com/api/v1/. Authenticate by sending the API key (mint one here) as a Bearer token:

curl https://app.viciagent.com/api/v1/calls \
  -H "Authorization: Bearer va_<your_key>"

Rate limit: 300 requests / minute per key. Contact support for higher.

Endpoints

Calls

GET /v1/calls — list calls. Query: agentId, contactId, status, hasRecording, dateFrom/To, limit/offset.
GET /v1/calls/:id — full call detail incl. transcript + cost line items.
GET /v1/calls/:id/recording.wav — streamed audio. Signed-URL gated.

Agents

GET /v1/agents · POST /v1/agents · PATCH /v1/agents/:id · DELETE /v1/agents/:id
PATCH body accepts name, soul, mission, playbook, knowledgeBase, firstMessage, voice and transfer settings.

Phone numbers

GET /v1/phone-numbers · PATCH /v1/phone-numbers/:id { agentId } to assign inbound routing.
GET /v1/phone-numbers/inventory/search?country=US&areaCode=415 · POST to buy from inventory.

Contacts

GET /v1/contacts · POST /v1/contact-lists with a CSV body to import in bulk.

Webhooks

Configure outbound HTTP callbacks at /settings/webhooks. Signed with HMAC-SHA256:

X-VICIagent-Event: call.completed
X-VICIagent-Delivery: <uuid>
X-VICIagent-Timestamp: 1715616000
X-VICIagent-Signature: t=1715616000,v1=<hex_hmac>

Verify by recomputing HMAC-SHA256(secret, body) and matching the v1= value. Event types include call.queued, call.connected, call.completed, call.failed, campaign.started, campaign.compliance_paused.

Errors

JSON error shape:

{
  "error": "rate_limited",
  "message": "too many requests — wait 12s",
  "details": { "retryAfterSec": 12 }
}

error is a stable machine code; message is human-readable.

Machine-readable spec

OpenAPI 3.1 JSON: app.viciagent.com/api/v1/openapi.json