Build a kit over the API.

Before you start

A key, and the requests a build makes.

An account admin creates the key under Fleet access and reads it once. Keep it in WK_MANAGER_KEY, the variable the requests below and the wk CLI both read.

Create the key at Fleet access, or connect with OAuth2 as the API page describes. Both specs below describe every request, its body and its responses.

The specs

Two OpenAPI documents.

Step 1

Read the guide and the vocabulary.

No key needed. The guide says which kind of kit the job is and how to fill every field; the vocabulary holds the only keys a kit may grant.

• The guide, no auth: index first, then schema and rules curl "https://api.workerkit.ai/api/directory/mcp/authoring/guide?section=index" curl "https://api.workerkit.ai/api/directory/mcp/authoring/guide?section=schema"
• One app, no auth: what a worker can do on it, and its exact keys curl "https://api.workerkit.ai/api/directory/mcp/authoring/tools?app=tasks" curl "https://api.workerkit.ai/api/directory/mcp/authoring/vocabulary?app=tasks"

Read index first, then schema and rules; skill, instruction, slots, state, example and selfcheck as the kit needs them, decision for a classifier, and workers before declaring workerSlots. Read the vocabulary per app for the apps you use, and copy keys from it: there is no "all" shorthand.

Step 2

Write kit.json.

One JSON object: the listing, the content and the app descriptions. A complete example is on the build hub, and the guide's example section has a longer one beside a decision kit. Set "visibility": "private" for the first publish, and add publisherName to the account's first publish only.

Step 3

Validate it.

The dry run judges the body as a public publish and reports every section at once. Nothing is created.

• Validate the file you will publish curl -X POST https://api.workerkit.ai/api/manage/kits/validate \ -H "Authorization: Bearer $WK_MANAGER_KEY" \ -H "Content-Type: application/json" \ --data @kit.json

Read canPublish first. errors[] would block the publish and warnings[] would not, each with its section; lintWarnings are advisory nudges about the instructions; requiredInputs lists the install-form fields your text declared; manifestPreview is the exact permission manifest that would ship. Fix and repeat until canPublish is true.

Step 4

Publish it private.

The response is the listing: its slug, its status, and any lint warnings.

• Publish it, with "visibility": "private" in the body curl -X POST https://api.workerkit.ai/api/manage/kits \ -H "Authorization: Bearer $WK_MANAGER_KEY" \ -H "Content-Type: application/json" \ --data @kit.json

A publish is not idempotent: every success creates another listing. After a timeout, read GET /api/manage/kits/mine before you send it again. A private kit installs only on your account and skips the public scan; the same request publishes from a worker you already tuned when the body carries sourceWorkerId instead of content (the body).

Step 5

Install it, deploy it, run it once.

Installing creates the worker; deploying is what lets it run at all; one run shows whether the instructions and the access hold.

• Read the install form curl https://api.workerkit.ai/api/manage/kits/{slug}/install-preview \ -H "Authorization: Bearer $WK_MANAGER_KEY"
• Install and deploy, answering any requiredInputs the preview lists curl -X POST https://api.workerkit.ai/api/manage/kits/{slug}/install \ -H "Authorization: Bearer $WK_MANAGER_KEY" \ -H "Content-Type: application/json" \ -d '{"deploy": true}'
• Run it with the new worker's id, and wait for the receipt curl -X POST https://api.workerkit.ai/api/manage/workers/{workerId}/run \ -H "Authorization: Bearer $WK_MANAGER_KEY" \ -H "Content-Type: application/json" \ -d '{"waitSeconds": 55}'

The install response carries the new worker's workerId for the run request, and its key and any webhook signing secrets exactly once: store them before you discard the response. readiness says whether an app still needs connecting, and connectAppsUrl is where a person connects it. Deploying needs manageDeployments beside installKits; reading the receipt needs readRuns.

Step 6

Keep improving it privately.

Public publishing and promotion are temporarily paused. Send visibility private when replacing or validating your kit.

• Validate the private version against the kit it replaces curl -X POST "https://api.workerkit.ai/api/manage/kits/validate?kitRef={slug}" \ -H "Authorization: Bearer $WK_MANAGER_KEY" \ -H "Content-Type: application/json" \ --data @kit.json
• Replace it, with "visibility": "private" in the body curl -X PUT https://api.workerkit.ai/api/manage/kits/{slug} \ -H "Authorization: Bearer $WK_MANAGER_KEY" \ -H "Content-Type: application/json" \ --data @kit.json

Private kits remain available to your account. Public publishing, public replacement and relisting return an error while the pause is in effect.

Send a body on every POST, at least {}: a POST with no body is refused at the edge before it reaches the API, which bites the bodyless unpublish, relist and make-private calls first.

Errors

The responses to branch on.

Edit, unlist and delete are on the build hub. The same steps run from your AI assistant and the terminal.