API Reference
Agents API
Create, retrieve, update, and delete AI agents programmatically.
Agents are the AI personalities that handle conversations on your channels. Each agent has a name, instructions (system prompt), and can be deployed across multiple channels.
đ¤ Create custom agents
Build specialized AI agents for sales, support, or scheduling via API.
đ Sync with your CRM
Automatically update agent instructions based on your CRM data.
đ Monitor deployments
Track which agents are active and their version history.
Available Endpoints
/api/v1/agentsâ List all agents/api/v1/agentsâ Create an agent/api/v1/agents/:idâ Get an agent/api/v1/agents/:idâ Update an agent/api/v1/agents/:idâ Delete an agentList Agents
/api/v1/agentsRetrieves a paginated list of all agents in your workspace.
Query Parameters
Parameters
| Name | Type | Description |
|---|---|---|
limit | integer | Number of agents to return (1-100, default: 20) |
offset | integer | Number of agents to skip (default: 0) |
Example Request
curl -X GET "https://dev.nutalk.ai/v1/agents?limit=10" \ -H "Authorization: Bearer YOUR_API_KEY"Response
{
"success": true,
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Sales Agent",
"description": "Handles inbound sales inquiries",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-20T14:45:00Z",
"deployed_version": {
"id": "v-abc123",
"version_label": "v1.2"
}
}
],
"pagination": {
"total": 5,
"limit": 10,
"offset": 0,
"has_more": false
}
}Create Agent
/api/v1/agentsCreates a new AI agent with the specified name and instructions.
Request Body
Parameters
| Name | Type | Description |
|---|---|---|
nameRequired | string | Display name for the agent (1-100 characters) |
description | string | Brief description of the agent's purpose (max 500 characters) |
instructionsRequired | string | System prompt that defines the agent's behavior (max 50,000 characters) |
Example Request
curl -X POST "https://dev.nutalk.ai/v1/agents" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Support Agent", "description": "Handles customer support inquiries", "instructions": "You are a helpful customer support agent for Acme Corp..."}'Response
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Support Agent",
"description": "Handles customer support inquiries",
"created_at": "2024-01-25T09:00:00Z",
"updated_at": "2024-01-25T09:00:00Z"
}
}Draft Version
New agents are created with a draft version. Deploy the agent from the dashboard to make it active on channels.
Get Agent
/api/v1/agents/:idRetrieves detailed information about a specific agent, including version history and deployed configuration.
Path Parameters
Parameters
| Name | Type | Description |
|---|---|---|
idRequired | uuid | The agent's unique identifier |
Example Request
curl -X GET "https://dev.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000" \ -H "Authorization: Bearer YOUR_API_KEY"Response
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Sales Agent",
"description": "Handles inbound sales inquiries",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-20T14:45:00Z",
"deployed_version": {
"id": "v-abc123",
"version_label": "v1.2",
"instructions": "You are a sales agent for Acme Corp..."
},
"versions": [
{
"id": "v-abc123",
"version_label": "v1.2",
"deployment_status": "deployed",
"created_at": "2024-01-20T14:45:00Z"
},
{
"id": "v-xyz789",
"version_label": "v1.1",
"deployment_status": "archived",
"created_at": "2024-01-18T11:20:00Z"
}
]
}
}Update Agent
/api/v1/agents/:idUpdates an existing agent's name, description, or instructions. Updating instructions creates a new draft version.
Path Parameters
Parameters
| Name | Type | Description |
|---|---|---|
idRequired | uuid | The agent's unique identifier |
Request Body
Parameters
| Name | Type | Description |
|---|---|---|
name | string | New display name (1-100 characters) |
description | string | New description (max 500 characters) |
instructions | string | New system prompt (creates a draft version) |
Example Request
curl -X PATCH "https://dev.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Premium Sales Agent", "description": "Handles high-value sales inquiries"}'Response
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Premium Sales Agent",
"description": "Handles high-value sales inquiries",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-25T16:00:00Z"
}
}Instructions Update
Updating instructions creates a new draft version that must be deployed from the dashboard to take effect.
Delete Agent
/api/v1/agents/:idSoft-deletes an agent. The agent will no longer appear in listings and cannot be used on channels.
Path Parameters
Parameters
| Name | Type | Description |
|---|---|---|
idRequired | uuid | The agent's unique identifier |
Example Request
curl -X DELETE "https://dev.nutalk.ai/v1/agents/550e8400-e29b-41d4-a716-446655440000" \ -H "Authorization: Bearer YOUR_API_KEY"Response
{
"success": true,
"data": {
"deleted": true
}
}Channel Impact
Deleting an agent will disconnect it from all channels. Ensure you have a replacement agent configured before deleting.
Error Codes
| Code | Status | Description |
|---|---|---|
| NOT_FOUND | 404 | Agent does not exist |
| VALIDATION_ERROR | 400 | Invalid request parameters |
| INTERNAL_ERROR | 500 | Server errorâcontact support |