# The device wire protocol — what a body sends

*Reference for anyone building a body that talks to Stringer: a robot, a fixed
camera, a sensor, or a client for a phone. `embodiments.md` says what a body must
DO; this page says what it must SEND. Every route below is the broker's own,
transcribed from the reference implementation (`stringer_body`'s `client.py`)
and the broker's handlers, and a test fails the build if the broker registers a
device route this page does not name.*

⚠️ **This page did not exist until 2026-09-05.** A body built from the
published documents alone reached a coherent, tested, unrunnable skeleton and
then stopped, because nothing published said what to send down the wire:
*"The documents are unusually good at telling you how the last person was
wrong. They are unusually bad at telling you what to send."* The agent-facing
verb specification (`/v0/reference/body-api.md`) is about missions, not about
a device's session with the broker. This is that other half.

## 0. Before the first packet

- **Base URL** is the origin you fetched this page from. Every path below is
  relative to it.
- **Send a User-Agent.** The broker sits behind Cloudflare, which refuses
  Python's default `Python-urllib/3.x` signature with a `403` and an HTML-ish
  `error code: 1010` that never reaches the broker at all. `stringer-body/0.1
  (+https://stringer.run)` is what the reference body sends; anything
  identifying your body will do. Measured on the robot, one header apart:
  urllib default → 403 from the edge; a named agent → the broker's own answer.
- **JSON in, JSON out**, `content-type: application/json`, except the one
  bytes route (§5). A non-2xx carries `{"error": "<code>", ...}`; the codes are
  named per route below and are the whole of what a body may branch on.
- **Credential**: a provider bearer, `authorization: Bearer sk_prov_…`, on
  every route after pairing. It is minted once, at pairing, returned in the
  clear once, and stored hashed. Keep it in a file with owner-only permissions;
  losing it costs the embodiment id, both per-device grants, standing and
  settings (`CARD-RECOVERY.md`). Never put it on a command line: it lands in
  `ps` and in `/proc`.

## 1. Pair: a one-time code becomes the credential

The owner mints a pairing code in the dashboard (`POST /v0/provider/pair/new`,
owner-authenticated — a device cannot mint its own). The device redeems it
**with its whole declaration in the same request**:

```
POST /v0/provider/pair/redeem            no auth: the code is the credential
{
  "code": "ABCD2345",
  "kind": "robot",                        robot | human | camera | sensor | unknown
  "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},
  "free_text_steerable": false,
  "name_detection": {"level": "none"},
  "form": "wheeled",
  "languages": ["en"],
  "mobility": {...}, "expressive": {...}, "routines": {...}, "autonomy": {...}
}
→ 200 {"provider_id": "prov_…", "embodiment_id": "emb_…", "auth": "sk_prov_…", ...}
→ 400 {"error": "invalid_or_expired_code"}     unknown, used or expired — one answer
→ 400 {"error": "<field>: <why>"}              a malformed declaration, refused BEFORE
                                               the code is burned
```

**The broker records exactly what is declared and nothing else.** A field you
do not send is unknown, and unknown is never matched as capable: a device that
sent only `sensing` paired, reported presence and polled for ever — and was
never offered work, correctly. The declaration keys and their shapes are in
`device-profile.md` (`claims`) and `embodiments.md` §5; the body's own bounds
for each routine are in `routines`. A numeric parameter is offered as
`[lo, hi]`; **a choice parameter may be offered as the list of choices this
body makes** — `"flourish": {"move": ["nod"], "duration_s": [1, 20]}` from a
body on a cable whose other moves would drive it. The broker refuses a request
for a choice outside the list, and its tether gate reads the list: a
`flourish` offered as `nod` only is allowed to a tethered body, asked for or
unnamed, because nothing in it turns a wheel (since 2026-09-05).

## 2. Declare again, whenever anything changes

```
POST /v0/provider/capability             Bearer sk_prov_…
{ ...the whole declaration, as at pairing... }
→ 200 {"embodiment_id": "emb_…", ...}
```

Not a merge: send everything you mean, every time. The reference body
re-declares on every start, so a detector that arrived, a rate that was
re-measured, or a capability the owner switched off is on the broker within a
restart. A declaration of nothing would un-declare what the broker holds, and
the reference client refuses to send one.

## 3. Presence and coverage

```
POST /v0/provider/presence     {"availability": "listening" | "off" | "dnd"}
POST /v0/provider/coverage     {"lat": 51.458, "lng": -0.322, "radius_m": 500}
POST /v0/provider/position     a measured position, for presence proofs (§6)
```

Presence is availability only; coordinates in that body are ignored. Coverage
is the circle the device is willing to work in — declared once by a human,
quantised by the broker, rate-limited to one change per fifteen minutes (the
first is free), and the response reports what was actually stored. Own-device
missions do not read it at all; stranger candidacy does, so a device that never
said where it works gets no stranger offers until it does.

## 4. The mission loop

```
GET /v0/provider/missions
→ 200 {"missions": [ {
     "id": "mis_…", "state": "DISPATCHED" | "ACTIVE",
     "verb_chain": [{"verb": "observe", "duration_s": 120, "routine": "sweep",
                     "routine_params": {"pan_deg": 45, "dwell_s": 2}}],
     "prompt": "…", "consent_tier": 0,
     "session_mode": "async_delegated" | "live_interactive",
     "media": null | {"kind": "video", "sink": {"url": "…", "method": "PUT"}, "frame_rate": 1, ...}
                  | {"kind": "live_video", ...} | {"kind": "image"},
     "location": {"lat", "lng"} | null, "distance_band": "…", "area": "…",
     "quote_minor": 123, "pay_instrument": "CRD" | "CRDW" | null,
     "agent_public_key": "<base64>", "presence_proven": false
   } ], "offers": [ ...unclaimed stranger offers, without sink or key... ] }
```

Poll it. Assigned missions carry the agent's box public key (seal observations
and artifacts to it) and, for a media mission, the agent's sink. An unclaimed
OFFER carries neither until you claim it.

