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	Use only when operating on Identity-owned resources. A PAT can explicitly supply this query parameter; omitting it uses administrator scope. SAT ownership is determined by the credential. Explicitly supplying this parameter with any SAT (including an empty value) returns HTTP 400. Versions inherit the ownership of 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.cn/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.cn/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 the query parameter `identity_id` (including 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 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 authorized scope.
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