API Reference
Goals API
Manage binary success goals and period-based targets for agent evaluation.
Goals describe outcomes an agent should achieve. Each goal belongs to an agent and can optionally be scoped to a channel. API keys need goals:read or goals:write.
Available Endpoints
/v1/goals- List goals/v1/goals- Create a goal/v1/goals/:id- Get a goal/v1/goals/:id- Update a goal/v1/goals/:id- Delete a goalList Goals
/v1/goalsQuery Parameters
| Name | Type | Description |
|---|---|---|
limit | integer | Number of goals to return (1-100, default: 20) |
offset | integer | Number of goals to skip (default: 0) |
agent_id | uuid | Filter goals for a specific agent |
channel_id | uuid | Filter goals scoped to a specific channel |
active | boolean | Filter active or inactive goals |
curl -X GET "https://www.nutalk.ai/v1/goals?active=true&limit=10" \ -H "Authorization: Bearer YOUR_API_KEY"{
"success": true,
"data": [
{
"id": "goal_abc123",
"agent_id": "agent_abc123",
"channel_id": null,
"title": "Book qualified meeting",
"description": "The call ends with a confirmed meeting time.",
"active": true,
"goal_targets": [
{
"id": "target_abc123",
"period": "week",
"target_type": "count",
"target_count": 25,
"target_rate": null,
"is_primary": true
}
]
}
],
"pagination": {
"total": 1,
"limit": 10,
"offset": 0,
"has_more": false
}
}Create Goal
/v1/goalsRequest Body
| Name | Type | Description |
|---|---|---|
agent_idRequired | uuid | Agent that owns the goal |
channel_id | uuid | null | Optional channel scope. Null applies to all channels. |
titleRequired | string | Goal title |
descriptionRequired | string | Success criteria used for evaluation |
targets | array | Period targets. target_type is count or rate. Only one target can be primary. |
curl -X POST "https://www.nutalk.ai/v1/goals" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "agent_abc123", "title": "Book qualified meeting", "description": "The call ends with a confirmed meeting time.", "targets": [ { "period": "week", "target_type": "count", "target_count": 25, "is_primary": true } ]}'{
"success": true,
"data": {
"id": "goal_abc123",
"agent_id": "agent_abc123",
"title": "Book qualified meeting",
"active": true,
"goal_targets": [
{
"period": "week",
"target_type": "count",
"target_count": 25,
"is_primary": true
}
]
}
}Get Goal
/v1/goals/:idcurl -X GET "https://www.nutalk.ai/v1/goals/goal_abc123" \ -H "Authorization: Bearer YOUR_API_KEY"{
"success": true,
"data": {
"id": "goal_abc123",
"agent_id": "agent_abc123",
"channel_id": null,
"title": "Book qualified meeting",
"description": "The call ends with a confirmed meeting time.",
"active": true,
"goal_targets": []
}
}Update Goal
/v1/goals/:idSend any writable field. If targets is included, it replaces all existing targets for the goal.
curl -X PATCH "https://www.nutalk.ai/v1/goals/goal_abc123" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "active": true, "targets": [ { "period": "month", "target_type": "rate", "target_rate": 70, "is_primary": true } ]}'{
"success": true,
"data": {
"id": "goal_abc123",
"active": true,
"goal_targets": [
{
"period": "month",
"target_type": "rate",
"target_rate": 70,
"is_primary": true
}
]
}
}Delete Goal
/v1/goals/:idcurl -X DELETE "https://www.nutalk.ai/v1/goals/goal_abc123" \ -H "Authorization: Bearer YOUR_API_KEY"{
"success": true,
"data": {
"id": "goal_abc123",
"deleted": true
}
}Targets Are Deleted
Deleting a goal also deletes its period targets.