API Reference
Competencies API
Manage the skills, knowledge areas, and attitudes evaluated for agents.
Competencies are scored with rubrics. API keys need competencies:read for reads and competencies:write for mutations.
Available Endpoints
/v1/competencies- List competencies/v1/competencies- Create a competency/v1/competencies/:id- Get a competency/v1/competencies/:id- Update a competency/v1/competencies/:id- Delete a competencyList Competencies
/v1/competenciesQuery Parameters
| Name | Type | Description |
|---|---|---|
limit | integer | Number of competencies to return (1-100, default: 20) |
offset | integer | Number of competencies to skip (default: 0) |
agent_id | uuid | Filter competencies for a specific agent |
category | string | Filter by skill, knowledge, or attitude |
active | boolean | Filter active or inactive competencies |
curl -X GET "https://www.nutalk.ai/v1/competencies?category=skill&limit=10" \ -H "Authorization: Bearer YOUR_API_KEY"{
"success": true,
"data": [
{
"id": "comp_abc123",
"agent_id": "agent_abc123",
"name": "Discovery quality",
"category": "skill",
"description": "Measures how well the agent discovers customer needs.",
"min_levels": 2,
"weight": 1,
"active": true,
"rubric": []
}
],
"pagination": {
"total": 1,
"limit": 10,
"offset": 0,
"has_more": false
}
}Create Competency
/v1/competenciesRequest Body
| Name | Type | Description |
|---|---|---|
agent_idRequired | uuid | Agent that owns the competency |
nameRequired | string | Competency name |
category | string | skill, knowledge, or attitude (default: skill) |
rubricRequired | array | At least min_levels rubric entries |
min_levels | integer | Minimum rubric levels required (default: 2) |
weight | number | Relative scoring weight (default: 1) |
curl -X POST "https://www.nutalk.ai/v1/competencies" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "agent_abc123", "name": "Discovery quality", "category": "skill", "description": "Measures how well the agent discovers customer needs.", "min_levels": 2, "rubric": [ { "level": "Needs improvement", "description": "Misses important qualification details." }, { "level": "Excellent", "description": "Captures pain, timeline, authority, and next step." } ]}'{
"success": true,
"data": {
"id": "comp_abc123",
"agent_id": "agent_abc123",
"name": "Discovery quality",
"category": "skill",
"min_levels": 2,
"weight": 1,
"active": true
}
}Get Competency
/v1/competencies/:idcurl -X GET "https://www.nutalk.ai/v1/competencies/comp_abc123" \ -H "Authorization: Bearer YOUR_API_KEY"{
"success": true,
"data": {
"id": "comp_abc123",
"agent_id": "agent_abc123",
"name": "Discovery quality",
"category": "skill",
"description": "Measures how well the agent discovers customer needs.",
"rubric": [],
"min_levels": 2,
"weight": 1,
"active": true
}
}Update Competency
/v1/competencies/:idSend any writable field. When increasing min_levels, include enough rubric entries or the request will be rejected.
curl -X PATCH "https://www.nutalk.ai/v1/competencies/comp_abc123" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "weight": 1.5, "active": true}'{
"success": true,
"data": {
"id": "comp_abc123",
"weight": 1.5,
"active": true
}
}Delete Competency
/v1/competencies/:idcurl -X DELETE "https://www.nutalk.ai/v1/competencies/comp_abc123" \ -H "Authorization: Bearer YOUR_API_KEY"{
"success": true,
"data": {
"id": "comp_abc123",
"deleted": true
}
}Evaluation History
Deleting a competency removes it from future evaluations. Existing historical call evaluation records are not recalculated.