Skip to main content
PATCH
cURL

Authorizations

Authorization
string
header
required

Send your API key as Authorization: Bearer YOUR_API_KEY.

Path Parameters

id
string
required

Agent id.

Minimum string length: 1
skillId
string
required

Stable skill id returned by the skills API.

Minimum string length: 1

Body

application/json
name
string

Human-readable name for the skill. Longer input is truncated to 120 characters and saved, not rejected. Whitespace is trimmed first, so a whitespace-only name is rejected as empty.

Required string length: 1 - 120
Pattern: \S
whenToUse
string
default:""

Plain-English trigger: when the agent should reach for this. Longer input is truncated to 300 characters and saved, not rejected.

Maximum string length: 300
enabled
boolean
default:true

Whether the skill is active on the agent. A disabled skill is kept but its tool is not installed.

instructions
string

Instructions skill only. The playbook the agent follows. Longer text is cut to 12000 characters and saved.

Required string length: 1 - 12000
zips
string

Service area skill only. Five-digit US ZIP codes, separated by commas or line breaks. Other text is ignored. A value with no ZIP code is rejected.

Required string length: 1 - 4000
outOfAreaResponse
string

Service area skill only. What the agent does when the caller's ZIP code is not on the list. Longer text is cut to 400 characters.

Maximum string length: 400
transferNumber
string

Live transfer skill only. The number the call goes to, in E.164 format, such as +14155550100. Other formats are rejected.

Required string length: 1 - 40
transferMessage
string

Live transfer skill only. What the agent says as it hands the call over. Empty keeps the default line. Longer text is cut to 400 characters.

Maximum string length: 400
tags
string

Add tag skill: the tags the agent may add, up to 30. Check tag skill: the one tag it checks. Separate tags with commas or line breaks.

Required string length: 1 - 1500
checkingMessage
string

Check tag skill only. What the agent says while the tag lookup runs. Longer text is cut to 200 characters.

Maximum string length: 200
expectedVersion
integer

The skills version from your last read of GET /api/agent-builder/agents/{id}/skills. If the skills changed since then, the write is refused with 409. Omit it to save without this check.

Required range: x >= 0

Response

Skill updated.

success
boolean
required
version
integer
required
Required range: x >= 0
skill
Custom instruction skill · object
required

A plain-English playbook that teaches the agent when and how to handle a use case.

partialFailures
string[]

Background synchronization work that did not finish. The skill change was still saved.