Update Skill

POST/v1/skills/{skill_id}

Change default_version, status, or market metadata. row_version is required when metadata is sent; otherwise the current value is used.

Path parameters

stringskill_idrequired

Skill ID (skl_ prefix).

Request body

JSON object.

Optional<string>default_version

Default used when first attaching this Skill without an explicit version. Existing Agent bindings keep their pinned versions.

Optional<string>status

active or disabled.

Optional<object | null>metadata

Presentation metadata under the market namespace only (up to 16 KiB). Requires row_version; replaces the metadata object. Unknown namespaces or fields return 400. See the metadata example below.

Optional<integer>row_version

Current row_version from Get Skill. A stale value returns 409 conflict; required when metadata is present.

curl -X POST https://api.sandbase.ai/v1/skills/skl_3c5e7a9b-1d4f-5a6c-8e2b-4d6f8a0c2e57 \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "default_version": "2"
  }'

Response200 OK

{
  "id": "skl_3c5e7a9b-1d4f-5a6c-8e2b-4d6f8a0c2e57",
  "object": "skill",
  "name": "release-notes",
  "description": "Draft release notes from merged changes.",
  "default_version": "2",
  "latest_version": "2",
  "status": "active",
  "visibility": "private",
  "row_version": 3,
  "metadata": {},
  "created_at": 1791273600,
  "updated_at": 1791273600
}

Metadata example

Send the current row_version together with the complete metadata object:

{
  "row_version": 3,
  "metadata": {
    "market": {
      "display_name": "Release notes",
      "categories": ["development"],
      "tags": ["releases"],
      "required_endpoints": ["github.issues"],
      "servers": ["github"]
    }
  }
}

Market metadata describes the Skill for display. It does not install a server, grant credentials, or change the Agent's MCP selection. metadata: {} or metadata: null clears it; both still require row_version.