# Body API Specification v0.1
*Status: draft for comment. Licence: open specification. Stringer is the reference broker implementation; nothing in this document is specific to it.*

## 1. Purpose

The Body API defines how an autonomous software agent acquires temporary sensing and action in the physical world. It specifies a small set of verbs, a capability discovery model, a consent and trust model and pricing metadata, such that any embodiment (a person with a phone, a fixed camera, a drone, a robot) can fulfil any conforming request interchangeably.

The design goal is interface stability across a hardware transition: an agent written against v0.1 in a world of humans holding phones should run unchanged in a world of robot fleets.

## 2. Terminology

**Agent.** The requesting software entity. Holds a wallet and a reputation.
**Broker.** The marketplace that receives requests, quotes, matches, escrows and settles.
**Embodiment.** Any physical fulfilment unit: human, phone, robot, drone, fixed sensor.
**Provider.** The party operating an embodiment and receiving payment.
**Mission.** One accepted request, from quote to settlement.
**Owner.** The human responsible for an agent, its wallet and its caps.

## 3. Design principles

1. **Implementation blindness.** No verb, parameter or response may reveal or require a particular *device*: an agent learns what a body can do, never what it is or where it stands, and nothing lets it name an individual. An agent MAY require a *shape* — `require.form`: `handheld` is a phone in a person's hand; `wheeled`, `legged`, `tracked`, `humanoid`, `aerial`, `fixed` are machines — because a person and a robot are different instruments with different consent and different steering (`live.md`: words steer a person, `control` steers a machine). That ruling is dated 2026-09-04 and supersedes this document's earlier "never send a human".
2. **No person-targeting primitive.** The schema contains no way to express "observe, follow, identify or locate an individual". This is a structural refusal, not a policy filter.
3. **Observations by default.** The default deliverable is structured observations produced at the edge. Raw media is a higher consent tier and a higher price.
4. **Consent is tiered and explicit.** Every request declares its tier; every embodiment declares the tiers it will serve.
5. **Everything is priced.** Own-device work is priced by the broker's rate and minted to the requester; an agent may cap it with `max_price`. Stranger work is priced by the agent's `offer_price`, which is REQUIRED (`E_PRICE_REQUIRED`); a supplier's price floor has no field today (§5). Quotes precede acceptance, and a quote dies five minutes after submit.
6. **Everything is logged.** Missions produce an immutable receipt visible to the agent, the provider and the owner.

## 4. Verbs

All verbs return a `mission_id` and stream lifecycle events. Times are ISO 8601; money is minor units — the ledger's unit is the US cent, and `CRD` / `CRDW` are the credit tiers (`money.md`). **The request shape the broker reads is the field table in `/v0/reference/missions.md`**, bound to the schema by a test: `verb_chain`, `prompt`, `consent_tier`, `location`, `session_mode`, `media`, `needs` / `prefer`, `require`, `allow_stranger`, `offer_price`, `pay_instrument`. The verbs the broker knows are `observe`, `goto` and `inspect`; the rest of this section describes intent, and §4.3 and §4.5 are designs, not routes.

### 4.1 observe
Passive sensing at a location.
```json
{
  "verb_chain": [{"verb": "observe", "duration_s": 120}],
  "prompt": "General street scene: weather, crowds, which shops are open.",
  "consent_tier": 0,
  "location": {"lat": 55.9533, "lng": -3.1883, "radius_m": 150},
  "session_mode": "async_delegated",
  "max_price": 40
}
```
There is no `modality`, `motion` or `expires_at`: what leaves the device is `media` (`text`, `image`, `video`, `audio`, `live_video`), how the body moves is a routine named on the step (`routine`, `routine_params`; `/v0/routines`), and a quote expires five minutes after submit. Until 2026-09-05 this example showed all three fields and a `max_price` object; three cold agents each listed it against the served schema as a contradiction, and a body built from this page alone would have sent it.

### 4.2 goto
Move the active embodiment to a location. Usually composed before other verbs, as a step in `verb_chain` with its own `location`.

### 4.3 ask — NOT IMPLEMENTED
A question posed by the embodiment to a person at a location (a shopkeeper, a passer-by, a venue). **A request naming `ask` is refused today; the verbs are `observe`, `goto`, `inspect`, and adding one is an owner ruling (they are published, declared by every device, matched on and priced).** The design stays here as the v0.2 candidate it is.
```json
{
  "verb": "ask",
  "location": {...},
  "question": "Is the gallery's east wing open today?",
  "disclosure": "asking on behalf of an AI agent",   // mandatory, non-empty
  "consent_tier": 3,
  "max_price": {...}
}
```

### 4.4 inspect
Close examination of a specified object or surface: read this meter, photograph this menu, check this label. The target must be an object, never a person.

### 4.5 call — NOT IMPLEMENTED
A voice call placed on the owner's behalf. **Refused today, like `ask`.** Constraints are normative: the callee MUST be on the owner's approved contact list, the call MUST open with disclosure of the agent's identity and purpose and impersonation is prohibited. Brokers MUST refuse `call` requests from agents below the attested-tier reputation floor.
```json
{
  "verb": "call",
  "contact_ref": "owner_contact:7f3a",   // opaque reference, never a raw number
  "purpose": "Confirm he received this morning's email and note any reply.",
  "script_constraints": ["disclose_agent", "no_negotiation", "max_120s"],
  "consent_tier": 3,
  "max_price": {...}
}
```

### 4.6 Session controls
There is no `wait`, `extend` or `end`. The agent-side controls are `accept` (escrows and dispatches), `cancel` (free before a claim; once a live provider is publishing it is `claimed_live` and costs the full quote — `missions.md` §7C) and, on a `live_interactive` mission, the directive channel: `text` to a person, `control` to a machine, `stop` to either, never refused (`live.md`). A mission runs for the sum of its steps' `duration_s`. Providers may end any mission unilaterally at any time (`terminate`, with a reason code); a safety termination is not a fault of theirs, and `responses.md` says not to downgrade them for it.

### 4.7 Composition
Requests are chained as `verb_chain`, in order: `goto` then `observe` then `inspect`. A chain is quoted and escrowed as one mission.

## 5. Capability discovery

Every embodiment declares what it can do to the broker, at pairing and again
whenever it changes. **The declaration's real shape is the one in
`/v0/reference/device-api.md` §1 and `/v0/reference/device-profile.md`
(`claims`)** — `kind`, `verbs`, `consent_tiers`, `sensing`, `redaction`,
`routines`, `form`, `mobility`, `expressive`, `free_text_steerable`,
`name_detection`, `autonomy` — and that is the only shape the broker reads:

```json
{
  "kind": "robot",
  "verbs": ["observe", "inspect"],
  "consent_tiers": [0, 2],
  "sensing": {"classify": "basic", "count": "basic", "ocr": "basic"},
  "redaction": {"post": "full", "live": "full", "tags": ["face_blur"], "max_fps": 3.3, "frame_budget_ms": 298},
  "routines": {"observe": {"default": "static", "offers": {"sweep": {"pan_deg": [-59, 59], "dwell_s": [0.5, 10]}}}},
  "form": "wheeled",
  "free_text_steerable": false
}
```

⚠️ Until 2026-09-05 this section showed a second, older shape
(`capabilities`, `modalities`, `motion`, `floors`, `trust`) that nothing on the
broker has ever read. A body built from the documents alone sent it, paired
successfully, and was never matched — the declaration was unknown and unknown is
never capable. Coverage is its own route (`POST /v0/provider/coverage`), trust
is the broker's to compute, and **a supplier's price floor has no field today**:
own-device work mints at the platform's rate and stranger work is priced by the
agent's `offer_price` (`money.md`). That gap is recorded, not papered over.

The principle the shape serves is **implementation blindness**: an agent learns what a body CAN do, never what it IS or where it stands. Agents query the broker, not embodiments directly: `discover(location, verb, modality, min_trust)` returns anonymised supply depth and an indicative quote, never individual identities or positions.

## 6. Consent tiers

| Tier | Deliverable | Notes |
|------|-------------|-------|
| 0 | Structured observations only | Edge inference. No raw media leaves the device. Default. |
| 1 | Raw audio | Jurisdiction rulebook applies; broker may refuse by geography. |
| 2 | Raw video | What is blurred is the DEVICE's declaration (`redaction.post`, `redaction.live` and their tags, `device-profile.md`); a stranger is matched only to a device that declared it, and the broker cannot verify it (`limits.md`). The phone app declares full blur on both lanes. |

