API reference

AI voice agents

Build, preview and attach AI voice agents to campaigns.

9 operationsBase URL https://packetexchange.io/api/v1Postman collection

BrowseAI voice agents

List your AI voice agents

GET/api/v1/ai-agents

Access: API key. Scoped keys need dialer:write.
Rate limit: 100 requests per second (the default)

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
userIdrequired
string (uuid) · data[].userId
namerequired
string · data[].name
voiceIdrequired
string | null · data[].voiceId
voiceProviderrequired
string · data[].voiceProvider
languagerequired
string · data[].language
firstMessagerequired
string | null · data[].firstMessage
What the agent says when the call is answered
systemPromptrequired
string · data[].systemPrompt
The script and instructions the agent follows
modelrequired
string · data[].model
guardrailsrequired
string | null · data[].guardrails
toolsrequired
string[] · data[].tools
maxCallSecondsrequired
integer · data[].maxCallSeconds
enabledrequired
boolean · data[].enabled
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data[].updatedAt
ISO-8601 timestamp (UTC)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Create an AI voice agent

POST/api/v1/ai-agents

Access: API key. Scoped keys need dialer:write.
Rate limit: 100 requests per second (the default)

Request body (application/json)

FieldDescription

namerequired
string
max 120 chars
voiceId
string | null
max 120 chars
voiceProvider
string
max 40 chars
language
string
max 12 chars
firstMessage
string | null
max 500 chars
systemPromptrequired
string
max 8000 chars
model
string
max 60 chars
guardrails
string | null
max 4000 chars
tools
string[]
maxCallSeconds
integer
1 to 3600
enabled
boolean

Response 201

FieldDescription

datarequired
object
Same fields as AiAgent, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/ai-agents" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme",
  "systemPrompt": "<systemPrompt>"
}'

Run it here with a test key.

List the voices an agent can speak with

GET/api/v1/ai-agents/voices

Access: API key. Scoped keys need dialer:write.
Rate limit: 100 requests per second (the default)

A trimmed list (about 60), English non-premium voices first.

Response 200

FieldDescription

datarequired
object[]
idrequired
string · data[].id
namerequired
string · data[].name
descriptionrequired
string · data[].description
genderrequired
string · data[].gender
languagerequired
string · data[].language
is_prorequired
boolean · data[].is_pro

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Hear a voice speak a short line

POST/api/v1/ai-agents/voices/preview

Access: API key. Scoped keys need dialer:write.
Rate limit: 100 requests per second (the default)

Returns MP3 audio of text (up to 300 characters) in the chosen voice.

Request body (application/json)

FieldDescription

voiceIdrequired
string
max 120 chars
textrequired
string
max 300 chars

Response 200 (audio/mpeg)

MP3 audio of the line.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/ai-agents/voices/preview" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "voiceId": "<voiceId>",
  "text": "Hello from Acme"
}'

Run it here with a test key.

Draft an agent from a plain-English description

POST/api/v1/ai-agents/draft

Access: API key. Scoped keys need dialer:write.
Rate limit: 20 requests per minute

Turns a description such as "call leads and book demos" into a name, opening line, script, guardrails and suggested tools. Nothing is saved; pass the result to POST /ai-agents.

Request body (application/json)

FieldDescription

descriptionrequired
string
max 2000 chars

Response 200

FieldDescription

datarequired
object
namerequired
string · data.name
firstMessagerequired
string · data.firstMessage
systemPromptrequired
string · data.systemPrompt
guardrailsrequired
string · data.guardrails
suggestedToolsrequired
string[] · data.suggestedTools

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/ai-agents/draft" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Example"
}'

Run it here with a test key.

Get an AI voice agent

GET/api/v1/ai-agents/{id}

Access: API key. Scoped keys need dialer:write.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object
Same fields as AiAgent, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Update an AI voice agent

PATCH/api/v1/ai-agents/{id}

Access: API key. Scoped keys need dialer:write.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string (uuid)

Request body (application/json)

FieldDescription

name
string
max 120 chars
voiceId
string | null
max 120 chars
voiceProvider
string
max 40 chars
language
string
max 12 chars
firstMessage
string | null
max 500 chars
systemPrompt
string
max 8000 chars
model
string
max 60 chars
guardrails
string | null
max 4000 chars
tools
string[]
maxCallSeconds
integer
1 to 3600
enabled
boolean

Response 200

FieldDescription

datarequired
object
Same fields as AiAgent, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X PATCH "https://packetexchange.io/api/v1/ai-agents/<id>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme",
  "voiceId": "<voiceId>"
}'

Run it here with a test key.

Delete an AI voice agent

DELETE/api/v1/ai-agents/{id}

Access: API key. Scoped keys need dialer:write.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Simulate one conversation turn with an agent

POST/api/v1/ai-agents/{id}/simulate

Access: API key. Scoped keys need dialer:write.
Rate limit: 20 requests per minute

Send what the callee said (message) plus the prior turns (history); the agent answers with its spoken reply and what it would do next. No call is placed and nothing is billed.

Parameters

idrequired
path · string (uuid)

Request body (application/json)

FieldDescription

history
object[]
rolerequired
string · history[].role
One of user, assistant
contentrequired
string · history[].content
max 4000 chars
messagerequired
string
max 2000 chars

Response 200

FieldDescription

datarequired
object
replyrequired
string · data.reply
What the agent would say
actionrequired
string · data.action
One of continue, end, transfer
captured
object · data.captured
Structured details captured this turn (name, email, intent...)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/ai-agents/<id>/simulate" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "Hello from Acme"
}'

Run it here with a test key.