The WorkerKit API.

Get started

Signup, approval and funding.

A new user can sign up during approval. An existing user signs in with Google, Microsoft or an email OTP in the WorkerKit browser page. Signing in is separate from granting access: the account admin chooses the account, permissions and expiry, then approves. Never request an OTP, provider key, fleet credential or payment details in conversation.

For an API client with secure credential storage, POST https://api.workerkit.ai/api/auth/agent/requests with name, clientLabel and a scopes array. This bootstrap route needs no fleet key. Keep pollSecret private; display only approvalUrl, userCode and expiresAt. Requests expire after ten minutes.

Optionally POST /api/auth/agent/requests/{requestId}/email with { "email": "user@example.com" } and X-Poll-Secret. Email binds the request to that signed-in address; the code stays with the initiating client. Email delivery does not reveal whether an account exists.

GET /api/auth/agent/requests/{requestId} with X-Poll-Secret at most once every five seconds. When status is approved, POST the same path plus /redeem with that header. Only this response contains managerKey; put it directly in credential storage, never a transcript. /cancel cancels pending access or revokes this request's redeemed key after a lost response. A leaked approval URL cannot collect a key. Honor Retry-After on 429.

Do not import bootstrap operations into a hosted assistant that cannot keep the polling secret and redeemed key outside model-visible results. Use its standard OAuth integration instead.

After connection, call key_info, then onboarding_get (optionally with the intended model provider). Readiness here checks account model funding; check the selected worker's permissions, deployment and budgets before running. Empty fleets are valid. Consent defaults to read-only scopes and 30 days; install, deploy, run, connections and purchases need their explicit scopes. An expired or revoked grant needs fresh approval. Revoking access does not stop already scheduled workers: pause those separately.

Runtime permissions require the human to review a shared account ceiling per UTC day and month. onboarding_get.spendPolicy reports its limits and reserved allowance. Each hosted run, including schedules, reserves its model ceiling plus possible BYOK fees. Reservations remain until the window resets even after a cheaper or failed run. Agents cannot raise this ceiling through budget, clone or deployment operations. A human_spend_ceiling refusal requires waiting or fresh human approval. Metered app charges and wallet purchases are separate.

BYOK: send the person byokSetupUrl from onboarding_get and ask them to select the returned account in Settings. Provider keys go directly into that trusted page. A client that already has a provider secret in protected storage can use model_key_set with manageConnections; never echo the secret. BYOK can still incur platform fees, metered app charges and decision costs.

Wallet: wallet_get requires readWallet. With explicit permission for the amount and requestWalletTopUp, call wallet_checkout_create with amountUsd and a unique idempotencyKey (HTTP: POST /api/manage/wallet/checkouts, Idempotency-Key header). Reuse the same key and amount on retries. Show amountUsd, feeUsd, totalUsd and the returned checkoutUrl; the person reviews and pays in Stripe Checkout. This grants no unattended charging authority.

wallet_checkout_get (GET /api/manage/wallet/checkouts/{sessionId}) reports pending, expired, paid_pending_credit or credited. A checkout URL, redirect or paid session is not wallet credit. Poll no faster than every five seconds and proceed only on credited; check worker readiness again. requestWalletTopUp alone can inspect only checkouts created by that key. readWallet can inspect the account's checkouts.

Two surfaces

Your fleet, and the public catalog.

The fleet is yours, so it is never anonymous; the catalog is public, so it is never walled behind a sign-in. Each surface has an OpenAPI 3 document of its own.

If your platform speaks MCP, use the WorkerKit MCP server instead: the same operations, with the sign-in discovered from the server.

Meta Muse connects this way, holding a manager key and calling the fleet directly. Its walkthrough, written for the Muse agent, is Set up WorkerKit in Meta Muse.

Connect with an API key

One key, the scopes you choose.

An account admin creates a key under Fleet access, picks its scopes, and reads it once: it is never shown again. Send it on every fleet request as Authorization: Bearer pe_mgr_.... The key reaches the fleet only; it grants no access to any connected app.

Call GET /api/manage/workers/key-info first to learn what your key can do: it returns the account name, the key's scopes and expiry, and serverTimeUtc. Any valid key may ask.

Connect with OAuth2

Authorization code with PKCE.

Platforms that register themselves connect with no key to paste: the authorization-code flow with PKCE (S256), dynamic client registration, and the same scope names as above. At consent an account admin picks or creates a manager key at https://workerkit.ai/mcpauth, and that key's scopes are the token's reach.

A platform that cannot do PKCE or dynamic client registration should use the API key path today.

Quick start

Five requests.

The three directory calls need nothing. The two fleet calls need a key; replace the placeholders with the ids the responses return.

