List skill versions

GET /v1/skills/{skill_id}/versions

Lists a skill’s versions, newest first.

You can’t delete a single version: DELETE /v1/skills/{skill_id}/versions/{version} returns 400. To replace a version, upload a new one. To remove every version, delete the skill.

The key must have the skills:read capability. For what each capability allows, see Keys.

Path parameters

Name	Type	Required	Default	Description
`skill_id`	`string`	Yes		The ID of the skill, or a built-in skill’s slug.

Query parameters

Name	Type	Required	Default	Description
`limit`	`integer`	No	`20`	The maximum number of versions to return. Must be between 1 and 100.
`page`	`string`	No		The `next_page` value from the previous response. Leave it out to get the first page.

Response

Returns 200 with a page of skill version objects in data, newest first, and a next_page value to pass as page. next_page is null on the last page. A version’s id is what {version} takes. For every field, see Skills.

{
  "data": [
    {
      "id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
      "type": "skill_version",
      "created_at": "2026-10-27T15:02:11.388Z",
      "description": "Summarize a pull request for reviewers.",
      "name": "pr-summary",
      "skill_id": "8b3f6c1e-2a4d-4f7b-9c1e-5d6a7b8c9d0e"
    }
  ],
  "next_page": null
}

Errors

This endpoint can return these errors as well as the common errors.

Status	`error.type`	Cause and fix
400	`invalid_request_error`	`limit` is outside 1 to 100. Send a value from 1 to 100.
404	`not_found_error`	No skill with this ID or slug exists, or the key’s owner can’t read it. Check the ID or slug, and that the key’s owner can read the skill.

Example

curl -sS "$CONTEXT_BASE_URL/v1/skills/8b3f6c1e-2a4d-4f7b-9c1e-5d6a7b8c9d0e/versions" -H "x-api-key: $CONTEXT_API_KEY"

for version in client.beta.skills.versions.list("8b3f6c1e-2a4d-4f7b-9c1e-5d6a7b8c9d0e"):
    print(version.id, version.created_at)

for await (const version of client.beta.skills.versions.list("8b3f6c1e-2a4d-4f7b-9c1e-5d6a7b8c9d0e")) console.log(version.id)