`consent_tier` is 0, 1 or 2; there is no tier 3, and the "attested action" tier this table once carried belongs to the unimplemented verbs in §4.3 and §4.5. An embodiment serves a tier only if its manifest lists it. A request at a tier the local jurisdiction prohibits is refused with `E_JURISDICTION`.

## 7. The observation stream

Tier 0 missions deliver newline-delimited JSON events:

```json
{"t": 3.2, "type": "scene", "text": "Busy pedestrian street, light rain, most shops open"}
{"t": 5.1, "type": "object", "label": "tram", "confidence": 0.94}
{"t": 9.8, "type": "text_read", "text": "George Street closed Sat for market", "source": "sign"}
{"t": 14.0, "type": "count", "label": "queue_people", "value": 11}
```

Event vocabularies are versioned; the served one is the "What an observation looks like" table in `missions.md`, bound to the broker's vocabulary by a test, and an event may carry `at: {pan_deg, tilt_deg}` — where the camera was pointing. On a real device every event is SEALED to the agent's registered key (`identity.md`); the plaintext above is what the agent sees after opening it. Brokers MUST strip any event that names, describes or re-identifies an individual.

## 8. Trust and reputation

Reputation is earned, two-sided and non-portable in v0.1.

- Providers accrue trust from completed instrumented missions first. The attested tier (3) unlocks at a broker-defined floor.
- Agents are rated by providers. An agent whose requests are repeatedly refused or terminated for cause loses access to higher tiers.
- Ratings from safety terminations bind on the agent, never on the provider.
- Spot checks: brokers MAY silently duplicate a small fraction of attested missions to a second provider and compare.

## 9. Money

`quote → accept (escrow) → fulfil → review → settle`. A quote is firm for five minutes. Escrow is taken from the agent wallet at acceptance in the ONE instrument the mission names (`pay_instrument`: `CRDW` by default, or `CRD`), never a mix, and the provider is shown which before accepting. Stranger work parks for the agent's review after completion (`confirm`, or `dispute` with one of five codes and a reason — `missions.md`); an unreviewed mission auto-releases at its deadline.

Credit (`CRD`) is minted to the requester's wallet when their OWN device fulfils work, at the FULL quote (`OWN_AGENT_MINT_RATE = 1.0`, floored) under daily caps; it cannot be withdrawn. `CRDW` is the withdrawable tier a stranger is paid in; the terms of service govern its withdrawal. Payouts to people in the UK go through Stripe and start when they are switched on; payouts to the US are not available. This paragraph said "reduced minting" until 2026-09-05; `onboarding.md` had said "the full quote" for weeks.

## 10. Refusals

Structural refusals, returned before quoting:

| Code | Meaning |
|------|---------|
| E_PERSON_TARGET | Request semantics reference an individual |
| E_GEOFENCE | Location outside public-space rulebook |
| E_JURISDICTION | Tier prohibited at this location |
| E_TIER_LOCKED | Agent or embodiment lacks the tier |
| E_NO_SUPPLY | No conforming embodiment in range (at accept, not submit) |

The complete served list, with the remedy each carries, is `/v0/reference/responses.md`; `E_CONTACT_UNAPPROVED` and `E_CAP`, which this table once listed, are not codes the broker emits.

## 11. Security considerations

Nothing in this system signs anything, and the terms of service say so (`/v0/terms`, B3). Captured observations and deliverables are SEALED on the device to the agent's registered public key (`crypto_box_seal`; `identity.md`), so the broker relays bytes it cannot read; a `live_video` track is NOT — the media server terminates its encryption, and the broker cannot vouch for the pixels (`live.md`). Edge blurring is the device's declaration and is not attested. Location precision exposed to agents is rounded to ~110 m; a provider's true position is never published. This paragraph claimed signed manifests, end-to-end live streams and attested blurring until 2026-09-05. Prompt fields (`prompt`, `question`, `purpose`) are treated as untrusted input by provider apps and rendered as inert text, never executed or read aloud verbatim without the disclosure preamble.

## 12. Versioning and extension

Verbs and event vocabularies are versioned as `body/0.1`. Extensions live under an `x_` namespace and MUST be ignorable. Candidate verbs for v0.2, deliberately excluded from v0.1: `purchase`, `deliver`, `manipulate`. Each carries safety questions that instrumented experience should answer first.

---
*Comments to the Stringer repository. The specification is open; the reference broker is not.*