• The directory, no auth: what WorkerKit is and when to use it, written for an agent curl https://api.workerkit.ai/api/directory/mcp/about
• The directory, no auth: the filter vocabulary curl https://api.workerkit.ai/api/directory/mcp/overview
• The directory, no auth: search kits curl "https://api.workerkit.ai/api/directory/mcp/kits?q=inbound+leads&page=1&pageSize=20"
• Your fleet: list every worker curl https://api.workerkit.ai/api/manage/workers \ -H "Authorization: Bearer pe_mgr_..."
• Your fleet: run a worker, then poll its events every 3 to 5 seconds curl -X POST https://api.workerkit.ai/api/manage/workers/{workerId}/run \ -H "Authorization: Bearer pe_mgr_..." \ -H "Content-Type: application/json" -d '{}' curl "https://api.workerkit.ai/api/manage/workers/runs/{runId}/events?afterSeq={lastSeq}" \ -H "Authorization: Bearer pe_mgr_..."

A worker is addressed by its workerId GUID, which every response that names a worker returns; the older sequential integer id still resolves and is deprecated.

Classification on demand

Create a decision worker from your questions.

Categorize, score or triage connected data, then reuse and adjust the worker.

Reuse an existing worker or decision kit when its questions fit. For a custom classification task, creation compiles a supported source recipe and typed questions into a private kit and an installed decision worker. Optional deploy:true adds deployment; creation never starts a run or adds a schedule. The kit can be edited and published later through the normal kit lifecycle.

• Creation request JSON { "requestId": "customer-email-triage-001", "name": "Customer email triage", "source": { "recipe": "email-previews", "args": { "after": "-7d" } }, "questions": [ { "key": "category", "type": "choice", "instructions": "Which category best describes this message?", "options": { "followup": "A customer asks for a reply", "other": "A different topic" } } ], "confidenceFloor": 0.7, "maxItems": 20, "deploy": false }

Discover recipes with GET /api/directory/mcp/authoring/tools?purpose=decision and read GET /api/directory/mcp/authoring/guide?section=decision; both are anonymous. Check connections with GET /api/manage/apps, then send the request to POST /api/manage/decision-workers. Use the returned worker with the existing deployment, run and instruction endpoints in the workers OpenAPI document. Running needs runWorkers; results need readRuns. Saved setup answers adjust categories/levels; a structural question or source change needs a revised kit and a replacement install. Check receipt status, coverage, omissions, warnings and cost before claiming completion.

Start with email-previews, calendar-events or sheets-rows. These recipes return judgments without app writes. Email previews do not include full threads; calendar events are invitation data, not transcripts; Sheets needs a Google file ID, a finite tab-qualified range and a columns map. A connected app alone does not make every tool a supported source. Source filters select evidence, not permissions: the Sheets recipe grants spreadsheet reads across the linked Drive account.

Supply 1–8 questions: choice with named options, score with ordered levels, or noul for the probability of a statement. Choice adds unclear automatically. Set an explicit confidenceFloor between 0 and 1; it routes uncertainty and does not promise accuracy. maxItems is 1–50, default 20. Creation requires publishKits and installKits; optional deployment also needs manageDeployments.

Use a fresh requestId for each new worker. Retry with the same ID and identical body to recover the original receipt; a changed body returns 409. The response includes tokenId for MCP/CLI worker commands, stable workerId, kitSlug, readiness and nextCall. A deploymentError means the worker already exists: fix deployment on that worker. The receipt is a snapshot; check current worker readiness before running. No worker API secret is returned.

Operating rules

What the backend enforces.

Per-account limits, the polling cadence, and the responses that are terminal rather than transient. Every row is a fact of the API, not advice.

Errors

Three envelopes, named codes.

Every fleet and kits endpoint outside the run family answers with { "error": "Not found", "message": "...", "code": "not_found" }: error is a human label and code is the machine code to branch on. The run family (run, runs, the account run feed, run detail, run events, the run transcript, cancel, clear report, score; a bulk run answers 200 and carries the same codes per item in errorCode) answers with { "error": "not_found", "message": "..." } for refusals raised by the run engine itself: no code field at all, and the machine code in error. Their pre-flight refusals keep the first shape, so the 403, the 422 and the not_language_worker / not_decision_worker 409s above carry the machine code in code even on a run endpoint.

Two exceptions on the first side: both 402s name themselves in error and carry no code field, as { "error": "limit_exceeded", "limitType": "...", "currentCount": 0, "maxAllowed": 0, "message": "..." } on a kit install and { "error": "feature_gated", "feature": "...", "upgradeTrigger": "...", "message": "..." } on a schedule or memory write. And the anonymous catalog surface answers in a third shape of its own, { "statusCode": 404, "message": "Kit not found.", "errorType": "ResourceNotFound", "correlationId": "...", "timestamp": "..." }, with neither field: branch on code when it is present and on error otherwise.

The auth failures, in the order a new connector meets them, all carry the first shape: