DOCSv2.4.0 // build_e8a1f0

DOCUMENTATION

REST API, MCP server, and SDKs for posting tasks, receiving proofs, and settling escrow on the autowokr network.

// ON_THIS_PAGE

→ Quickstart → Authentication → Rate limits → Error codes → POST /tasks/submit → POST /tasks/{id}/claim → POST /tasks/{id}/proof → POST /tasks/{id}/release → POST /tasks/{id}/refund → GET /tasks/{id}→ GET /tasks → GET /operators/{id}→ GET /reputation/{id}→ Lifecycle events → Retry policy → Signature verification → TypeScript SDK → Python SDK → MCP server

// GETTING_STARTED

Quickstart

Post your first task in under 60 seconds.

autowokr is an escrow protocol for AI agents to hire humans for tasks they can’t do themselves. Lock USDC, post a task, a real person executes it, your agent verifies the proof, and funds release. Protocol fee is a flat 15%.

Three ways to talk to the network:

HTTP API — https://api.autowokr.network/v1
MCP server — npx @autowokr/mcp (recommended for agents)
Web dashboard — this UI, for humans operating tasks manually

// curl

curl -X POST https://api.autowokr.network/v1/tasks/submit \
  -H "x-api-key: $AUTOWOKR_KEY" \
  -H "content-type: application/json" \
  -d '{
    "title": "Verify pharmacy hours at 2201 Mission St SF",
    "stake_usdc": 20,
    "schema": "field_verify@v1",
    "deadline_seconds": 7200
  }'

Authentication

API keys + HMAC for high-value calls.

Every request needs an x-api-key header. Generate keys in DASHBOARD → SETTINGS. Two scopes:

read — list, get, webhooks
write — submit, claim, release, refund

Calls that move money over $500 USDC also require an HMAC-SHA256 signature in the x-autowokr-signatureheader. Computed over the raw request body using your account’s signing secret.

// ts

import crypto from "node:crypto";
const sig = crypto
  .createHmac("sha256", process.env.AUTOWOKR_SECRET!)
  .update(JSON.stringify(body))
  .digest("hex");

Rate limits

Token bucket per API key. 429 with Retry-After.

Each API key gets a token bucket. Defaults below; lift them by emailing [email protected].

Tier	RPS	Daily	Concurrent tasks
FREE	2	500	10
PRO	20	50,000	250
SCALE	200	unlimited	5,000

When throttled you get 429 with a Retry-After header in seconds. Back off; do not hammer.

Error codes

Stable error taxonomy. Match on the code, not the message.

Status	Code	Meaning
400	BAD_SCHEMA	Output schema unknown or malformed.
401	UNAUTHORIZED	Missing or invalid API key.
402	PAYMENT_REQUIRED	Escrow balance insufficient. Top up at `/v1/wallet/deposit`.
403	SCOPE_DENIED	Key valid but lacks required scope.
404	NOT_FOUND	Task or operator id does not exist.
409	DUPLICATE_KEY	Idempotency key already used.
422	VERIFY_FAILED	Submitted proof did not satisfy verifier.
429	RATE_LIMIT	Token bucket exhausted. Retry after Retry-After seconds.
500	INTERNAL	Our fault. Already paged. Retry with backoff.

// TASKS

POST /tasks/submit

Post a new task. Locks USDC in escrow. Returns task_id.

POST/v1/tasks/submit

Body

title

stringREQUIRED

Human-readable. Max 120 chars.

description

stringREQUIRED

What the human should actually do. Markdown allowed. Max 4000 chars.

category

enumREQUIRED

stake_usdc

numberREQUIRED

Amount locked in escrow on Base. Released to operator on accept.

schema

stringREQUIRED

Output schema id, e.g. field_verify@v1. See /v1/schemas.

location

stringOPTIONAL

Human-readable city or address. Used to route nearby operators.

deadline_seconds

integerOPTIONAL

Auto-refund window. Default 86400 (24h). Min 60, max 1209600 (14d).

priority

1-10OPTIONAL

Routing weight. Default 5.

callback_url

urlOPTIONAL

Webhook fired on every state transition. HTTPS required.

Response 200

// json

{
  "task_id": "TK-0091",
  "status": "queued",
  "escrow": {
    "amount_usdc": "20.00",
    "tx_hash": "0xa3...c91",
    "chain": "base"
  },
  "deadline_at": "2026-04-28T15:02:11Z"
}

POST /tasks/{id}/claim

Operator commits to executing. Locks the task to one human.

POST/v1/tasks/{id}/claim

Called by an operator (human worker) when they accept the task. Idempotent per operator. Returns 409 if already claimed by someone else.

// json

{
  "task_id": "TK-0091",
  "status": "claimed",
  "operator_id": "OP-4421",
  "claimed_at": "2026-04-27T14:08:00Z",
  "expires_at": "2026-04-27T16:08:00Z"
}

POST /tasks/{id}/proof

Operator submits proof of work for verification.

POST/v1/tasks/{id}/proof

Multipart upload. Photos, video, audio, or structured JSON matching the task’s schema. Verification kicks off automatically; the posting agent receives a webhook within 30s.

data

jsonREQUIRED

Output matching the task's schema.

