Skip to main content
PATCH
Update a workspace skill

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

1–255 printable ASCII characters (0x21–0x7E, no spaces), scoped to the calling credential. A repeat with the same key and request never runs the write again, a 5xx included: once the operation's permissions pass again it answers the identical status and body of the first response (Idempotent-Replayed: true, also sent as Idempotency-Replayed: true), unless the operation's own replay policy withholds it; a first response that was not stored (over 32 KiB, or carrying a one-time secret) answers its first status with only data.id (Idempotency-Replay-Disclosure: id-only) when it named one; otherwise 409 idempotency_result_unavailable; a repeat while the first is still running is 409 idempotency_key_in_flight, and the same key with a different request is 422 idempotency_key_reuse. Honoured for External App JWTs and platform and Personal keys; an External App's static companion key is not protected.

Required string length: 1 - 255

Path Parameters

skillId
string
required
Minimum string length: 1

Body

application/json

id is the skill's skillId. Only supplied fields are patched; any other field is ignored. status (and enabled) are live controls outside version identity.

name
string
description
string
version
string
status
string
tags
string[]
emoji
string
skillType
string
content
string
files
object
inputModes
string[]
outputModes
string[]
allowedTools
string[]
defaultActivationMode
enum<string>
Available options:
always,
on_demand

Response

Skill updated A same-key repeat whose first response was not stored (over 32 KiB, or a one-time secret) answers this status with only data.id (IdOnlyReplay, Idempotency-Replay-Disclosure: id-only).

data
object
required

A skill in the platform-global catalog. activeVersionId and canaryVersionId name immutable versions (see listVersions). The creator, principal, synthesis, embedding and usage fields are never returned; absent optional values are null.

meta
object
required