---
name: somebody
description: Hire a verified human to do a physical task and get proof back as data. Use when a task needs a body in the world: be somewhere, wait in line, buy at a counter, hold or receive an item, verify a location, hand something off, or answer a question on the spot. Not a delivery API.
---

# Somebody: the human API for agents

Your agent has no body. Somebody gives it one. You post a task made of small
verbs, a verified person nearby does it, and every step closes with a proof
object you can read and threshold without a human looking.

Endpoint: `https://api.somebody.now/v1` · MCP: `https://mcp.somebody.now`
Status: pre-launch, Los Angeles first. This document is the contract we are
building to; shapes may change before launch.

## Verbs

| verb | what a person does | metered |
|---|---|---|
| `go(place, window)` | travels to a location inside a time window; arrival = geofence | per mile + per minute |
| `wait(until)` | holds a spot or waits for a condition (`doors_open`, `delivery_arrives`, `line_under: 10`) | per minute |
| `buy(item, limit, card)` | purchases at a counter with a card issued for this task only; receipt is proof | card scoped to merchant, amount, window |
| `hold(item)` | takes custody; custody is a ledger entry under the runner's name | per day |
| `hand_off(to)` | moves an item to another runner, courier, or you; both sides scan | per handoff |
| `capture(spec)` | photo/video inside the app with nonce, GPS, attestation, model check against `spec` | included |
| `ask(question)` | human judgment on the spot; returns a typed answer | per question |

Compose them. A task is an ordered list of steps. A task set is a list of
tasks with counts (`× 30`) and dependencies (`starts_when: buyer.purchased >= 20`).

## Rules the schema cannot express

1. Every non-GET call accepts `dry_run: true`. Same validation, same pricing,
   nothing dispatched, no charge. Call it first, every time.
2. `post_task_set` returns `status: "pending_approval"` with an `approval_id`.
   A human on your side must approve. Poll `await_approval(approval_id)` or
   subscribe to events. Nothing posts without it.
3. Tasks pass a network safety policy before any runner sees them. Refused
   categories (ticketed events, controlled substances for others, private
   residences, confrontations, anything involving a minor) return
   `POLICY_REFUSED` with the clause. There is no override.
4. Per-merchant, per-event caps are network-owned. `× 300` at one store is
   refused; `× 36` is fine.
5. Partial success is normal. Read `tasks[].state` and `counts`, never assume
   a set completed because the call returned 200.
6. Proof is data. Accept or dispute against `attestation_score`, not by
   looking at the image. Scores under your threshold should be disputed;
   disputes hold escrow and route to review.
7. Idempotency keys on every write. Dry runs never consume them.
8. Runners never see who posted. Do not put your identity in step text.

## Tools

- `get_pricing()` read first; never quote prices from memory
- `post_task_set(task_set, dry_run?)` → quote or `pending_approval`
- `await_approval(approval_id)`
- `get_task_set(id)` → states, counts, `next_action`
- `list_proofs(task_id)` → proof objects
- `accept(task_id, step)` / `dispute(task_id, step, reason)`
- `cancel(task_id)` allowed until a runner is assigned; after that, pays show-up
- `get_contract()` machine-readable: what each proof field means and what you never get

## Proof object

```json
{
  "step": 3,
  "type": "capture",
  "media_url": "...",
  "captured_in_app": true,
  "device_attestation": { "platform": "ios", "valid": true },
  "geo": { "lat": 34.0902, "lng": -118.3861, "inside_fence": true, "accuracy_m": 4 },
  "nonce": "8K2F-91",
  "model_check": { "spec": "sealed pharmacy bag at front door", "passed": true, "reason": "..." },
  "captured_at": "2026-10-16T14:02:11-07:00",
  "attestation_score": 0.97
}
```

## Example

```yaml
task_set: release-0412
tasks:
  - id: buyer
    count: 36
    steps:
      - go: { place: "Best Buy #1142", window: "06:30-08:00" }
      - wait: { until: doors_open }
      - buy: { item: "SKU 6598842", limit: 1, card: issue }
      - capture: "receipt + sealed box in hand"
      - hand_off: { to: collector }
    pay: { show_up: 25, on_purchase: 35 }
  - id: collector
    count: 1
    starts_when: buyer.purchased >= 20
    steps:
      - go: { place: "Best Buy #1142", window: "07:30-10:00" }
      - hold: { from: buyer }
      - go: { place: "UPS Store 4th St" }
      - capture: "tracking label"
    pay: { base: 120, per_item: 4 }
```

Money: pay per task, escrowed on accept, released on accepted proof. Cards
issued to runners and settlement run on Allowance (allowance.network).