Skills API
Manage scoped, versioned reusable task instructions through the customer API.
Use a customer API key with Authorization: Bearer wvz_your_api_key. Every request specifies a UUID workspaceId. Workspace-scoped keys can only access their allowed workspaces.
The library scope is end_user by default or workspace for shared instructions. Personal library requests from your backend require endUserId, the customer's external identity previously registered in that workspace. The API does not treat this as a dashboard user identifier. Shared libraries omit endUserId.
Skill responses expose metadata and, on an explicit read or write, Markdown. The owner and sharing scope are immutable. Create a separate copy to share a personal skill.
Search skills
/api/v1/skills| Query | Meaning |
|---|---|
workspaceId | Required workspace UUID |
scope | end_user or workspace |
endUserId | Required external identity for a personal library |
query | Search names, slugs and descriptions, up to 120 characters |
tag | Match one tag |
includeDisabled | true to include disabled skills for maintenance; default false |
limit / offset | Page size 1 –50, default 25; offset 0 –10,000 |
Returns { skills, pagination: { limit, offset, total }, permissions: { canWrite } }. Search returns metadata only, never Markdown. Each metadata record includes id, workspaceId, scope, slug, name, description, tags, enabled, version, createdAt and updatedAt.
Create a skill
/api/v1/skills{
"workspaceId": "11111111-1111-4111-8111-111111111111",
"scope": "end_user",
"endUserId": "customer_123",
"slug": "customer-call-brief",
"name": "Prepare a customer call brief",
"description": "Prepare a sourced brief before a customer meeting.",
"markdown": "# Customer call brief\nRead the connected account notes. Summarize open questions and cite the source records. Return a draft for review.",
"tags": ["sales", "meetings"],
"enabled": true
}Required content: slug, name and markdown. Slugs use lowercase letters, numbers and hyphens, up to 64 characters. Names support 120 characters, descriptions 500, Markdown 64 KiB UTF-8 and up to 12 tags of 32 characters each. description and tags default to empty; enabled defaults to true.
Returns HTTP201 with { skill, permissions }. The new skill starts at version 1. A duplicate slug within the library returns HTTP409 SKILL_SLUG_EXISTS.
Read a skill
/api/v1/skills/{id}Supply the library query fields: workspaceId, scope, and endUserId for a personal library. Returns { skill, permissions, instructionNotice }, including skill.markdown.
Reading a skill does not execute its instructions or grant app access. Dashboard and backend maintenance can read disabled records; the agent skill MCP tools reject disabled skills.
Update a skill
/api/v1/skills/{id}Supply the library fields and required expectedVersion in the JSON body, together with at least one content field: slug, name, description, markdown, tags or enabled.
{
"workspaceId": "11111111-1111-4111-8111-111111111111",
"scope": "end_user",
"endUserId": "customer_123",
"expectedVersion": 1,
"description": "Prepare a meeting brief with source links and open questions."
}A successful edit increments version. A stale edit returns HTTP409 SKILL_CONFLICT; read the current record and reconcile your changes before retrying.
Delete a skill
/api/v1/skills/{id}Supply workspaceId, scope, endUserId when personal, and expectedVersion as query parameters. Returns { deleted: true, id }. A stale version returns HTTP409. Deleting a skill removes its stored instructions; it does not disconnect an app or change an approval rule.
Errors and technical ceilings
HTTP400 indicates invalid input or an unsupported identity override. HTTP403 indicates a denied workspace or shared-write permission. A skill outside the requested library returns HTTP404 SKILL_NOT_FOUND. Concurrent changes and duplicate slugs return HTTP409. The current ceilings of 200 skills per library and 1,000 per organization apply equally to every plan and return HTTP429 when reached.
Use the Skills guide for dashboard and MCP workflows.