API ReferenceSkills

Create Skill

Beta

Create a skill at version 1. Names are unique per workspace. Every tool_ids and knowledge_base_ids entry must already exist in the same project as the skill. Bounded by the workspace’s skill limit (409 skill_limit_reached). 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_…’.

Headers

Speechify-VersionstringOptional
Idempotency-KeystringOptional<=255 characters
A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns `409 idempotency_conflict`. A replayed response carries the `Idempotent-Replayed: true` header.

Request

This endpoint expects an object.
namestringRequired

1-128 characters of letters, digits, spaces, or . _ -; unique per workspace.

instructionsstringRequired1-4000 characters

The procedure. Bounded because it rides on every dispatched turn of every agent that attaches it, so the limit is a per-turn token bill rather than a storage bound.

descriptionstringOptional<=1000 characters
tool_idslist of stringsOptional
knowledge_base_idslist of stringsOptional
variablesmap from strings to stringsOptional

Default token values. Keys in the reserved system__ namespace are refused.

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

The project to create the skill in; omit for the caller’s default.

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).

Response

The created skill.
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