POST /v2/skills/{skill_id}/versions
Publish a new version, optionally carrying files from a previous version.
How to use
Publish a new revision. Repeat carry_paths for files to keep; base_version selects the source version (current by default). Supplying a different name can rename the skill. Review the assembled bundle before publishing.
Authentication and permissions
Required permissions: skills.update. Resource and owner access checks also apply.
Personal API key (sk_...) or supported user access JWT. See Authentication and authorization for endpoint restrictions and scopes. Use exactly one Authorization header.
ID of the skill.
Bundle files; each part's filename is its relative POSIX path inside the bundle (optionally under one shared root folder). A single .zip is accepted as an alternative.
Skill name (form mode); a changed name renames the skill when published.
Skill description (form mode).
SKILL.md body (form mode).
Action refs; repeat the field per item.
File paths to carry over unchanged from the current files; repeat the field per item.
Version to copy carry_paths from; defaults to the current version.
Created
Invalid request parameters
Authentication required
Permission denied; insufficient API-key scope includes meta.required_scope
Skill or version not found
Name or version conflict
Invalid skill bundle, including oversized uploads
Skill persistence failed; internal details are not exposed
Other client errors use the same public error envelope
curl --fail-with-body -sS \
"$STACKAI_BASE_URL/v2/skills/${SKILL_ID}/versions" \
-H "Authorization: Bearer $STACKAI_API_KEY" \
-F 'files=@skill.zip'{
"response_code": "text",
"meta": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"data": {
"version": 1,
"description": "text",
"created_by_user_profile": {
"id": "text",
"full_name": "text"
},
"created_at": "2026-01-01T00:00:00.000Z",
"instructions": "text",
"frontmatter": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"actions": [
"text"
],
"files": [
{
"path": "text",
"content_type": "text",
"size": 1
}
]
}
}Last updated
Was this helpful?

