Create skill. POST /api/openapi/v1/skills, scope admin.v1.skills.manage.
- Scope: admin.v1.skills.manage
- Permission: Manage skills (skills)
- Permission type: Manage
- Endpoint: POST/api/openapi/v1/skills
Authentication and request headers
Call with an application API key. This endpoint checks only the scope above; read, manage and execute permissions do not imply one another.
| Name | Location | Type | Required | Description | Example |
|---|---|---|---|---|---|
| Authorization | header | string | Yes | Application API key, passed as a Bearer token. | Bearer qwk_*** |
| X-Request-Id | header | string | No | Optional request tracing identifier; generated by the server if omitted. | req-20260831-001 |
Request parameters
| Name | Location | Type | Required | Description | Example |
|---|---|---|---|---|---|
| Idempotency-Key | header | string | Required | Idempotency key used to prevent duplicate submissions | "<string>" |
| category_id | body | string · uuid | No | Category (category ID) | "<uuid>" |
| clients | body | array ｜ null | No | Supported clients | ["<string>"] |
| description | body | string | No | Description (English) | "<string>" |
| description_cn | body | string | No | Description | "<string>" |
| icon_upload_id | body | string · uuid | No | Resource icon (upload session ID) | "<uuid>" |
| icon_url | body | string · uri | No | Resource icon (URL) | "<string>" |
| name | body | string | Required | Unique identifier | "<string>" |
| name_cn | body | string | No | Skill name | "<string>" |
| name_en | body | string | No | Skill name (English) | "<string>" |
| status | body | string | No | Enabled | "draft" |
| upload_id | body | string · uuid | No | Resource package (ZIP) upload session ID | "<uuid>" |
| version | body | string | No | Version | "<string>" |
Request example
cURL
Responses
201 Created
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| clients | array ｜ null | Yes | Supported clients | ["<string>"] |
| created_at | string · date-time | Yes | Created at | "2026-08-27T10:00:00Z" |
| description | string | Yes | Description (English) | "<string>" |
| description_cn | string | No | Description | "<string>" |
| has_package | boolean | Yes | Whether a resource package has been uploaded | false |
| icon_url | string | No | Resource icon (URL) | "<string>" |
| id | string | Yes | Skill ID | "<string>" |
| name | string | Yes | Unique identifier | "<string>" |
| name_cn | string | No | Skill name | "<string>" |
| name_en | string | No | Skill name (English) | "<string>" |
| origin | string | Yes | Origin | "<string>" |
| readme_content | string | No | Details content | "<string>" |
| revision | integer · int64 | Yes | Revision used for concurrent update checks | 0 |
| source_type | string | No | Source type | "official" |
| status | string | Yes | Enabled | "<string>" |
| updated_at | string · date-time | Yes | Updated at | "2026-08-27T10:00:00Z" |
| version | string | No | Version | "<string>" |
default Flat business error
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| code | string | No | Stable business error code | "<string>" |
| detail | string | Yes | Human-readable error description | "<string>" |
| details | OpenapiErrorDetails | No | Error details | {"field":"<string>","reason":"<string>","suggestion":"<string>"} |
| details.field | string | No | Request field that failed validation | "<string>" |
| details.reason | string | No | Stable validation failure reason | "<string>" |
| details.suggestion | string | No | Suggested normalized value | "<string>" |
| error | string | Yes | Stable HTTP error type | "<string>" |