```
POST /v0/provider/missions/:id/accept      no body
→ 200 {"state": "ACTIVE"}                            started
→ 200 {"awaiting_review": …} | {"awaiting_approval": …}   parked for a human's tap
→ 403 {"error": "stopped"}                            the owner's stop is on; try later
→ 404 for anything else: not yours, not there, not DISPATCHED
```

Accept **only a DISPATCHED mission**. Accepting is what moves it to ACTIVE and
opens every live surface; `rtc/publish` and the directive routes refuse before
it.

```
POST /v0/provider/missions/:id/events      one observation, as missions.md describes
{"t": 12.4, "type": "object", "label": "chair", "confidence": 0.81,
 "at": {"pan_deg": 30, "tilt_deg": 0}}                          plaintext, or
{"sealed": true, "ciphertext": "<base64 crypto_box_seal to agent_public_key>"}
→ 200
```

Types, fields and the bearing are in `missions.md` ("What an observation looks
like"). Unsealed text is person-stripped and PII-masked by the broker; sealed
events pass through untouched, so seal to the key on the mission row.

```
GET  /v0/provider/missions/:id/directives?since=<seq>&wait=<s>   live missions only
→ 200 {"directives": [{"seq": 7, "sender": "agent", "kind": "control" | "text",
                       "body": "{\"action\":\"routine\",\"value\":\"sweep\",\"params\":{...}}",
                       "created_at": "…"}]}
→ 409 {"error": "not_interactive" | "not_active"}
POST /v0/provider/missions/:id/directives   {"text": "switched to dwell", "in_reply_to": 7}
→ 200 {"ok": true, "seq": 8}
```

`since` is a high-water mark, not a time; `wait` (up to 20 s) holds the
request until something lands — set your transport timeout above it. Read the
thread from the moment you go ACTIVE, or a steer is not late, it is unread.
Your replies are screened (no URLs, emails, numbers) and refused rather than
truncated; say what you did, when you did it, in plain words.

```
POST /v0/provider/missions/:id/complete    {"outcome": "danced: spin x3"}   body optional
→ 200 {"state": "SETTLED" | ...}
→ 400 {"error": "bad_outcome", "reason": "…"}   the line failed the screen; nothing moved
POST /v0/provider/missions/:id/terminate   {"reason_code": "routine_not_offered", "detail": "…"}   both optional
→ 200 {"state": "TERMINATED_PROVIDER", "reason_recorded": true | false}
POST /v0/provider/missions/:id/decline     an OFFER you will not take
```

Complete when the work is delivered. The outcome line is the only channel a
body has for work that produces no observations and no media. Terminate with
a reason from `responses.md`'s table (`routine_not_offered`,
`operator_stopped`, `driver_error`, …): an unknown code is dropped, never
refused — a body can always give up. A terminate earns the elapsed pro rata,
with one exception: `driver_error` (the device broke) on a job meant to deliver
something (a look, inspect, photo, clip or live video) with nothing delivered —
no observation, no media, no published track — earns 0 and the agent is
refunded in full. A movement-only job keeps the pro rata. Send it honestly; it
only ever costs the device.

