The canonical mutation surface is Most's /v3 HTTP API with bearer authentication backed by finite Skarbiec capabilities. Events flow back out as HMAC-signed webhooks with bounded retry; attachments use signed URLs that work while the attachment stays registered; location reads answer from what the bridge recorded.
HTTP API — canonical mutation, account-adoption, location and webhook-subscription interface: `GET /v3/accounts`, `POST /v3/accounts/messages-app/import`, `POST /v3/chats`, message, reaction, typing, voice, edit, unsend, `GET /v3/chats/{chat_id}/location`, `GET /v3/chats/{chat_id}/location/history`, and subscription routes.
Developer first use — authenticated `GET /v3/onboarding/first-use`, also discoverable as `most-cli onboarding` and MCP tool `most_onboarding_first_use`; its primary action is `most-cli accounts import messages-app`, and completion requires accepted imported history or an actual `message.delivered` / `message.read` provider receipt.
Desktop first use is a separate, locally stored most-desktop journey completed by an actual service posture read, not a provider message receipt. Failed recording leaves the walkthrough present; completion or skip whose event flush fails remains recorded and reports unsent events after the overlay closes. Advance, skip, first-success completion and replay share an in-flight mutation guard, so awaited storage or delivery cannot admit a competing journey mutation.
Desktop replay distinguishes failure to restart from a later exposure or event-delivery failure after reset was recorded. The latter leaves the restarted walkthrough present and names the failed stage and client cause in both the settings mutation result and the window message; it does not perform another reset.
Health API — `GET /healthz`, unauthenticated and secret-free; exposes build identity, the active composition, the backends that serve and every backend the composition declares that does not, with its cause (`unavailable`), in which case `status` is `degraded`, not `ok`.
Phone calls — `GET /v3/calls/readiness`, `POST /v3/calls`, `GET /v3/calls`, `GET /v3/calls/{call_id}` and `answer`, `reject`, `say`, `hangup` under it, with the service bearer; the voice provider's own requests arrive under `/v3/providers/twilio/voice/*` and are checked against its signature. See Phone calls.
Attachment API — HMAC-signed `GET /v3/attachments/{id}?sig=…`, valid while the attachment stays registered and Messages keeps its file (not found / gone after); rotating the signing item ends every URL. URLs minted earlier with `exp=…` are honoured until that instant. A wrong signature or a passed `exp` is forbidden; when the signing key cannot be redeemed from Skarbiec the link is not checked and the answer is service unavailable, with the redemption's own cause in the request-failure log. A row that records no media type is served without `Content-Type`.
Worker protocol — `/internal/worker/connect`, protected by mTLS and a dedicated bearer capability; the wire contract lives in docs/remote_worker_protocol.md.
Automation — `most-cli accounts` lists retained source metadata, `most-cli accounts import <source>` imports one adopted source's history (`messages-app` is the Messages.app adapter; another source kind is refused with the ones that exist), and `most-cli location <chat_id>` / `most-cli location-history <chat_id>` read where a conversation's participants are. Every answer is the server's JSON; `--text`, anywhere on the line, prints it as `key: value` lines. A wrong invocation exits 2 with the usage; a request the server refused or that never reached it prints `error: <message>` and exits 1. The stdio `most-mcp` server remains read-only.
A new conversation creates durable chat and message records, dispatches through one eligible transport worker, and returns stable identifiers and status. Authentication, validation, and worker selection happen before backend dispatch.
A continued conversation uses the Most `chat_id` and keeps the same conversation identity: the chat is durably assigned to a transport and, when pooled, to one physical worker.
A saved chat is not proof of message acceptance. HTTP 200 can contain delivery_status=failed. Inspect the `message` receipt of a new conversation, or the returned message of a continued one, and its optional error. Most Desktop and the messaging examples reject failed receipts while retaining the chat identifier.
Most Desktop requires nonempty sender, recipients and text without imposing its own character or recipient-count ceiling. SMS and RCS retain their service contract of one recipient. It consumes complete JSON responses, including histories and import reports, rather than rejecting them by byte count. HTTP timing follows Foundation's declared request/resource policy, not a shorter desktop deadline; this does not promise unlimited requests.
The mac-relay adapter cannot create group conversations. It refuses a group request with HTTP 501 and the observed recipient count before dispatch or persistence, rather than sending to only the first recipient. The group-send example therefore requires a group-capable transport; Most Desktop retains the complete service refusal.
Send endpoints currently have no idempotency key, so callers must not automatically retry an ambiguous provider outcome. Once an upstream provider has accepted a request, final delivery is the provider's domain; Most reports acceptance and subsequent provider receipts.
When a transport observes an inbound message, a status change or a location fact and a matching webhook subscription exists, Most normalizes and persists the event, then delivers an HMAC-signed webhook, retried on a 5xx answer, a 429 or a transport error on the schedule the deployment declares. `MOST_WEBHOOK_RETRY_DELAYS` lists the whole seconds to wait before each attempt, comma-separated, and its length is the number of attempts: `MOST_WEBHOOK_RETRY_DELAYS=0,15,60` tries at once, after 15 seconds and after another 60. Most has no schedule of its own: with it unset or malformed, the server refuses to start an enabled direct-to-Apple backend (`direct-apple backend not registered: MOST_WEBHOOK_RETRY_DELAYS is not set: …`), the mac-relay pool and phone calls report it as their reason in the log and in `GET /v3/calls/readiness`, and the remote-worker control plane is not mounted, with the same reason logged. The receiver can verify the raw body and timestamp; attachment access uses signed URLs that work while the attachment stays registered and Messages keeps its file.
Subscribable events: `message.received`, `message.delivered`, `message.read`, `message.failed`, `location.received`, `location.sharing.started`, `location.sharing.stopped`, `call.ringing`, `call.answered`, `call.speech`, `call.ended`. Every delivery carries exactly three signature headers: `X-Webhook-Event`, `X-Webhook-Timestamp`, `X-Webhook-Signature`, plus `X-Webhook-Subscription-ID`.
4xx identifies caller or authorization errors; a missing chat returns 404; 401 means a missing or invalid bearer (`AUTH_BYPASS=1` is local development only).
A failed SMS receipt reports the actual integration URL, operation, HTTP status and bounded error code when supplied. HTTP 401 inside that receipt refers to wisent-integrations rejecting Most, not the caller's authentication to Most. Missing provider identifiers and invalid JSON are failures, not queued messages.
501 means no executable capability: the selected composition has no transport for the requested service. Do not enable an unavailable transport merely to suppress the error.
503 means a configured dependency or the chat's pinned worker is unavailable — restore the assigned worker; there is no cross-worker failover of an existing chat.