Attach Skill To Agent

Beta

PUT

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

Attach a skill to this agent, pinned to one version. Omit version to pin whatever is latest AT THIS MOMENT - the pin is a number, never a live pointer, so a later edit to the skill does not reach this agent. Idempotent: attaching again re-pins.

Three refusals worth knowing. The agent and the skill must be in the same project (409 cross_project_reference). The skill’s tools must not collide by name with anything the agent already answers to (409 skill_tool_name_conflict) - the model picks a tool by name. And any knowledge base the skill names must already be attached to the agent (409), because retrieval re-authorizes against the agent’s own attachments and would refuse a skill-contributed base mid-call. Dark launch: requires the skills_access entitlement (402 skills_not_in_plan otherwise).

Attach a skill to this agent, pinned to one version. Omit `version` to pin whatever is latest AT THIS MOMENT - the pin is a number, never a live pointer, so a later edit to the skill does not reach this agent. Idempotent: attaching again re-pins. Three refusals worth knowing. The agent and the skill must be in the same project (409 `cross_project_reference`). The skill's tools must not collide by name with anything the agent already answers to (409 `skill_tool_name_conflict`) - the model picks a tool by name. And any knowledge base the skill names must already be attached to the agent (409), because retrieval re-authorizes against the agent's own attachments and would refuse a skill-contributed base mid-call. 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

agent_idstringRequired

Agent id (prefixed external id, agent_...).

skill_idstringRequired

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

Request

This endpoint expects an object.

versionintegerOptional>=1

Version to pin. Omit to pin whatever is latest at this moment.

enabledbooleanOptional

Defaults to true.

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

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

namestring

descriptionstring

versioninteger

The version this agent is pinned to, and the one dispatch renders.

latest_versioninteger

The version the catalog holds now. Higher than version means an upgrade is available.

enabledboolean

A disabled skill keeps its pin but is not rendered or dispatched.

instructionsstring

tool_idslist of strings

knowledge_base_idslist of strings

variablesmap from strings to strings

attached_atdatetime

updated_atdatetime

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

404

Not Found Error

409

Conflict Error

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

1	{
2	"skill_id": "string",
3	"name": "string",
4	"description": "string",
5	"version": 1,
6	"latest_version": 1,
7	"enabled": true,
8	"instructions": "string",
9	"tool_ids": [
10	"string"
11	],
12	"knowledge_base_ids": [
13	"string"
14	],
15	"variables": {},
16	"attached_at": "2024-01-15T09:30:00Z",
17	"updated_at": "2024-01-15T09:30:00Z"
18	}