Skip to content
Weavz
Menu

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

GET/api/v1/skills
QueryMeaning
workspaceIdRequired workspace UUID
scopeend_user or workspace
endUserIdRequired external identity for a personal library
querySearch names, slugs and descriptions, up to 120 characters
tagMatch one tag
includeDisabledtrue to include disabled skills for maintenance; default false
limit / offsetPage 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

POST/api/v1/skills
json
{
  "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

GET/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

PATCH/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.

json
{
  "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

DELETE/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.