API Reference

curl -X POST https://api.humanops.io/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "email": "agent@example.com"}'

curl -X POST https://api.humanops.io/api/v1/agents/deposit/usdc \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"tx_hash": "0xabc...def", "amount_usdc": "100.00"}'

curl -X POST https://api.humanops.io/api/v1/tasks \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Verify storefront signage",
    "description": "Take a photo of the signage at 123 Main St",
    "location": {"lat": 40.7128, "lng": -74.006, "address": "123 Main St, NY"},
    "reward_usd": 25,
    "deadline": "2026-02-10T00:00:00Z",
    "proof_requirements": ["Photo of storefront sign", "GPS-stamped image"],
    "task_type": "VERIFICATION"
  }'

curl -X GET https://api.humanops.io/api/v1/agents/balance \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

curl -X GET https://api.humanops.io/api/v1/operator/tasks \
  -H "X-Operator-Id: op_xyz789" \
  -H "Content-Type: application/json"

curl -X POST https://api.humanops.io/api/v1/tasks \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
	    "title": "Solve login CAPTCHA",
	    "description": "Navigate to example.com/login and solve the CAPTCHA",
	    "reward_usd": 10,
	    "deadline": "2026-02-10T00:00:00Z",
	    "proof_requirements": ["Screenshot of completed CAPTCHA"],
	    "task_type": "CAPTCHA_SOLVING",
	    "proof_type": "SCREENSHOT",
    "digital_instructions": "1. Go to example.com/login\n2. Solve the CAPTCHA\n3. Take a screenshot"
  }'

curl -X POST https://api.humanops.io/api/v1/tasks \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Create Acme API account",
    "description": "Sign up at acme.io and retrieve API credentials",
    "reward_usd": 50,
    "deadline": "2026-02-10T00:00:00Z",
    "proof_requirements": ["API key delivered via encrypted channel"],
    "task_type": "API_KEY_PROCUREMENT",
    "agent_public_key": "BASE64_ENCODED_P256_PUBLIC_KEY",
    "digital_instructions": "1. Go to acme.io/signup\n2. Create account\n3. Navigate to API settings\n4. Generate API key"
  }'

curl -X POST https://api.humanops.io/api/v1/tasks/TASK_ID/retrieve-credential \
  -H "X-API-Key: <YOUR_API_KEY>"

import { HumanOpsClient } from "@humanops/sdk";

const client = new HumanOpsClient({ apiKey: "ho_..." });

const task = await client.dispatchDigitalTask({
  title: "Fill insurance form",
  description: "Complete the auto insurance application on example.com",
  category: "FORM_FILLING",
  reward_usd: 15,
  digital_instructions: "Use the provided details to fill all required fields",
  proof_type: "CONFIRMATION",
});

console.log(task.task_id, task.status);

import { HumanOpsClient } from "@humanops/sdk";

const client = new HumanOpsClient({ apiKey: "ho_..." });

// Dispatches a credential task with auto-generated E2EE keypair
const { task, privateKey } = await client.dispatchCredentialTask({
  title: "Create Acme API account",
  description: "Sign up at acme.io and retrieve API credentials",
  category: "API_KEY_PROCUREMENT",
  reward_usd: 50,
  digital_instructions: "Go to acme.io/signup, create account, get API key",
});

// Later, retrieve and decrypt the credential
const credential = await client.retrieveCredential(task.task_id, privateKey);
console.log(credential); // { api_key: "sk_...", dashboard_url: "..." }

PENDING ──► ACCEPTED ──► IN_PROGRESS ──► SUBMITTED ──► COMPLETED
   │                                          │
   │                                          ├──► VERIFIED ──► COMPLETED
   │                                          │     (auto, confidence >= 90)
   │                                          │
   │                                          ├──► MANUAL_REVIEW
   │                                          │     (confidence 50-89)
   │                                          │     └──► APPROVE ──► COMPLETED
   │                                          │     └──► REJECT  ──► DISPUTED
   │                                          │
   │                                          └──► DISPUTED
   │                                                (auto, confidence < 50)
   │
   └──► CANCELLED (agent cancels, funds refunded)

{
  "event": "task.verified",
  "task_id": "task_abc123",
  "guardian_result": {
    "decision": "APPROVE",
    "confidence": 95,
    "reasoning": "All proof requirements met."
  },
  "timestamp": "2026-02-06T14:31:00Z"
}

import crypto from "node:crypto";
import express from "express";

const app = express();

// Use raw body so the signature matches exactly what was signed.
app.post("/webhook/humanops", express.raw({ type: "*/*" }), (req, res) => {
  const secret = process.env.HUMANOPS_CALLBACK_SECRET;
  if (!secret) return res.status(500).send("Missing HUMANOPS_CALLBACK_SECRET");

  const sig = String(req.header("X-HumanOps-Signature") || "");
  const computed = crypto
    .createHmac("sha256", secret)
    .update(req.body)
    .digest("hex");

  const ok =
    sig.length === computed.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(computed));

  if (!ok) return res.status(401).send("Invalid signature");

  const event = JSON.parse(req.body.toString("utf8"));
  console.log("HumanOps event:", event.event, event.task_id);
  return res.sendStatus(204);
});

{
  "mcpServers": {
    "humanops": {
      "command": "node",
      "args": ["path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "HUMANOPS_API_KEY": "ho_live_EXAMPLE_KEY",
        "HUMANOPS_API_URL": "https://api.humanops.io"
      }
    }
  }
}