Create a Skill Version

Description

Appends a new version to an existing Skill. A version is immutable after creation. The service generates version as a 16-digit Unix microsecond timestamp and updates the Skill's latest_version to point to it. Package and upload-field rules are the same as Create a Skill. See Skill package.

Path

POST /api/v1/forward/skills/{id}/versions

Request headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT or SAT>`
`Content-Type`	Yes	`multipart/form-data`

Path parameters

Parameter	Type	Required	Description
`id`	string	Yes	ID of the target Skill.

Query parameters

Parameter	Type	Required	Description
`identity_id`	string	No	For Identity-owned resources only. PATs may supply this query parameter; omitting it uses the administrator scope. SAT ownership is determined by the credential; any SAT (including Admin SAT) explicitly supplying this parameter, even with an empty value, receives HTTP 400. Versions inherit ownership from their Skill. See Identity ownership.

Form fields

Field	Type	Required	Description
`files`	file	Yes	Upload field that can appear multiple times. Supports two forms: • A single `.zip` archive; • A bare file tree, with one file per part and a relative path in `filename` (for example, `customer-reply/SKILL.md` or `customer-reply/scripts/run.sh`). Both the compressed archive and its extracted contents must be no larger than 50 MB.

This endpoint accepts only files; omitting it returns 400. The legacy singular file field is not supported here.

See Skill package for package constraints. A package must contain SKILL.md, have exactly one top-level directory, and use the name from SKILL.md as the directory name.

Example request

Single zip archive:

curl -X POST "https://api.qoder.com/api/v1/forward/skills/skill_xxx/versions" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "files=@customer-reply.zip;type=application/zip"

Bare file tree (repeat the files field):

curl -X POST "https://api.qoder.com/api/v1/forward/skills/skill_xxx/versions" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "files=@customer-reply/SKILL.md;filename=customer-reply/SKILL.md" \
  -F "files=@customer-reply/scripts/run.sh;filename=customer-reply/scripts/run.sh"

Example response

HTTP 201 Created

{
  "id": "skillver_xxx",
  "skill_id": "skill_xxx",
  "version": "1786973491821648",
  "name": "customer-reply",
  "description": "Customer reply skill",
  "directory": "customer-reply",
  "content_size": 2607,
  "content_sha256": "9de8ae3a296bc6198cd080f5ce31d523a34fd0a52e2e64365055fa79a0d3383d",
  "status": "active",
  "created_at": "2026-08-17T13:31:31.917881Z",
  "metadata": {}
}

Response fields

The response is a Skill version object. version is the newly assigned 16-digit Unix microsecond timestamp. After creation, the Skill's latest_version points to that value; verify it with Get a Skill.

Errors

HTTP	Type	Trigger
400	`invalid_request_error`	Multipart parsing failed, the package structure is invalid (for example, missing `SKILL.md`, multiple top-level directories, or a directory name that differs from `name`), a parameter is missing, or any SAT explicitly supplies query `identity_id` (even with an empty value).
400	`skill_content_too_large`	The compressed archive or its extracted contents exceed 50 MB.
401	`authentication_error`	The authentication token is missing or invalid.
403	`permission_error`	An owner mismatch occurs in the administrator scope, or a downstream service denies access.
404	`not_found_error`	The Skill does not exist or is not visible in the current Identity scope; the Identity specified by the PAT is invalid, disabled, deleted, or outside the caller's ownership.
413	`invalid_request_error`	The request body exceeds the service limit.
429	`rate_limit_error`	The caller exceeded the API rate limit.
500/502/503	`api_error`	Forward or a dependent service failed.

​Description

​Path

​Request headers

​Path parameters

​Query parameters

​Form fields

​Example request

​Example response

​Response fields

​Errors