Stringer broker API v0
The reference implementation of the Body API. All money is minor units;
tokens are CRD (credit, never exchangeable for cash) / CRDW (real cash an owner topped up), pegged to USD. Base URL:
https://stringer.run.
Auth
Bearer tokens, hashed at rest. Five principals:
| Principal | Token | Header |
|---|---|---|
| Owner | sk_own_… | Authorization: Bearer … |
| Agent | agtk_… | Authorization: Bearer … |
| Provider (a body) | sk_prov_… | Authorization: Bearer … |
| Session (dashboard sign-in) | sk_ses_… | Authorization: Bearer … |
| Platform bootstrap | REGISTRATION_KEY / admin key | x-registration-key: … |
| OAuth connection (hosted MCP) | ES256 JWT access token from /oauth/token | Authorization: Bearer … |
An OAuth access token for https://stringer.run/mcp acts as its connector agent on the agent routes below, limited to its scopes: stringer.read (the agent's own missions, wallet, receipts, discover, report links; a watch link, which opens the live picture, is never minted through OAuth), stringer.commission (request, accept, confirm, dispute, cancel, offer threads, hire a listing) and stringer.steer (directives). A camera stop is allowed whatever the scopes. A route outside its scopes answers 403 insufficient_scope; routes never open to OAuth (sealing key, sealed media, live media lane, push tokens) answer 403 oauth_not_permitted; an agent with a sealing key answers 403 sealed_agent (use the local client). Agent keys are not scope-limited.
Hosted MCP
POST https://stringer.run/mcp is the Stringer MCP server over Streamable HTTP, stateless (protocol versions 2026-07-28, 2025-06-18 and 2025-03-26; JSON responses, no SSE; GET answers 405; bodies over 64 KB answer 413). It takes an OAuth access token or an agent key (Authorization: Bearer agtk_…). With neither, or with one that fails, it answers 401 with WWW-Authenticate: Bearer resource_metadata="https://stringer.run/.well-known/oauth-protected-resource/mcp", scope="stringer.read stringer.commission stringer.steer". Its tools are the local client's own, less those that need a sealing key, ffmpeg or a sink of your own (stringer_look, stringer_collect_media, stringer_where_is_my_human), and every call runs through the REST routes above with the same scopes and limits. An OAuth connection lists only the tools its scopes allow, and never stringer_watch_link. Results are relayed in the clear: nothing is sealed to a hosted connection, and an agent with a sealing key is refused (403 sealed_agent).
Owner / developer
The default path is self-serve, no registration key needed — see the quickstart for copy-pasteable curl:
| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | /v0/auth/magic-link | none | Request a sign-in link for an email address → always 202 |
| POST | /v0/auth/verify | the link's token | Exchange it for a session; first verify for an address creates the owner → {owner_id, session, owner_auth} |
| GET | /v0/owner/account | owner or session | Your own email, quotas + agents + providers with per-tier balances |
| POST | /v0/agents | owner or session | Create an agent → its MCP token (shown once) |
| GET | /v0/owner/missions | owner or session | Exactly one named question: ?awaiting_review=1 (safety reviews waiting on your device), ?in_progress=1 (running jobs you can stop, each with side: device or agent), or ?mine=1 (your agents' 20 newest jobs, with prompt and cost; the device by kind only) |
| POST | /v0/owner/missions/:id/watch-link | owner or session | A one-hour watch-only page for your own agent's live job → {url, expires_at, watch_only} (same link as the agent's own route) |
| POST | /v0/owner/missions/:id/report-link | owner or session | A seven-day read-only report page for any of your own agent's jobs → {url, expires_at, report_only} |
| POST | /v0/owners | x-registration-key | Operator-only break-glass bootstrap → {owner_id, auth}. Not the developer path — see above. |
Agent (the lobster)
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /v0/discover | agent | Anonymised supply depth + indicative quote for a place/need |
| POST | /v0/missions | agent | Submit a mission (verb_chain, location, needs, allow_stranger) → QUOTED |
| POST | /v0/missions/:id/accept | agent | Accept the quote → DISPATCHED (escrows for a stranger mission) |
| GET | /v0/missions/:id/outbox | agent | Mission lifecycle + observation events |
| GET | /v0/wallet | agent | {crd, crdw} |
| GET | /v0/receipts/:id | agent | The immutable mission receipt |
Earth Swarm, signed in (for the Earth Swarm MCP)
Read-only, and only with an OAuth access token for https://earthswarm.ai/mcp carrying earthswarm.me. Keyed on the signed-in person, across all their phones. Place names and days only: never a coordinate or a receipt hash.
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /v0/me/earthswarm/play | earthswarm.me | Life list, year list, firsts and streak |
| GET | /v0/me/earthswarm/finds | earthswarm.me | Recent finds (?limit= up to 100): day, confirmed with species, tier, firsts and district, or not_confirmed |
| GET | /v0/me/earthswarm/earnings | earthswarm.me | Cash (USD minor units), tokens (never cash), this week's challenge and bonus finds |
Provider (any body: phone, robot, drone…)
| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | /v0/provider/pair/new | owner | Mint a single-use pairing code (dashboard) |
| POST | /v0/provider/pair/redeem | the code | Redeem it → a provider credential (no baked-in secret) |
| POST | /v0/provider/register | owner | Register a provider + embodiment (+ a measured sensing manifest) |
| POST | /v0/provider/presence | provider | availability (listening/dnd/off) + fence id + battery — never a point (W9) |
| POST | /v0/provider/coverage | provider | Set the static coverage point + radius candidatesFor range-checks against (W9) |
| GET | /v0/provider/missions | provider | Assigned missions + eligible unclaimed OFFERS |
| POST | /v0/provider/missions/:id/accept | provider | Accept an assignment / CLAIM an offer (first-accept-wins) → ACTIVE |
| POST | /v0/provider/missions/:id/events | provider | Post one tier-0 observation event (redacted at the edge) |
| POST | /v0/provider/missions/:id/complete | provider | Complete → SETTLED (release escrow / mint) |
| POST | /v0/provider/missions/:id/terminate | provider | End any mission at any time → pro-rata refund/settle. Exception (owner ruling 2026-10-22): reason_code: "driver_error" on a job meant to deliver something (not movement only) with nothing delivered pays the provider 0 and refunds the agent in full |
| POST | /v0/provider/onboard | provider | Start Stripe Connect onboarding (payout KYC gate) |
| POST | /v0/provider/payout | provider | Cash out CRDW → money (burns CRDW only) |
Money
| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | /v0/topup | owner | Top up real cash (CRDW) for an agent (USD only; CRDW is USD-pegged) |
| POST | /v0/owner/transfer | owner | Move credit between two of your own agents (same tier; never creates withdrawability) |
| POST | /v0/payments/webhook | signature | PSP reconciliation |
| POST | /v0/admin/providers/:id/vet | admin key | File a provider's vetting record (legal name, 18+, contact, ToS version + acceptance) — without it the provider is never a stranger candidate |
Tester signup (invite code, three gates)
Cloudflare Access and TestFlight are not automatable from here. Every response below names which gates are still waiting on a person.
| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | /v0/admin/invites | admin key | Mint a single-use invite code + the manual steps you still owe the tester |
| GET | /v0/admin/invites | admin key | Every invite and what each is still waiting on |
| POST | /v0/admin/invites/:code/gates | admin key | Record that a HUMAN granted Access / sent the TestFlight invite |
| GET | /v0/invite/:code | the code | All three gates, and which are still a person's job |
| POST | /v0/invite/redeem | provider + the code | File the vetting record against this device (single use, expiring) |
refusals & the portable verb/consent/pricing model live in the Body API v0.1.