Skip to main content

API reference

The VoisX Cloud Platform API lets you run your agents from your own website or app. You can open voice sessions with an agent from your own client, send session events, and trigger workflows from other systems.

You build and configure agents, skills, tools and channels in the console at app.voisx.ai. You can also do this from your own server with the management API.

What you can call​

AreaWhat it doesAuthentication
Widget configRead your project's widget settings and the agents it can talk to.Project API key
SessionsOpen a voice session with an agent over one WebSocket.Project API key
ToolsHow an agent's tools run during a session. They run on the VoisX server.None
Session eventsAdd client-side events, such as errors, to a session.Project API key
Workflow webhooksStart a workflow run from another system.Secret webhook URL
Management APICreate and change agents, skills, tools and channels, and upload files.Project API key with management permissions
EvalsTest agents with eval suites, read results and set a publish gate.Project member access

Hosts and data regions​

Your project lives in one data region. Send requests to the host for that region.

RegionHost
India (default)https://in.api.voisx.ai
UAEhttps://uae.api.voisx.ai

The API has two path prefixes on each host:

PrefixUsed byExample
/widget/v1Widget config, sessions and session eventshttps://in.api.voisx.ai/widget/v1/config
/apiWorkflow webhooks and the management APIhttps://in.api.voisx.ai/api/webhooks/{token}

The examples in this reference use the India host. If your project is in the UAE region, replace in.api.voisx.ai with uae.api.voisx.ai.

tip

Agents and workflows are stored in your project's region. A request sent to the other region's host returns 404 for them. If you get an unexpected 404, check the region first.

Versioning​

The widget API is versioned in its path. The current version is v1. New optional fields can be added to v1 responses at any time, so ignore fields you do not recognise.

Requests and responses​

  • Send request bodies as JSON with Content-Type: application/json.
  • Voice sessions use a WebSocket (wss://) on the same host. See Sessions.
  • Responses are JSON.
  • Send timestamps in requests as ISO 8601, for example 2026-10-05T09:14:02Z. Expiry times in responses are Unix timestamps in seconds.
  • IDs for agents and projects are integers. Session IDs are strings.

Project scoping​

Each project API key belongs to one project. The widget API works out the project from the key, so you never put a project ID in its paths. Management API paths do include the project ID, and it must be the key's own project. A key can only reach agents in its own project, and you can limit it further to specific agents and website domains. See Authentication.

Next steps​

Was this page helpful?
On this page
Try it in the consoleBuild an agent and test it in the Playground.Open console →