Competencies API
A competency is one behavior the evaluator rates in an agent's evaluated conversations, on 3 or 4 performance levels from the lowest to the highest. Ratings appear in the dashboard, on the Competencies page and in each conversation's evaluation.
competencies:readcompetencies:write5 endpointsShow
/v1/competenciesList competencies
Lists competencies with their performance levels, newest first.
competencies:readQuery parameters
limitinteger · 1–100Results per page. Default: 20.
offsetinteger · at least 0Results to skip. Default: 0.
agent_iduuidOnly this agent's competencies.
categoryskill | knowledge | attitudeOnly this type.
activebooleanOnly active (true) or inactive (false) competencies.
Show 1 more field
Errors
400validation_errorA query parameter is invalid (details.errors lists each one).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl "https://www.nutalk.ai/v1/competencies?category=skill&limit=10" \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": [
{
"id": "b97659d1-b147-4831-86d0-3e36b6bd3fee",
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Handles price questions",
"category": "skill",
"area": "Sales",
"description": "Gives the approved price range and offers to book, without pressure.",
"rubric": [
{
"level": "Needs improvement",
"description": "Invents a price, dodges the question or pushes for the sale.",
"criteria": null,
"weight": null,
"threshold": null
},
{
"level": "Meets expectations",
"description": "Gives the approved range and offers the next step.",
"criteria": null,
"weight": null,
"threshold": null
},
{
"level": "Exceeds expectations",
"description": "Also explains what's included and answers the next question before it's asked.",
"criteria": null,
"weight": null,
"threshold": null
}
],
"min_levels": 3,
"weight": 1,
"active": true,
"created_at": "2026-10-02T02:25:39.506247+00:00",
"updated_at": "2026-10-02T02:25:39.506247+00:00"
}
],
"pagination": {
"total": 1,
"limit": 10,
"offset": 0,
"has_more": false
}
}/v1/competenciesCreate a competency
Creates a competency the evaluator rates in each of the agent's evaluated conversations: what good looks like and 3 or 4 performance levels. Every competency counts the same.
competencies:writeLevels go from the lowest to the highest. The middle level (the third of four) is the passing level: an evaluation at or above it counts as passing.
Request body
agent_iduuidrequiredThe agent it rates.
namestring · 1–200 charactersrequiredCompetency name: one behavior, e.g. Handles price questions.
descriptionstring | null · up to 5,000What good looks like, in one sentence the evaluator can check in a transcript.
categoryskill | knowledge | attitude | nullThe competency's type; null for none. Default: skill.
areastring | null · up to 60The competency's category: the group it belongs to, any name (e.g. Sales, Customer service, Technical); null for none.
rubricobject[] · 3–4 itemsrequiredPerformance levels, from the lowest to the highest.
rubric[].levelstring · 1–100 charactersrequiredLevel name, e.g. Meets expectations.
rubric[].descriptionstring | null · up to 1,000What this level looks like in a conversation: one sentence.
rubric[].criteriastring | null · up to 2,000Optional extra detail for the evaluator; levels written in the dashboard keep everything in description.
rubric[].weightnumber | nullDeprecated. Accepted and ignored; answered as null.
rubric[].thresholdnumber | nullDeprecated. Accepted and ignored; answered as null.
min_levelsintegerDeprecated. Accepted and ignored: a rubric has 3 or 4 levels.
weightnumberDeprecated. Accepted and ignored: every competency counts the same. Answered as 1.
activebooleanInactive competencies are not evaluated. Default: true.
Show 10 more fields
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).400validation_errorThe rubric doesn't have 3 or 4 levels, or a level has no name.422validation_errorarea, or a null category, sent before the workspace's next platform update makes them available.404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X POST https://www.nutalk.ai/v1/competencies \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Handles price questions",
"description": "Gives the approved price range and offers to book, without pressure.",
"category": "skill",
"area": "Sales",
"rubric": [
{
"level": "Needs improvement",
"description": "Invents a price, dodges the question or pushes for the sale."
},
{
"level": "Meets expectations",
"description": "Gives the approved range and offers the next step."
},
{
"level": "Exceeds expectations",
"description": "Also explains what'\''s included and answers the next question before it'\''s asked."
}
]
}'{
"success": true,
"data": {
"id": "b97659d1-b147-4831-86d0-3e36b6bd3fee",
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Handles price questions",
"category": "skill",
"area": "Sales",
"description": "Gives the approved price range and offers to book, without pressure.",
"rubric": [
{
"level": "Needs improvement",
"description": "Invents a price, dodges the question or pushes for the sale.",
"criteria": null,
"weight": null,
"threshold": null
},
{
"level": "Meets expectations",
"description": "Gives the approved range and offers the next step.",
"criteria": null,
"weight": null,
"threshold": null
},
{
"level": "Exceeds expectations",
"description": "Also explains what's included and answers the next question before it's asked.",
"criteria": null,
"weight": null,
"threshold": null
}
],
"min_levels": 3,
"weight": 1,
"active": true,
"created_at": "2026-10-02T02:25:39.506247+00:00",
"updated_at": "2026-10-02T02:25:39.506247+00:00"
}
}/v1/competencies/:idGet a competency
Returns one competency with its performance levels.
competencies:readPath parameters
iduuidrequiredThe competency id.
Errors
404not_foundNo competency with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/competencies/b97659d1-b147-4831-86d0-3e36b6bd3fee \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"id": "b97659d1-b147-4831-86d0-3e36b6bd3fee",
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Handles price questions",
"category": "skill",
"area": "Sales",
"description": "Gives the approved price range and offers to book, without pressure.",
"rubric": [
{
"level": "Needs improvement",
"description": "Invents a price, dodges the question or pushes for the sale.",
"criteria": null,
"weight": null,
"threshold": null
},
{
"level": "Meets expectations",
"description": "Gives the approved range and offers the next step.",
"criteria": null,
"weight": null,
"threshold": null
},
{
"level": "Exceeds expectations",
"description": "Also explains what's included and answers the next question before it's asked.",
"criteria": null,
"weight": null,
"threshold": null
}
],
"min_levels": 3,
"weight": 1,
"active": true,
"created_at": "2026-10-02T02:25:39.506247+00:00",
"updated_at": "2026-10-02T02:25:39.506247+00:00"
}
}/v1/competencies/:idUpdate a competency
Changes the fields you send; rubric replaces the whole rubric.
competencies:writeCan wait for approvalLevels go from the lowest to the highest. The middle level (the third of four) is the passing level: an evaluation at or above it counts as passing.
Path parameters
iduuidrequiredThe competency id.
Request body
namestring · 1–200 charactersNew name.
descriptionstring | null · up to 5,000What good looks like.
categoryskill | knowledge | attitude | nullThe type; null for none.
areastring | null · up to 60The category; null for none.
rubricobject[] · 3–4 itemsNew levels, from the lowest to the highest (replaces all).
rubric[].levelstring · 1–100 charactersrequiredLevel name, e.g. Meets expectations.
rubric[].descriptionstring | null · up to 1,000What this level looks like in a conversation: one sentence.
rubric[].criteriastring | null · up to 2,000Optional extra detail for the evaluator; levels written in the dashboard keep everything in description.
rubric[].weightnumber | nullDeprecated. Accepted and ignored; answered as null.
rubric[].thresholdnumber | nullDeprecated. Accepted and ignored; answered as null.
min_levelsintegerDeprecated. Accepted and ignored.
weightnumberDeprecated. Accepted and ignored: every competency counts the same.
activebooleanTurn evaluation on or off.
Show 9 more fields
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).400validation_errorNo field to change was sent, or the new rubric doesn't have 3 or 4 levels.422validation_errorarea, or a null category, sent before the workspace's next platform update makes them available.404not_foundNo competency with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X PATCH https://www.nutalk.ai/v1/competencies/b97659d1-b147-4831-86d0-3e36b6bd3fee \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"area": "Sales",
"active": true
}'{
"success": true,
"data": {
"id": "b97659d1-b147-4831-86d0-3e36b6bd3fee",
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Handles price questions",
"category": "skill",
"area": "Sales",
"description": "Gives the approved price range and offers to book, without pressure.",
"rubric": [
{
"level": "Needs improvement",
"description": "Invents a price, dodges the question or pushes for the sale.",
"criteria": null,
"weight": null,
"threshold": null
},
{
"level": "Meets expectations",
"description": "Gives the approved range and offers the next step.",
"criteria": null,
"weight": null,
"threshold": null
},
{
"level": "Exceeds expectations",
"description": "Also explains what's included and answers the next question before it's asked.",
"criteria": null,
"weight": null,
"threshold": null
}
],
"min_levels": 3,
"weight": 1,
"active": true,
"created_at": "2026-10-02T02:25:39.506247+00:00",
"updated_at": "2026-10-02T02:25:47.646176+00:00"
}
}/v1/competencies/:idDelete a competency
Deletes the competency.
competencies:writeWaits for approvalPath parameters
iduuidrequiredThe competency id.
Unless its key was set not to wait, nothing is removed yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
404not_foundNo competency with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X DELETE https://www.nutalk.ai/v1/competencies/b97659d1-b147-4831-86d0-3e36b6bd3fee \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"id": "b97659d1-b147-4831-86d0-3e36b6bd3fee",
"deleted": true
}
}