Agents API

List Agents

Retrieve a list of all agents for your organization.

GET /api/public/v1/agents

Response

The response is an array of agents, when you fetch all agents.

[
	{
		"id": "<your_agent_id>",
		"name": "<your_agent_name>",
		"gender": "<your_agent_gender>",
		"description": "<your_agent_description>",
		"script": "<your_agent_script>",
		"voiceId": ["<your_agent_voice_id>"],
		"voiceUrl": "<your_agent_voice_url>",
		"createdAt": "<your_agent_created_at>",
		"updatedAt": "<your_agent_updated_at>"
	}
]

Create Agent

Create a new AI agent.

POST /api/public/v1/agents

Request Body

{
	"name": "<your_agent_name>",
	"gender": "<your_agent_gender> MALE or FEMALE",
	"description": "<your_agent_description>",
	"script": "<your_agent_script>",
	"voiceId": ["<premium_voice_id>", "<basic_voice_id>"],
	"voiceUrl": "<your_agent_voice_url>"
}

Response

The response is the agent details, when you create a new agent.

{
	"id": "<your_agent_id>",
	"name": "<your_agent_name>",
	"gender": "<your_agent_gender>",
	"description": "<your_agent_description>",
	"script": "<your_agent_script>",
	"voiceId": ["<premium_voice_id>", "<basic_voice_id>"],
	"voiceUrl": "<your_agent_voice_url>",
	"createdAt": "<your_agent_created_at>",
	"updatedAt": "<your_agent_updated_at>"
}

Get Agent

Retrieve details of a specific agent.

GET /api/public/v1/agents/{agent_id}

Response

The response is the agent details, when you fetch a specific agent.

{
	"id": "<your_agent_id>",
	"name": "<your_agent_name>",
	"gender": "<your_agent_gender>",
	"description": "<your_agent_description>",
	"script": "<your_agent_script>",
	"voiceId": ["<premium_voice_id>", "<basic_voice_id>"],
	"voiceUrl": "<your_agent_voice_url>",
	"createdAt": "<your_agent_created_at>",
	"updatedAt": "<your_agent_updated_at>"
}

Parameters

Pass the agent id in the url while fetching a specific agent.

Parameter	Type	Description
agent_id	string	The ID of the agent to retrieve

Update Agent

Update an existing agent's details.

PUT /api/public/v1/agents/{agent_id}

Request Body

{
	"name": "Updated Name",
	"gender": "FEMALE",
	"description": "Updated Description",
	"script": "Updated Script",
	"voiceId": ["<premium_voice_id>", "<basic_voice_id>"],
	"voiceUrl": "https://example.com/new_voice.mp3"
}

Response

The response is the agent details, when you update an agent.

{
	"id": "<your_agent_id>",
	"name": "<your_agent_name>",
	"gender": "<your_agent_gender>",
	"description": "<your_agent_description>",
	"script": "<your_agent_script>",
	"voiceId": ["<premium_voice_id>", "<basic_voice_id>"],
	"voiceUrl": "<your_agent_voice_url>",
	"createdAt": "<your_agent_created_at>",
	"updatedAt": "<your_agent_updated_at>"
}

Parameters

Pass the agent id in the url while updating the agent.

Parameter	Type	Description
agent_id	string	The ID of the agent to delete

Delete Agent

Delete an existing agent.

DELETE /api/public/v1/agents/{agent_id}

Response

The response is a message, when you delete an agent.

{
	"message": "Agent deleted successfully"
}

Parameters

Pass the agent id in the url while deleting the agent.

Parameter	Type	Description
agent_id	string	The ID of the agent to delete

Agent Schema

The agent schema is the schema of the agent.

Field	Type	Mandatory	Description
id	string	Generated	The ID of the agent
name	string	Required	The name of the agent
gender	string	Required	The gender of the agent, MALE or FEMALE
description	string	Required	The description of the agent. Description is used to describe the agent's personality
script	string	Required	The script of the agent. The following script is used in conversation with the customer
voiceId	string[]	Required	Array of voice ids. Convention: [premiumVoiceId, basicVoiceId]
voiceUrl	string	Required	The voice url of the agent

Validation Rules

Name must be a string
Gender must be MALE or FEMALE
Description must be a string
Script must be a string
VoiceId must be an array of strings (premium first, basic second)
VoiceUrl must be a string

Error Responses

Status Code	Description
400	Bad Request - Invalid input parameters
401	Unauthorized - Invalid or missing API key
404	Not Found - Agent not found
500	Internal Server Error

Security

All endpoints require authentication
Agents are organization-specific
Access is restricted to authorized users only
API keys must have appropriate permissions
Each agent is associated with a specific organization

On this page