Most/Docs

The message bridge surfaces

The canonical mutation surface is a Linq-compatible /v3 HTTP API with bearer authentication backed by finite Skarbiec capabilities. Events flow back out as HMAC-signed webhooks with bounded retry; attachments use independently expiring signed URLs.

Primary interfaces#

  • HTTP API — canonical mutation, account-adoption, and webhook-subscription interface: `GET /v3/accounts`, `POST /v3/accounts/messages-app/import`, `POST /v3/chats`, message, reaction, typing, voice, edit, unsend, 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 adopt-messages`, and completion requires accepted imported history or an actual `message.delivered` / `message.read` provider receipt.
  • Health API — `GET /healthz`, unauthenticated and secret-free; exposes build identity and active composition.
  • Attachment API — expiring HMAC-signed `GET /v3/attachments/{id}?exp=…&sig=…`.
  • Worker protocol — `/internal/worker/connect`, protected by mTLS and a dedicated bearer capability; the wire contract lives in docs/remote_worker_protocol.md.
  • Operator diagnostics — loopback-only `/internal/diagnostics/imessage/*`.
  • Automation — `most-cli accounts` lists retained source metadata and `most-cli adopt-messages` imports the canonical Messages account. The stdio `most-mcp` server remains read-only.

Sending and continuing conversations#

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.

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.

Signed inbound webhooks#

When a transport observes an inbound message or status change and a matching webhook subscription exists, Most normalizes and persists the event, then delivers an HMAC-signed webhook with bounded retry. The receiver can verify the raw body and timestamp; attachment access uses independently expiring signed URLs.

Signature scheme
HMAC-SHA256 over "{timestamp}.{raw_body}"
# WISENT_LINQ_COMPAT=1 additionally emits legacy X-Linq-* headers

Failure contract#

  • 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).
  • 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.