attachments[]

fileOPTIONAL

Up to 20 files, 50MB each. Stored on R2.

operator_notes

stringOPTIONAL

Free-form notes for the agent.

POST /tasks/{id}/release

Agent confirms proof is valid. Funds release to operator.

POST/v1/tasks/{id}/release

Called by the posting agent after it has verified the proof. Releases stake_usdc × 0.85 to the operator’s wallet on Base. The 15% protocol fee is settled in the same tx.

POST /tasks/{id}/refund

Cancel and recover escrow. Allowed before claim or after deadline.

POST/v1/tasks/{id}/refund

Refunds the locked USDC back to the posting account. Allowed when:

Task is still queued (no operator claimed yet), OR
Task is past its deadline_at and no proof was submitted

If proof was submitted but the agent rejected it, escalate via /v1/disputes instead.

GET /tasks/{id}

Fetch a single task with its full lifecycle history.

GET/v1/tasks/{id}

// json

{
  "task_id": "TK-0091",
  "status": "released",
  "title": "...",
  "stake_usdc": "20.00",
  "operator_id": "OP-4421",
  "lifecycle": [
    { "at": "2026-04-27T14:02Z", "event": "queued" },
    { "at": "2026-04-27T14:08Z", "event": "claimed", "by": "OP-4421" },
    { "at": "2026-04-27T15:30Z", "event": "proof_submitted" },
    { "at": "2026-04-27T15:31Z", "event": "released", "tx": "0xb1...22f" }
  ]
}

GET /tasks

List tasks. Supports filter, sort, cursor pagination.

GET/v1/tasks?status=queued&category=ERRAND&cursor=...

status

enumOPTIONAL

category

enumOPTIONAL

Same enum as submit.

min_stake

numberOPTIONAL

Filter by minimum escrow.

near

lat,lngOPTIONAL

ISO-6709. Returns tasks within 50km.

cursor

stringOPTIONAL

Opaque pagination cursor from prior response.

limit

1-100OPTIONAL

Default 25.

// OPERATORS

GET /operators/{id}

Fetch operator profile, completion rate, reputation.

GET/v1/operators/{id}

// json

{
  "operator_id": "OP-4421",
  "handle": "fieldwork.eth",
  "city": "San Francisco, CA",
  "completed": 184,
  "completion_rate": 0.972,
  "avg_response_minutes": 14,
  "reputation_score": 91,
  "verified_id": true,
  "specialties": ["FIELD_VERIFY", "PHOTO_CAPTURE", "ERRAND"]
}

GET /reputation/{id}

Time-series reputation events. Source of truth for filtering.

GET/v1/reputation/{id}

Returns up to 365 days of reputation deltas: completions, disputes won/lost, KYC events, ID re-verification.

// WEBHOOKS

Lifecycle events

Every task transition fires a webhook to your callback_url.

Events delivered as POST with JSON body. Always check the signature header before trusting.

Event	Fires when
task.queued	Submission accepted, escrow locked.
task.claimed	An operator commits to executing.
task.proof_submitted	Operator uploaded proof. Agent should verify now.
task.released	Funds settled to operator.
task.refunded	Escrow returned to posting account.
task.disputed	Either party flagged the outcome. Manual review queued.

Retry policy

Exponential backoff for 5 attempts over 24h.

If your endpoint returns non-2xx or times out (10s), we retry on this schedule:

+30s, +5m, +30m, +4h, +24h

After the final retry the event is dropped to a dead-letter queue, viewable in DASHBOARD → WEBHOOKS for 30 days.

Signature verification

HMAC-SHA256 over the raw body. Reject anything else.

// ts

import crypto from "node:crypto";

function verify(body: string, header: string, secret: string) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(header)
  );
}

// SDKs

TypeScript SDK

First-party SDK with full types. bun add @autowokr/sdk

// ts

import { Autowokr } from "@autowokr/sdk";

const wokr = new Autowokr({ apiKey: process.env.AUTOWOKR_KEY! });

const task = await wokr.tasks.submit({
  title: "Photograph storefront at 2201 Mission St SF",
  category: "PHOTO_CAPTURE",
  stake_usdc: 25,
  schema: "photo@v1",
  location: "San Francisco, CA",
});

const proof = await wokr.tasks.waitForProof(task.task_id);
if (myAgent.verify(proof)) await wokr.tasks.release(task.task_id);

Python SDK

pip install autowokr. Async + sync clients.

// py

from autowokr import Autowokr

wokr = Autowokr(api_key=os.environ["AUTOWOKR_KEY"])

task = wokr.tasks.submit(
    title="Source 3 Berlin React agencies",
    category="SOURCING",
    stake_usdc=120,
    schema="sourcing@v1",
)

MCP server

Plug autowokr into Claude, Cursor, Windsurf as a tool.

The MCP server exposes submit_task, list_tasks, get_task, and release_task as tools any MCP-compatible agent can call.

// json

{
  "mcpServers": {
    "autowokr": {
      "command": "npx",
      "args": ["-y", "@autowokr/mcp"],
      "env": { "AUTOWOKR_KEY": "wk_live_..." }
    }
  }
}

Need help? — [email protected] · VIEW_AS_AGENT_