Developer overview: how code talks to Voxido
This section is for developers. It explains every way your code can connect to Voxido today, which credential each one uses, and the limits.
Pick your path
| You want to… | Direction | Use | Credential |
|---|---|---|---|
| Push a contact (form fill, new booking, new order) into Voxido | Your system → Voxido | Inbound API | API key with inbound:write, in X-API-Key |
| Start an agent for one contact (call or message them now) | Your system → Voxido | Webhook trigger on the agent | HMAC-SHA256 signature in X-Voxido-Signature |
| Let an agent look something up or book something in your system during a chat or call | Voxido → your system | Outbound Custom API | Your system's own key, stored on the Custom API |
| Check your API key and signing code | Your system → Voxido | POST /api-keys/test-signature | API key in X-API-Key |
There is no general REST API (for listing contacts, sending messages or placing calls) that accepts API keys. Those actions are available in the app, to agents, and through the routes above.
Base URL
https://api.voxido.ai/api/v1Every path in this reference is relative to it. For example, the inbound route is https://api.voxido.ai/api/v1/inbound/{endpoint_id}.
Server to server only
Call these routes from your backend, Zapier, n8n or a similar tool. Browsers block them: the headers they need (X-API-Key, X-Voxido-Signature) aren't allowed in cross-site browser requests. Never put a key or secret in front-end code.
Rate limits
Each limit is per minute, per caller, per path.
| Route | Limit per minute |
|---|---|
POST /inbound/{endpoint_id} | 120 |
POST /agents-v4/{agent_id}/webhook | 30 |
POST /api-keys/test-signature | 30 |
Over the limit, you get 429 with {"detail": "Rate limit exceeded. Please try again later."} and a Retry-After header. Wait that many seconds, then retry.
Does Voxido sign requests it sends to you?
No. When an agent calls your API through an outbound Custom API, Voxido sends the authentication you set on that Custom API (an API key header, a bearer token or basic auth). Check that credential on your side. See Custom API.
Reference pages
- REST API and authentication — API keys, the inbound route and the key test route.
- Webhook triggers: payload and HMAC signing — start an agent from your code.