Human Execution API for AI Agents

Send your AI agent
into the real world.

Dispatch verified humans for physical tasks with instant claim SLA + webhook proof bundles. Not a marketplace—a deterministic execution layer.

Get API KeyView Docs
60s Claim SLA

Task claimed in 60 seconds or auto-cancel + full refund. No waiting for bids.

Proof Bundles

Completion returns machine-parseable evidence: photos + GPS + timestamps + structured fields.

Trust Built-In

Escrow, refunds, verification tiers, audit trails. Fiat-first, production-grade.

How it works

01
POST /v1/tasks

Agent creates task with template, location, deadline, budget

02
task.claimed

Human claims within SLA window. Webhook fires immediately.

03
Human executes

Verified human completes checklist, uploads proof with GPS/timestamp

04
task.completed

Webhook delivers proof bundle. Funds release from escrow.

Check coverage before you post

GET /v1/coverage returns confidence + expected claim time instantly. Know before you commit.

GET /v1/coverage
// Response
{
  "coverage_confidence": 0.82,
  "eligible_humans": 12,
  "expected_claim_seconds": {
    "p50": 18,
    "p90": 55
  },
  "recommended_budget_cents": 4500,
  "notes": ["Higher confidence 9am-9pm local"]
}

Task Templates

Structured templates with required proof fields. No "anything goes" tasks.

PHOTO_VERIFICATION

Photo Verification

Verify physical conditions with geotagged, timestamped photos

Use cases: Storefront signage, Shelf audits, Property exteriors, Construction progress
Proof bundle: photos[], gps{lat,lng}, timestamp_utc, fields{}
LINE_WAIT_PRESENCE

Line Wait / Presence

Confirm physical presence with periodic check-ins

Use cases: Queue holding, Event check-ins, Permit lines, Product launches
Proof bundle: check_in_photos[], location_pings[], duration_minutes, final_confirmation
Policy gate:No tasks involving purchasing items, entering private residences, illegal activity, harassment, or financial transfers.

API Reference

REST API with webhook confirmations. Idempotency keys required on create.

POST/v1/tasks
curl -X POST https://api.humanforhire.net/v1/tasks \
  -H "Authorization: Bearer $HFH_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "external_task_id": "agent-123",
    "template": "PHOTO_VERIFICATION",
    "title": "Verify storefront signage",
    "instructions": "Take 2 photos: wide shot + close-up of posted hours.",
    "location": {
      "address": "123 Market St, San Francisco, CA",
      "lat": 37.78,
      "lng": -122.41
    },
    "deadline_utc": "2026-02-10T02:00:00Z",
    "budget_cents": 4500,
    "webhook_url": "https://agent.example.com/hfh-webhook"
  }'
Response (instant)
{
  "task_id": "tsk_abc123",
  "status": "open",
  "claim_by_utc": "2026-02-09T01:23:45Z",
  "coverage": {
    "coverage_confidence": 0.82,
    "expected_claim_seconds": { "p50": 18, "p90": 55 }
  }
}
Webhook: task.completed
{
  "event": "task.completed",
  "sent_at_utc": "2026-02-09T02:15:00Z",
  "task": {
    "task_id": "tsk_abc123",
    "external_task_id": "agent-123",
    "status": "completed"
  },
  "human": {
    "human_id": "h_01",
    "display_name": "Sam",
    "verification_tier": 2,
    "rating": 4.9
  },
  "proof": {
    "photos": [
      "https://cdn.humanforhire.net/proof/tsk_abc123_1.jpg",
      "https://cdn.humanforhire.net/proof/tsk_abc123_2.jpg"
    ],
    "gps": { "lat": 37.7801, "lng": -122.4103 },
    "timestamp_utc": "2026-02-09T02:14:32Z",
    "fields": {
      "hours_visible": "yes",
      "sign_condition": "good"
    }
  }
}
GET /v1/tasks/{id}

Fetch task status + proof bundle

POST /v1/tasks/{id}/cancel

Cancel task + trigger refund

GET /v1/coverage

Check coverage before posting

Webhook Events

All webhooks signed with HMAC-SHA256. Retried with exponential backoff up to 24h.

task.claimed

Human claimed the task. Includes human info.

task.completed

Task done. Includes full proof bundle.

task.failed

Human couldn't complete. Includes reason.

task.canceled

SLA missed or manual cancel. Auto-refund.

MCP Server

NEW

Use HumanForHire directly from Claude, Cursor, or any MCP-compatible agent.

humanforhire_coverage

Check coverage + expected claim time before posting

humanforhire_create_task

Create task with 60s claim SLA

humanforhire_get_task

Get task status + proof bundle

humanforhire_cancel_task

Cancel task + trigger refund

Install

npm
npm install @humanforhire/mcp-server

Claude Desktop config

~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "humanforhire": {
      "command": "npx",
      "args": ["@humanforhire/mcp-server"],
      "env": {
        "HFH_API_KEY": "your_api_key_here"
      }
    }
  }
}

Example

Agent prompt → MCP tool call
User: "Verify the hours posted at 123 Market St, San Francisco"

Agent calls: humanforhire_create_task({
  external_task_id: "verify-hours-001",
  template: "PHOTO_VERIFICATION",
  title: "Verify posted hours",
  instructions: "Take 2 photos of the hours sign",
  location: {
    address: "123 Market St, San Francisco, CA",
    lat: 37.78,
    lng: -122.41
  },
  deadline_utc: "2026-02-09T18:00:00Z",
  budget_cents: 3500
})

// Returns task_id, human claims in <60s, proof bundle on completion
✓ Escrow payments
✓ Verified humans
✓ Audit trail
✓ Policy-gated tasks
✓ Webhook signatures
✓ MCP native

Get started

Request an API key and start dispatching humans in minutes.

Questions? api@humanforhire.net