## 5. Media

```
POST /v0/provider/missions/:id/rtc/publish   {"sdp": "<your offer>", "mid": "0"}
→ 200 {"session_id": "…", "track_name": "…", "sdp": "<the SFU's answer>"}
→ 409 before ACTIVE; 429 on a tight retry loop
```

Live video: offer your track, set the answer on your own peer. Redact every
frame before it leaves the device (`embodiments.md` §4c) — the broker cannot
see the pixels and `live.md`'s table says so from the agent's side.

```
POST /v0/provider/missions/:id/delivery      a media mission's receipt
{"content_hash": "<sha256 of the bytes you sent to the sink>",
 "redaction": {...the attestation block your redactor produced...},
 "sealed_key": "…", "envelope": {...}, "capture_link": "…", "grounded_in": "…"}
→ 200 {"recorded": true, "content_hash": "…", ...}
→ 400 {"error": "bad_request", "detail": "…"}   → 409 not_active | no_media
```

The bytes go to the AGENT's sink (on the mission row), never through the
broker; this records a receipt about them. `content_hash` is the only required
field; the redaction block is shape-checked and cannot be verified — every word
in it is your claim.

```
POST /v0/missions/:id/artifact               the RELAY lane: body = the sealed bytes
content-type: image/jpeg (or the artifact's type)       Bearer sk_prov_…
→ 200 {"content_hash": "…", ...}   → 413 too_large   → 409 not_active | wrong_lane | already
```

⚠️ **The path is `/v0/missions/:id/artifact`, not `/v0/provider/…`**, with
provider auth. Not a slip: it matches the media specification verbatim, and a
tidier path 404s. Send the ciphertext as the body — the broker stores it opaque,
hashes what it received, and that hash is the dispute primitive. No separate
receipt call; this writes the delivery itself.

## 6. Proving you were there, and what you are

```
POST /v0/provider/missions/:id/presence/challenge   → a single-use nonce
POST /v0/provider/missions/:id/presence             {...a signed position over it...}
POST /v0/provider/attest/challenge                  → nonce   (App Attest; iPhone only today)
POST /v0/provider/attest                            {...the attestation...}
```

Earth Swarm survey missions only (`programme: "earthswarm"`), the find
protocol in `earthswarm/PROTOCOL.md` sections 1 and 5 -- one App Attest assertion
certifies a per-mission Ed25519 session key, and each find is a signed receipt
of hashes, never a photo, a species or a position:

```
GET  /v0/provider/missions/:id/obskey/challenge     → { challenge }   (single use, 10 minutes)
POST /v0/provider/missions/:id/obskey               { challenge, session_pk, assertion }
POST /v0/provider/missions/:id/find-receipts        { seq, captured_at, mono_ms, photo_sha256,
                                                      body_sha256, loc_commit, prev_hash, signature }
```

Presence proofs are optional and gate only the automatic release when an agent
never reviews; attestation is experimental and non-enforcing (`limits.md`). A
body with neither is `attestation: none`, like every robot in the field.

