← Dearly for Muse

API Documentation

Last updated: 27 September 2026

Dearly is a raw HTTP API (not an MCP server) that lets Muse remember occasions, send reminders, and place physical postcard, flower, and gift orders on a user's behalf. Its machine-readable capability document is published at GET https://api.dearlymuse.com/connector/openapi.json.

What Muse handles vs. what Dearly handles

Muse owns the user relationship entirely: authentication, conversation, deciding what to say and when, and getting the user's explicit confirmation before every quote, draft, and charge. Dearly never talks to the user directly — no email, text, or push, ever.

Dearly owns fulfilment: it stores exactly what's needed to send a postcard or gift, tenant-scoped by the identity resolved from the caller's API key (never client-asserted), prices orders, calls PostGrid/Stripe/Goody, and enforces that a single payment can never produce two orders. Dearly has no way to reach the end user independent of Muse.

Authentication

Every route other than /health, /ready, and the two provider webhooks requires Authorization: Bearer <api key>. An API key is minted by the operator and tied to exactly one Dearly user — there is no way for a caller to assert a different identity than the key it presents. An invalid, missing, or revoked key returns 401.

How Muse should operate the connector

  1. Dearly is the source of truth. Never infer that an occasion, payment, or order exists without reading it from the connector.
  2. Default new occasions to reminder_only. A muse_candidate remains inactive until the user explicitly confirms it.
  3. Poll POST /v1/reminders/claim from a daily scheduled task. Say nothing when the returned list is empty.
  4. Suggest a physical gift at most once per reminder. If the user is interested, call GET /v1/occasions/{id}/fulfillment-choices and offer the returned postcard, flower, and gift ideas conversationally — these are themes, not claims of product availability.
  5. Flowers and gifts both browse Goody's real catalogue via the connector; never invent products or availability.
  6. Before quoting any gift, flower, or postcard, read the recipient's full delivery address back to the user and get explicit confirmation. Send addressConfirmed: true with the quote/draft/selection request.
  7. For a postcard, generate exactly four distinct, occasion-aware front images and a short suggested back message for each, and save them with POST /v1/postcard-options.
  8. Let the user accept or edit the suggested back message and choose a supported font, size, and postcard size before creating the priced draft via /v1/postcard-options/{id}/select.
  9. Show both masked sides and every price line (minor units, in the quoted currency) before requesting approval to pay.
  10. Call the pay endpoint only after explicit user approval. Only state: confirmed with a returned order means fulfilment was actually ordered.
  11. Never say "sent" for an order in the placed state — say "ordered". Only say "sent" once a provider callback records shipped.
  12. Dearly never contacts the user directly by email, text, or push. All communication stays inside Muse.

Access requirements