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:

PrincipalTokenHeader
Ownersk_own_…Authorization: Bearer …
Agentagtk_…Authorization: Bearer …
Provider (a body)sk_prov_…Authorization: Bearer …
Session (dashboard sign-in)sk_ses_…Authorization: Bearer …
Platform bootstrapREGISTRATION_KEY / admin keyx-registration-key: …
OAuth connection (hosted MCP)ES256 JWT access token from /oauth/tokenAuthorization: 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:

MethodPathAuthPurpose
POST/v0/auth/magic-linknoneRequest a sign-in link for an email address → always 202
POST/v0/auth/verifythe link's tokenExchange it for a session; first verify for an address creates the owner → {owner_id, session, owner_auth}
GET/v0/owner/accountowner or sessionYour own email, quotas + agents + providers with per-tier balances
POST/v0/agentsowner or sessionCreate an agent → its MCP token (shown once)
GET/v0/owner/missionsowner or sessionExactly 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-linkowner or sessionA 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-linkowner or sessionA seven-day read-only report page for any of your own agent's jobs → {url, expires_at, report_only}
POST/v0/ownersx-registration-keyOperator-only break-glass bootstrap → {owner_id, auth}. Not the developer path — see above.

Agent (the lobster)

MethodPathAuthPurpose
GET/v0/discoveragentAnonymised supply depth + indicative quote for a place/need
POST/v0/missionsagentSubmit a mission (verb_chain, location, needs, allow_stranger) → QUOTED
POST/v0/missions/:id/acceptagentAccept the quote → DISPATCHED (escrows for a stranger mission)
GET/v0/missions/:id/outboxagentMission lifecycle + observation events
GET/v0/walletagent{crd, crdw}
GET/v0/receipts/:idagentThe 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.

MethodPathAuthPurpose
GET/v0/me/earthswarm/playearthswarm.meLife list, year list, firsts and streak
GET/v0/me/earthswarm/findsearthswarm.meRecent finds (?limit= up to 100): day, confirmed with species, tier, firsts and district, or not_confirmed
GET/v0/me/earthswarm/earningsearthswarm.meCash (USD minor units), tokens (never cash), this week's challenge and bonus finds

Provider (any body: phone, robot, drone…)

MethodPathAuthPurpose
POST/v0/provider/pair/newownerMint a single-use pairing code (dashboard)
POST/v0/provider/pair/redeemthe codeRedeem it → a provider credential (no baked-in secret)
POST/v0/provider/registerownerRegister a provider + embodiment (+ a measured sensing manifest)
POST/v0/provider/presenceprovideravailability (listening/dnd/off) + fence id + battery — never a point (W9)
POST/v0/provider/coverageproviderSet the static coverage point + radius candidatesFor range-checks against (W9)
GET/v0/provider/missionsproviderAssigned missions + eligible unclaimed OFFERS
POST/v0/provider/missions/:id/acceptproviderAccept an assignment / CLAIM an offer (first-accept-wins) → ACTIVE
POST/v0/provider/missions/:id/eventsproviderPost one tier-0 observation event (redacted at the edge)
POST/v0/provider/missions/:id/completeproviderComplete → SETTLED (release escrow / mint)
POST/v0/provider/missions/:id/terminateproviderEnd 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/onboardproviderStart Stripe Connect onboarding (payout KYC gate)
POST/v0/provider/payoutproviderCash out CRDW → money (burns CRDW only)

Money

MethodPathAuthPurpose
POST/v0/topupownerTop up real cash (CRDW) for an agent (USD only; CRDW is USD-pegged)
POST/v0/owner/transferownerMove credit between two of your own agents (same tier; never creates withdrawability)
POST/v0/payments/webhooksignaturePSP reconciliation
POST/v0/admin/providers/:id/vetadmin keyFile 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.

MethodPathAuthPurpose
POST/v0/admin/invitesadmin keyMint a single-use invite code + the manual steps you still owe the tester
GET/v0/admin/invitesadmin keyEvery invite and what each is still waiting on
POST/v0/admin/invites/:code/gatesadmin keyRecord that a HUMAN granted Access / sent the TestFlight invite
GET/v0/invite/:codethe codeAll three gates, and which are still a person's job
POST/v0/invite/redeemprovider + the codeFile the vetting record against this device (single use, expiring)

refusals & the portable verb/consent/pricing model live in the Body API v0.1.