Skip to main content
Versions

Create a Skill Version

Forward API reference.

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

HeaderRequiredDescription
AuthorizationYesBearer <PAT or SAT>
Content-TypeYesmultipart/form-data

Path parameters

ParameterTypeRequiredDescription
idstringYesID of the target Skill.

Form fields

FieldTypeRequiredDescription
filesfileYesUpload 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

HTTPTypeTrigger
400invalid_request_errorMultipart parsing failed, the package structure is invalid (for example, missing SKILL.md, multiple top-level directories, or a directory name that differs from name), or a parameter is missing.
400skill_content_too_largeThe compressed archive or its extracted contents exceed 50 MB.
401authentication_errorThe authentication token is missing or invalid.
403permission_errorThe caller cannot access the Skill.
404not_found_errorThe Skill does not exist or is not visible.
413invalid_request_errorThe request body exceeds the service limit.
429rate_limit_errorThe caller exceeded the API rate limit.
500/502/503api_errorForward or a dependent service failed.
First steps
Define your agent
Configure agent environment
Delegate work to your agent
Agent integrations
Manage agent context
Account
Best Practices
Announcements
API reference
Create a Skill Version - Qoder