## 7. The rest of the surface

| route | who | what |
|---|---|---|
| `GET /v0/provider/me` | device | who am I: provider, embodiment, owner, status |
| `GET /v0/provider/wallet`, `GET /v0/provider/earnings`, `GET /v0/provider/receipts` | device | balances, earnings, per-mission receipts |
| `GET /v0/provider/agent-keys` | device | the agent keys this owner's phone may act with (agent mode) |
| `POST /v0/provider/agent-mode` | device | a phone turning agent mode on |
| `POST /v0/provider/pay-preferences` | device | `accepts_crd`: whether to take platform credit for stranger work |
| `POST /v0/provider/push-token` | device | where to push a nudge (a phone). Optional `topic`: the bundle id of the app that minted the token, which must be one this broker attests |
| `GET /v0/provider/settings/stringer-missions`, `PUT /v0/provider/settings/stringer-missions` | device | an Earth Swarm phone's "Also offer me Stringer missions" switch, `{ "enabled": boolean }`; off by default, always `true` for a Stringer device |
| `POST /v0/provider/diagnostics` | device | crash and error records, batched |
| `POST /v0/provider/vetting` | device | file the owner's vetting record (needed before stranger work) |
| `POST /v0/provider/missions/:id/complaint`, `POST /v0/provider/complaints/:id/appeal` | device | a complaint about a mission; an appeal |
| `POST /v0/provider/routine-proposals` | device | propose a routine the registry lacks (a person judges it; `VERBS ARE SACRED`) |
| `GET /v0/routines` | anyone | the routine registry, with units and reference frames |
| `GET /v0/geofences`, `GET /v0/exclusions` | anyone | where each consent tier is lawful; where the platform does not operate |
| `POST /v0/provider/register` | owner | register a device with an owner token instead of a pairing code |
| `POST /v0/provider/pair/new` | owner | mint a pairing code |
| (register, pair/new with a dashboard session) | n/a | an owner key is unaffected; a dashboard session without recent proof gets `403 reauth_required` (see onboarding: step-up) |
| (payouts for such a device) | n/a | a device registered or paired with an owner key cannot set up payouts from the device (`409 payouts_need_dashboard`). Set payouts up from the phone app or dashboard |
| `POST /v0/provider/:id/rotate` | dashboard session | rotate a device's credential: needs a dashboard session with recent proof (see onboarding: step-up) |
| `POST /v0/provider/:id/revoke` | owner | revoke a device's credential (unchanged) |
| `POST /v0/owner/embodiments/:id/coverage` | owner | set a device's coverage from the dashboard |
| `GET /v0/owner/devices` | owner | every device of this owner |
| `GET /v0/agent/devices` | agent | what its owner has (`what you have` in the app) |
| `POST /v0/surveyor/signin/apple` | anyone | Earth Swarm app only: Sign in with Apple creates or finds the owner and registers THIS phone (the pair/redeem manifest as `device`); returns `provider_token` |
| `POST /v0/surveyor/signin/email/start`, `POST /v0/surveyor/signin/email/verify` | anyone | Earth Swarm app only: email a six-digit code (always `202`), then trade it plus `device` for a `provider_token` |
| `GET /v0/surveyor/profile`, `PUT /v0/surveyor/profile` | device | the surveyor's one form: name, 18+, the terms version shown; files the same vetting record as `POST /v0/provider/vetting` |
| `GET /v0/surveyor/terms` | anyone | the terms of service the profile accepts, `{version, markdown}` |
| `POST /v0/surveyor/payouts/setup`, `GET /v0/surveyor/payouts/return` | device / anyone | Stripe payouts set up in the app: `{return_url: "earthswarm://…"}` → `{url}`; Stripe lands on the return route, which bounces to the app |
| `GET /v0/surveyor/earnings` | device | what the surveyor has earned, what is pending, what has been paid out, and whether payouts are ready; `tokens: {balance, earned_7d, recent}` is platform credit (CRD), never cash, and never counted in `pending_minor` |
| `POST /v0/surveyor/explore` | device | Earth Swarm phones only: `{lat, lng}` rounded to 0.01 degrees (finer is a 400) asks the programme for an Explore job nearby; optional `choice`, `"quick"` or `"spot:<place id>"`, names which of today's jobs (Earth Swarm's `GET /v1/jobs/today`) was tapped → `202 {requested, request_id, remaining_today}`; `429 E_EXPLORE_DAILY_LIMIT` once three Explore jobs were accepted today (UTC), `429 E_EXPLORE_DAILY_TOKENS` once the jobs taken today come to 200 tokens (also refuses a walk) |
| `POST /v0/surveyor/walk` | device | Earth Swarm phones only: today's walk, a job that sends nobody anywhere (record what you find, where you are). `{lat, lng}` rounded to 0.01 degrees → `202 {requested, request_id, remaining_today}`; `429 E_WALK_DAILY_LIMIT` once today's walk was taken (UTC). One a day, separate from Explore's three. No route is asked for or kept |
| `POST /v0/surveyor/record` | device | Earth Swarm phones only: an UNPAID recording session where the surveyor is, any time and as often as they like, so a find outside a paid job still counts for the life list, firsts and boards. `{lat, lng}` rounded to 0.01 degrees → `202 {requested, request_id}`. The job answering it pays nothing, enforced by the database |
| `GET /v0/surveyor/identify-pass` | device | Earth Swarm phones only: a signed pass for Earth Swarm's identify queue → `200 {pass, expires_at}` (one hour). It carries a pseudonym and HMAC tags of this person's recent Earth Swarm missions, never who they are; the phone sends it to `earthswarm.ai/v1/identify/*` as `Authorization: Identify <pass>`. `403 E_IDENTIFY_EARTHSWARM_ONLY` for any other phone, `503 E_NOT_CONFIGURED` until the broker holds `IDENTIFY_PASS_SECRET` |
| `POST /v0/surveyor/share-pass` | device | Earth Swarm phones only: numbers for a share card, signed for `earthswarm.ai/v1/shares` → `200 {pass, expires_at}` (ten minutes). Body `{what}`: `streak`, `species`, `tokens`, `challenge`, `bonus` (with the wanted species' `taxon`) or `rank` (with a `district`). Every number is the broker's own; the pass carries the person's referral code and nothing that identifies them. `409 E_SHARE_NOTHING` when there is nothing to show yet, `400` for an unknown `what`, `403 E_SHARE_EARTHSWARM_ONLY`, `503 E_NOT_CONFIGURED` without `IDENTIFY_PASS_SECRET` |
| `POST /v0/surveyor/signin/password` | none | Earth Swarm sign-in by address and password `{email, password, device}` → the same answer as the other sign-ins. `401 E_PASSWORD_INVALID` for an unknown address, an account with no password and a wrong password alike; `429 E_RATE_LIMITED` after ten tries for an address in fifteen minutes, or thirty an hour from one IP |
| `PUT /v0/surveyor/password` | device | Set or change this account's password `{password}` (10 to 128 characters) → `200 {password: true}`. Signed in only: the sign-in is the proof of the address. Stored as a salted PBKDF2-SHA-256 hash. `409 E_CONTACT_REQUIRED` for an account with no email address |
| `GET /v0/surveyor/referral` | device | Earth Swarm phones only: this person's invite code → `200 {code, tokens, redeemed, can_redeem}`. The code is six characters with no look-alikes, stable, and printed on their share cards |
| `POST /v0/surveyor/referral` | device | Earth Swarm phones only: enter a friend's code `{code}` → `200 {inviter_name, tokens}` and the two become friends on the boards. Both are paid `tokens` once this person has finds on two different days. `404 E_REFERRAL_UNKNOWN`, `400 E_REFERRAL_OWN`, `409 E_REFERRAL_ALREADY` or `E_REFERRAL_NOT_NEW` (a code is for someone with no find yet) |
| `GET /v0/surveyor/play` | device | the surveyor's own life list, across their phones: `{life: [{taxon, name, common, first_day, finds}], year: {year, species}, firsts: {earthswarm, place}}`, from finds Earth Swarm confirmed for play. No place and no position: the broker holds neither, only the local authority district of each find, for the local boards |
| `GET /v0/surveyor/challenge` | device | this week's challenge, the same for everybody: `{title, group, need, have, tokens, done, ends_at}`. `have` counts different species of `group` (any group when null) confirmed this week; reaching `need` pays `tokens` once |
| `GET /v0/surveyor/bounties` | device | bonus finds: `{new_species: {tokens, done}, wanted: [{taxon, name, tokens, done}], ends_at}`. A species new to the surveyor's list pays once a day; each of this week's three wanted species pays once |
| `GET`/`PUT /v0/surveyor/push-prefs` | device | which Earth Swarm notifications the surveyor gets: `{confirmed, rewards, streak, events, identify}`, each a boolean, all on until changed. `PUT` takes any of them; anything else is `400`. Nothing is sent between 21:00 and 08:00 UK time whatever is on |
| `GET`/`PUT /v0/surveyor/boards/settings` | device | the surveyor's leaderboard settings: `{display_name, visible}`. Opted out by default; `visible: true` needs a `display_name` of 2 to 30 letters, digits, spaces or `' - . _` |
| `GET /v0/surveyor/boards/friends` | device | the surveyor and their friends who opted in, ranked on species confirmed this calendar year, then firsts: `{year, entries: [{friendship, you, display_name, rank, year_species, year_firsts, life_species}], hidden_friends}`. Friends who did not opt in are counted, never named |
| `GET /v0/surveyor/boards/districts` | device | the local authority districts the surveyor has confirmed finds in: `{districts: [{id, name, year_species, life_species}]}` |
| `GET /v0/surveyor/boards/local?district=` | device | a district's board for this year, ranking everyone with confirmed finds made there: `{district, year, people, entries: [{rank, display_name, species, firsts, you}], me}`. Names only people who opted in (at most 50); `me` is the caller's own standing, shown whether or not they opted in. `404 E_BOARD_EMPTY` when nobody has a find there this year |
| `POST /v0/surveyor/friends/invite` | device | a one-use friend invite: `201 {code, expires_at}`, 10 characters, 7 days. `429 E_INVITES_LIMIT` with 10 open |
| `POST /v0/surveyor/friends/accept` | device | `{code}` → `{friendship}`; case, spaces and dashes ignored. `404 E_INVITE_UNKNOWN` for a spent, expired or mistyped code, `400 E_INVITE_OWN` for your own |
| `DELETE /v0/surveyor/friends/:id` | device | ends a friendship, from either side: `{removed: true}` |
| `GET /v0/surveyor/finds?after=` | device | the surveyor's own Earth Swarm find receipt hashes, across their phones, 500 a page in hash order: `{receipt_hashes, next}`. A new phone asks Earth Swarm's status route about them to rebuild its patches |
| `POST /v0/surveyor/account/erase` | device | deletes the surveyor's account: `{confirm: "erase my account"}` → `{erased: true}`. Their life list, sign-in, contact details and device positions go; money and consent records stay, no longer tied to them. `409 E_ERASE_MONEY_WAITING` while cash is owed, `409 E_ERASE_JOB_IN_PROGRESS` while a job is open |

## 8. The order that works

Pair → declare (on every start) → presence `listening` → coverage (once, by a
human) → poll → accept a DISPATCHED mission → for a live mission, read the
thread and publish → post observations as they happen → deliver or relay media
→ complete with an outcome line, or terminate with a reason → poll again.
`embodiments.md` §4a is the safety half of every step above; read it before
you write the loop.

## 9. The sticker

Every device has a public page: `https://stringer.run/v0/d/<embodiment_id>`.
It shows a person in the room what this body is, what it says it can do, what
it masks, that all of that is the device's own word (or its attestation), and
a form that files a complaint against the device's most recent mission — no
account, no name asked. It shows nothing about the owner, the position or
whether the body is working right now. **Print it on the body.** A robot in a
shop films people who never onboarded, and this page is the only door they
have; the owner's dashboard shows the URL beside each device.
