Try it uses test keys only. Requests go straight from your browser to https://voice-api.relationsai.com/v1 with a rai_test_ key, which never places a real call. It works once the API is enabled for your workspace (private preview: support@relationsai.com). Your key stays in this tab's memory; live keys are refused.

Agents

Download schema

AI voice agents. Agents are created, configured and published in the console; the API reads them and tells you whether one is ready to place calls. Agent editing through the API is planned.

List agents

GET

https://voice-api.relationsai.com/v1

/agents

Bearer (rai_test_... or rai_live_...)

Lists the workspace's agents, newest first. Agents are created, configured and published in the console; the API reads them. Deleted agents are not listed.

published is checked live for each page, so it can be null when that check is not available at that moment. Use the readiness endpoint before placing calls with an agent.

GET /v1/agents · Operation ID: listAgents

List agents › query Parameters

limit

integer · min: 1 · max: 100

Maximum number of objects to return, from 1 to 100. Defaults to 25.

Default: 25

cursor

string · minLength: 1 · maxLength: 512

The next_cursor of the previous page. Send it with exactly the same filters as the request that returned it; a changed filter set is 400 invalid_cursor.

List agents › Responses

A page of agents.

A page of agents, newest first.

AgentList

object

string · const · required

Always list.

Const value: list

has_more

boolean · required

True when more objects exist after this page.

next_cursor

string | null · required

Pass as cursor (with the same filters) to fetch the next page. Null on the last page.

Agent[] · required

Agents on this page.

GET/agents

curl -X GET https://voice-api.relationsai.com/v1/agents \
     -H "Authorization: Bearer <token>"

Example Responses

{
  "object": "list",
  "data": [
    {
      "id": "agent_3hT9kQ2mVx7RbN4pLc8Wz1",
      "object": "agent",
      "livemode": false,
      "name": "Loan renewal reminder",
      "description": "Reminds customers that their loan is due for renewal and books a callback.",
      "status": "active",
      "published": true,
      "published_version": 4,
      "is_default": true,
      "sample": false,
      "created_at": "2026-09-02T10:12:44.000Z",
      "updated_at": "2026-10-18T14:03:10.000Z"
    },
    {
      "id": "agent_1ZltiWzxrXmMprGD6q63",
      "object": "agent",
      "livemode": false,
      "name": "Sample agent",
      "description": "A built-in agent for trying the API in test mode.",
      "status": "active",
      "published": true,
      "published_version": 1,
      "is_default": false,
      "sample": true,
      "created_at": "2026-10-21T00:00:00.000Z",
      "updated_at": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

json

application/json

Retrieve an agent

GET

https://voice-api.relationsai.com/v1

/agents/{agent_id}

Bearer (rai_test_... or rai_live_...)

Returns one agent. An agent that was deleted, belongs to another workspace, or is the test-mode Sample agent read with a live key is 404 resource_not_found.

GET /v1/agents/{agent_id} · Operation ID: getAgent

Retrieve an agent › path Parameters

agent_id

string · pattern: ^agent_[A-Za-z0-9_-]… · required

The agent id (agent_...).

Retrieve an agent › Responses

The agent.

An AI voice agent: what callers hear and how the conversation goes. Agents are created, configured, published and switched on in the console. A call uses the agent's published version.

Agent

id

string · pattern: ^agent_[A-Za-z0-9_-]… · required

Agent id (agent_...).

object

string · const · required

Always agent.

Const value: agent

livemode

boolean · required

Mode of the key that read it. Agents are shared configuration, readable in both modes.

name

string · required

Agent name.

description

string | null · required

What the agent is for, as written in the console. Null when not set.

status

string · enum · required

Whether the agent is switched on in the console. active agents can place calls; paused and draft agents cannot. Open enum: unknown values mean the agent cannot be assumed callable.

Enum values:

active

paused

draft

unknown

published

boolean | null · required

True when the agent has a published version that calls use. Null when the publication state could not be read right now; use the readiness endpoint for a definite answer.

published_version

integer | null · min: 1 · required

Number of the published version, when known.

is_default

boolean · required

True for the workspace's default agent.

sample

boolean · required

True only for the built-in Sample agent that exists in test mode.

created_at

string · date-time · required

When the agent was created.

updated_at

string | null · date-time · required

When the agent's configuration last changed, when known.

Check whether an agent can place calls

GET

https://voice-api.relationsai.com/v1

/agents/{agent_id}/readiness

Bearer (rai_test_... or rai_live_...)

Checks, right now, everything about the agent and the workspace that would stop a call being placed, and returns every problem found (not just the first). An agent is ready when it is switched on, fully set up and published, has an outbound phone number, and the workspace has calling set up, an active account, spend headroom and enough balance.

Readiness does not check per-destination rules (the do-not-call list, consent, calling hours and the per-number daily limit); those are applied to each call. A ready agent can therefore still be refused for a particular number, and readiness can change at any time.

GET /v1/agents/{agent_id}/readiness · Operation ID: getAgentReadiness

Check whether an agent can place calls › path Parameters

agent_id

string · pattern: ^agent_[A-Za-z0-9_-]… · required

The agent id (agent_...).

Check whether an agent can place calls › Responses

The readiness result.

Whether an agent can place calls right now, and every reason it cannot. This is a point-in-time check of the agent and the workspace. Per-destination rules (do-not-call list, consent, calling hours, the per-number daily limit) are checked when each call is placed and are not part of readiness.

AgentReadiness

object

string · const · required

Always agent_readiness.

Const value: agent_readiness

livemode

boolean · required

Mode of the key that asked.

agent_id

string · required

The agent checked.

ready

boolean · required

True when reasons is empty.

AgentReadinessReason[] · required

Every reason the agent cannot place calls. Empty when ready.

checked_at

string · date-time · required

When the check ran.

Workspace Phone numbers