Update a Skill

⚠️ Deprecated: PUT /skills/{id} is the legacy content-update path and returns Deprecation: true in the response headers. Use Create a Skill Version to append an immutable version. This endpoint remains available for compatibility with existing clients.

Description

Uses PUT to update a Skill's display information or complete content. The Skill name cannot be changed. Supplying content creates a new immutable version, equivalent to appending a version, and points latest_version to it.

Path

PUT /api/v1/forward/skills/{id}

Request headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT or SAT>`
`Content-Type`	Yes	`application/json`

Path parameters

Parameter	Type	Required	Description
`id`	string	Yes	Skill ID.

Request body

Field	Type	Required	Description
`description`	string	No	New description.
`content`	string	No	New content as a zip archive. Both the archive and its extracted contents must be no larger than 50 MB, otherwise 400 is returned. The entire request body, including base64 encoding and the JSON envelope, is limited to about 67.7 MB; exceeding it returns 413.
`content_encoding`	string	No	Encoding of `content`. Supports `base64`, `utf-8`, `utf8`, `plain`, and `text`; defaults to UTF-8 text. A non-empty `content` value is required when this field is provided.
`metadata`	object	No	Metadata object that replaces the current metadata rather than merging it. It must not be `null`, and values must be strings. `created_by` is reserved and must not be supplied (supplying it returns 400).
`icon_id`	string \| null	No	Updates or clears the Forward icon.
`name`	string	No	⚠️ Deprecated: The Skill name cannot be changed. If supplied, it must exactly match the current canonical name or the request returns 400; a matching value is a no-op.

Response headers

Responses from this endpoint include Deprecation: true, without a specific Sunset date.

Example request

curl -X PUT "https://api.qoder.com/api/v1/forward/skills/skill_xxx" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated customer reply skill",
    "content": "UEsDB...",
    "content_encoding": "base64",
    "metadata": {"source": "console"}
  }'

Example response

HTTP 200 OK

{
  "id": "skill_xxx",
  "type": "skill",
  "display_title": "customer-reply",
  "description": "Updated customer reply skill",
  "source": "custom",
  "latest_version": "1759178010641129",
  "metadata": {"source": "console"},
  "created_at": "2026-07-23T10:00:00Z",
  "updated_at": "2026-07-23T11:00:00Z",
  "identity_id": null,
  "icon_url": null,
  "binding_info": {"agent_template_count": 0}
}

Response fields

The response is a Skill object.

Errors

HTTP	Type	Trigger
400	`invalid_request_error`	The request body is invalid, `name` differs from the current canonical name, `content_encoding` is supplied without `content`, or a similar validation fails.
400	`invalid_request_error`	If the reserved key `created_by` is supplied, `message` is `metadata key "created_by" is reserved`, identifying the invalid field.
400	`skill_content_too_large`	The `content` archive or its extracted contents exceed 50 MB.
401	`authentication_error`	The authentication token is missing or invalid.
403	`permission_error`	The caller cannot modify the Skill.
404	`not_found_error`	The Skill does not exist or is not visible.
413	`invalid_request_error`	The entire request body exceeds approximately 67.7 MB.
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

​Request body

​Response headers

​Example request

​Example response

​Response fields

​Errors