Update Skill

Beta

PATCH

https://api.speechify.ai/v1/skills/:skill_id

Update a skill. The two halves behave differently on purpose: name and description are labels and edit in place, while instructions, tool_ids, knowledge_base_ids and variables are the body - touching any of them MINTS A NEW VERSION and leaves every existing attachment on the version it pinned. Agents move when someone moves them, never because the catalog changed. A present list replaces rather than appends. Dark launch: requires the skills_access entitlement (402 skills_not_in_plan otherwise).

Update a skill. The two halves behave differently on purpose: `name` and `description` are labels and edit in place, while `instructions`, `tool_ids`, `knowledge_base_ids` and `variables` are the body - touching any of them MINTS A NEW VERSION and leaves every existing attachment on the version it pinned. Agents move when someone moves them, never because the catalog changed. A present list replaces rather than appends. Dark launch: requires the `skills_access` entitlement (402 `skills_not_in_plan` otherwise).

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Path parameters

skill_idstringRequired

Skill id (prefixed external id, skill_...).

Request

This endpoint expects an object.

namestringOptional

descriptionstringOptional<=1000 characters

instructionsstringOptional1-4000 characters

tool_idslist of stringsOptional

knowledge_base_idslist of stringsOptional

variablesmap from strings to stringsOptional

Response headers

Speechify-Request-IdstringOptional

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a Speechify-Request-Id request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests

it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

The legacy alias X-Request-ID carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a `Speechify-Request-Id` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope. The legacy alias `X-Request-ID` carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Response

The skill, at the version this call left it on.

idstringformat: "^skill_[0-9a-hjkmnp-tv-z]{26}$"

namestring

descriptionstring

project_idstring or nullformat: "^proj_[0-9a-hjkmnp-tv-z]{26}$"

The project this skill belongs to; null when it belongs to none.

versioninteger

The version this body came from.

latest_versioninteger

The highest version minted. Differs from version only when you asked for an older one.

instructionsstring

The procedure, rendered into the system prompt of every agent attached at this version.

tool_idslist of strings

Tool definitions this skill contributes to an attached agent's toolbelt.

knowledge_base_idslist of strings

Knowledge bases this procedure needs. Unlike tools these are not contributed - the agent must already have them attached, and an attach naming one it lacks is refused.

variablesmap from strings to strings

Defaults for the {{tokens}} the instructions reference. They only fill keys nothing else set - the agent’s own values, the flow’s and the session’s all outrank them.

attached_agent_countinteger

How many agents hold this skill. Zero on list responses.

created_atdatetime

updated_atdatetime

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

404

Not Found Error

409

Conflict Error

$	curl -X PATCH https://api.speechify.ai/v1/skills/skill_01jqr8x9zg5k2m3n4p5q6r7s8t \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{}'

1	{
2	"id": "skill_01jqr8x9zg5k2m3n4p5q6r7s8t",
3	"name": "Book an appointment",
4	"description": "string",
5	"project_id": "string",
6	"version": 1,
7	"latest_version": 1,
8	"instructions": "string",
9	"tool_ids": [
10	"string"
11	],
12	"knowledge_base_ids": [
13	"string"
14	],
15	"variables": {},
16	"attached_agent_count": 1,
17	"created_at": "2024-01-15T09:30:00Z",
18	"updated_at": "2024-01-15T09:30:00Z"
19	}