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

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`userId`requireddata[].userId	string (uuid)	-
`name`requireddata[].name	string	-
`voiceId`requireddata[].voiceId	string \| null	-
`voiceProvider`requireddata[].voiceProvider	string	-
`language`requireddata[].language	string	-
`firstMessage`requireddata[].firstMessage	string \| null	What the agent says when the call is answered
`systemPrompt`requireddata[].systemPrompt	string	The script and instructions the agent follows
`model`requireddata[].model	string	-
`guardrails`requireddata[].guardrails	string \| null	-
`tools`requireddata[].tools	string[]	-
`maxCallSeconds`requireddata[].maxCallSeconds	integer	-
`enabled`requireddata[].enabled	boolean	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata[].updatedAt	string (date-time)	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)

Field	Type	Description
`name`required	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`required	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

Field	Type	Description
`data`required	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

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string	-
`name`requireddata[].name	string	-
`description`requireddata[].description	string	-
`gender`requireddata[].gender	string	-
`language`requireddata[].language	string	-
`is_pro`requireddata[].is_pro	boolean	-

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)

Field	Type	Description
`voiceId`required	string	-max 120 chars
`text`required	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)

Field	Type	Description
`description`required	string	-max 2000 chars

Response 200

Field	Type	Description
`data`required	object	-
`name`requireddata.name	string	-
`firstMessage`requireddata.firstMessage	string	-
`systemPrompt`requireddata.systemPrompt	string	-
`guardrails`requireddata.guardrails	string	-
`suggestedTools`requireddata.suggestedTools	string[]	-

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

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

Field	Type	Description
`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

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-

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

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

Field	Type	Description
`history`	object[]	-
`role`requiredhistory[].role	string	-One of `user`, `assistant`
`content`requiredhistory[].content	string	-max 4000 chars
`message`required	string	-max 2000 chars

Response 200

Field	Type	Description
`data`required	object	-
`reply`requireddata.reply	string	What the agent would say
`action`requireddata.action	string	-One of `continue`, `end`, `transfer`
`captured`data.captured	object	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.