Spoonity Platform API Reference#
Spoonity is a marketing and loyalty platform for quick-service and
fast-casual restaurant brands. This is the API reference for the services
that make it up: passwordless customer sign-in, dynamic content, short/deep
links and QR codes, digital wallet loyalty passes, analytics, promotions, feature
flags for the apps, the operator dashboard that ties them together, and the MCP
server that lets an AI agent
act on all of the above.
Every page here is served as plain, self-contained HTML with no required
JavaScript, and as raw Markdown at the same path plus .md — pick whichever
your client (human or automated) prefers.
The services#
| Service | What it does | Who calls it |
|---|---|---|
| Auth | Passwordless sign-in for a brand's end customers: one-time codes over SMS/WhatsApp/email, magic links, passkeys, Sign in with Apple/Google, and out-of-band approval for POS terminals. Returns a loyalty session alongside its own tokens, so existing loyalty calls keep working. | Your brand's mobile app, web ordering, kiosks and POS. Not your backend — this is where your customers authenticate. |
| CMS | Dynamic content for apps and web: content "spaces" (screens/sections), reusable content blocks, media, A/B experiments, personalization, webhooks. | Your app/web client fetches content at runtime; your backend manages it via the API. |
| Links | Short links, platform-aware deep links, QR code generation, click analytics, geo/OS-based routing, Link-in-Bio pages. | Your backend creates and manages links; the short-link redirect itself is public and unauthenticated. |
| Wallet | Apple Wallet and Google Wallet loyalty passes — enroll a customer, issue a pass, keep it updated. | Your backend calls one endpoint (POST /v1/enroll/session) to start an enrollment; the resulting link is what you hand the customer. |
| Insights | Analytics and reporting across the platform: the semantic layer and dashboards behind Prism's own reporting UI. | Consumed through Prism's Insights section, the standalone Insights app at insights.spoonity.com and the MCP server, never with a vendor API key. See Insights for the current integration surface. It is not a general-purpose public API the way CMS, Links, and Wallet are. |
| Offers | The promotions engine: prices a cart against the merchant's promotions and loyalty rewards, decides how they stack, and returns the discount per line with a reason code for every offer that did not apply. Also the promotion catalog and policy admin API, and a POS check surface. | Kiosks, ordering apps and channel backends (/v1/evaluate), a POS at pay time (/partners/pos), and merchant back offices or Prism for the catalog. See Offers. |
| Flags | Feature flags and experiments for a brand's apps: per-environment definitions with targeting rules, percentage rollouts and a kill switch, evaluated locally by the Swift, Kotlin and React Native SDKs, plus server-side evaluation, impressions and conversion events. | Your apps (through an SDK, with a client key) and your backend (with a server key). Flags are managed in Prism or the Flags console. See Flags. |
| Prism | The operator dashboard that puts the services above, the loyalty platform's own console sections, Apex, Ordering, feature flags and promotions behind one login, one vendor switcher, and one settings area (including API key management for CMS, Links, and Wallet). | Spoonity operators, in a browser. Prism's own /api/* is not a public integration surface; see Authentication. |
| MCP Server | mcp.spoonity.com — wraps the loyalty platform, Links, CMS, Apex marketing automation and Insights as tools, resources and prompts an AI agent can call. Not a REST API you hold a key for; a person connects an MCP client and signs in with their own Spoonity account. |
AI agents (Claude, ChatGPT, or any MCP client), acting on a signed-in operator's behalf. See MCP Server. |
Which one do I need?#
- "I want my customers to sign in to my app without a password." → Auth
- "I want to change what shows up in the app/website." → CMS
- "I want a shareable/trackable short link, a deep link into the app, or a QR code." → Links
- "I want to put a loyalty card in the customer's Apple Wallet or Google Wallet." → Wallet
- "I want to apply promo codes, deals, combos or loyalty rewards to a cart and get the discount back." → Offers
- "I want to turn a feature on for some customers, roll it out by percentage, or switch it off without an app release." → Flags
- "I want to pull reporting/analytics numbers." → Insights — but check its page first: it may not expose a direct integrator API for what you want yet.
- "I'm a Spoonity operator and I want to manage my vendor's settings, API
keys, or see an audit log." → that's Prism itself, at
https://prism.spoonity.com— not an API you integrate with, a dashboard you sign in to. Its own/api/*surface is documented at Prism for completeness, not as something to build against. - "I want an AI agent (Claude, ChatGPT, …) to be able to act across the platform on my behalf — look up a customer, draft content, build a campaign." → MCP Server. Not something your code calls directly; a person connects their chat client to it and signs in with their own Spoonity account.
If you're still not sure, Conventions and Authentication are worth reading regardless — they cover what's actually shared across services (and, just as importantly, what isn't) before you commit to one.
Before you write any code#
Two pages apply no matter which service you're integrating with:
- Conventions — base URLs per environment, versioning, error response shapes, pagination, rate limits, timestamp formats, vendor scoping, idempotency. Read this before assuming CMS's rules apply to Links, or Links's apply to Wallet — several of them differ, and that page says exactly where.
- Authentication — every auth mechanism in use:
CMS's and Links's scoped API keys (different scope vocabularies, same
underlying mechanism), Wallet's per-program keys, Prism's operator-only
session cookie, and the internal service-to-service identity used between
Spoonity's own services. Includes the exact header each service expects
(
X-API-Keyvs.Authorization: Bearer— they are not interchangeable) and the current, real limitation on managing CMS/Links keys through Prism.
All pages#
| Page | Contents | HTML | Raw Markdown |
|---|---|---|---|
| Index (this page) | Orientation, service directory, links to everything else | /docs | /docs/index.md |
| Conventions | Cross-service rules: base URLs, versioning, errors, pagination, rate limits, timestamps, vendor scoping, idempotency | /docs/conventions | /docs/conventions.md |
| Authentication | Every auth mechanism, scope vocabulary, and header, per service | /docs/authentication | /docs/authentication.md |
| Auth | Passwordless consumer sign-in: one-time codes, magic links, passkeys, social sign-in, POS pairing, sessions and tokens | /docs/auth | /docs/auth.md |
| CMS | Spaces, content blocks, media, experiments, personalization, webhooks, delivery API | /docs/cms | /docs/cms.md |
| Links | Short links, deep links, QR codes, click analytics, Link-in-Bio | /docs/links | /docs/links.md |
| Wallet | Apple/Google Wallet enrollment and pass management | /docs/wallet | /docs/wallet.md |
| Insights | Analytics and reporting | /docs/insights | /docs/insights.md |
| Offers | Promotions engine: cart evaluation, stacking, reason codes, redemption lifecycle, promotion catalog and policy, POS check | /docs/offers | /docs/offers.md |
| Flags | Feature flags: SDK keys, local and server-side evaluation, definitions and targeting rules, segments, impressions, events, change log | /docs/flags | /docs/flags.md |
| Prism | Prism's own BFF API: sign-in and MFA, Apex and ordering connections, audit log, saved tiles/dashboards/goals, digest and welcome preferences, feedback, product updates, Flags sync, and the /api/<product> proxy. Session-authenticated, not a public integration surface |
/docs/prism | /docs/prism.md |
| MCP Server | mcp.spoonity.com — the Model Context Protocol server: endpoint, transport, OAuth authentication, and the tool/resource/prompt groups it exposes to an AI agent |
/docs/mcp | /docs/mcp.md |
Machine-readable specs#
Auth, CMS, Links, Offers and Flags each ship an OpenAPI 3.1 spec:
| Service | Spec | Version | Paths |
|---|---|---|---|
| Auth | /docs/openapi/auth.yaml | 1.0.0 | 60 |
| CMS | /docs/openapi/cms.yaml | 1.5.0 | 70 |
| Links | /docs/openapi/links.yaml | 1.3.0 | 56 |
| Offers | /docs/openapi/offers.yaml | 0.1.0 | 37 |
| Flags | /docs/openapi/flags.yaml | 1.0.0 | 41 |
The Auth spec is generated by the service itself and also served live at
https://auth.spoonity.com/openapi.json. The Flags spec is too, at
https://flags.spoonity.com/openapi.json.
Wallet, Insights, Prism, and the MCP server have no OpenAPI spec today — their pages (Wallet, Insights, Prism, MCP Server) are the closest thing to a machine-readable contract for them, written to the same uniform per-endpoint structure as the CMS and Links pages so a model can parse all six the same way even without a formal spec for four of them. (The MCP server's own per-tool input schemas — the closest thing it has to an OpenAPI spec — live in its source repository, not here; see its page's "Tool groups" section.)
For AI agents#
A one-line index of every page, meant for automated consumption, is served
at /llms.txt (and /docs/llms.txt),
following the llms.txt convention. Every page on
this site is also available as raw Markdown at its HTML path plus .md
(see the table above) — no JavaScript execution or HTML parsing required to
read any of them in full.