REST API

Place outbound calls, read call records, and list your workspaces. Plain HTTP, JSON in and out.

Base URL

https://voylo.ai/v1. The interactive Swagger UI is at /docs.

Authentication

Programmatic requests use an API key as a bearer token. The key is already bound to a workspace at creation time, so it scopes the request automatically — no X-Workspace-Id header needed. Create keys at API keys — the raw key is shown once.

Headers (every request)

Authorization: Bearer vlx_live_abc…

The console uses session cookies + an X-Workspace-Id header to support users with multiple workspaces. API keys are simpler: one key, one workspace, no header.

Place an outbound call

POST /v1/calls— rings a destination from one of your workspace numbers and runs your chosen application's VoyloML on answer. Returns immediately with { publicId, status: "dialing" }; the real outcome arrives via webhooks (call.placed immediately, then call.completed / call.failed when the call ends). The Idempotency-Key header is honoured — replaying the same request returns the original call instead of dialling twice.

POST /v1/calls

curl -X POST https://voylo.ai/v1/calls \

-H "Authorization: Bearer $VOYLO_API_KEY" \

-H "Idempotency-Key: order-1234" \

-H "Content-Type: application/json" \

-d '{"from":"+2004446","to":"+966512345678","applicationId":"<uuid>","variables":{"order_id":"ORD-1234"}}'

Custom variables are substituted as {{key}}in the application's static VoyloML AND ride as var_<key> on any action-URL POSTs. See the VoyloML reference.

Get a single call

GET /v1/calls/{publicId}— the full record once it's ended (or the pending shape while it's still in progress). Use the publicId returned by POST.

GET /v1/calls/cl_…

curl https://voylo.ai/v1/calls/cl_a1b2c3d4e5f6 \

-H "Authorization: Bearer $VOYLO_API_KEY"

Pending outbound calls return { "pending": true, "pendingStatus": "dialing" } until the call ends; completed calls return the CDR shape including outcome, durationS, and destinationKind.

List calls

GET /v1/calls — most recent first. Useful for a quick audit or to build a CRM-side activity feed. The response is an array of call records; paginate by passing before= a publicId.

GET /v1/calls

curl https://voylo.ai/v1/calls \

-H "Authorization: Bearer $VOYLO_API_KEY"

List your workspaces

GET /v1/workspaces — the workspace bound to the API key. Returns a one-element array today (one key, one workspace) but the array shape is preserved so multi-workspace API keys, when we support them, are a non-breaking addition.

GET /v1/workspaces

curl https://voylo.ai/v1/workspaces \

-H "Authorization: Bearer $VOYLO_API_KEY"

Other resources exist in the API (numbers, trunks, applications, webhooks, billing, rentals) and drive the console you're already using. They're intentionally not yet stable for external use — we'll publish them once their shape is locked. For now, stick to the four endpoints above; everything else is exercised through the web console.

Errors

JSON body with statusCode, error, and message; validation failures (400) include field details. Full breakdown in Errors.

← Previous

VoyloML reference

Error codes