Skill バージョンの作成

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.

パス

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

リクエストヘッダー

ヘッダー	必須	説明
`Authorization`	はい	`Bearer <PAT または SAT>`
`Content-Type`	はい	`multipart/form-data`

パス参数

パラメーター	型	必須	説明
`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

フィールド	型	必須	説明
`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.

リクエスト例

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"

レスポンス例

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": {}
}

レスポンスフィールド

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.

エラー

HTTP	Type	発生条件
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`	認証トークンがないか、無効です。
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 または依存サービスでエラーが発生しました。

​Description

​パス

​リクエストヘッダー

​パス参数

​Query parameters

​Form fields

​リクエスト例

​レスポンス例

​レスポンスフィールド

​エラー