# 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](/docs/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](/docs/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](/docs/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](/docs/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](/docs/mcp). |

## Which one do I need?

- **"I want my customers to sign in to my app without a password."** →
  [Auth](/docs/auth)
- **"I want to change what shows up in the app/website."** → [CMS](/docs/cms)
- **"I want a shareable/trackable short link, a deep link into the app, or a
  QR code."** → [Links](/docs/links)
- **"I want to put a loyalty card in the customer's Apple Wallet or Google
  Wallet."** → [Wallet](/docs/wallet)
- **"I want to apply promo codes, deals, combos or loyalty rewards to a cart
  and get the discount back."** → [Offers](/docs/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](/docs/flags)
- **"I want to pull reporting/analytics numbers."** → [Insights](/docs/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](/docs/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](/docs/mcp). 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](/docs/conventions) and
[Authentication](/docs/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](/docs/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](/docs/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-Key` vs. `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) | [/docs/index.md](/docs/index.md) |
| Conventions | Cross-service rules: base URLs, versioning, errors, pagination, rate limits, timestamps, vendor scoping, idempotency | [/docs/conventions](/docs/conventions) | [/docs/conventions.md](/docs/conventions.md) |
| Authentication | Every auth mechanism, scope vocabulary, and header, per service | [/docs/authentication](/docs/authentication) | [/docs/authentication.md](/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) | [/docs/auth.md](/docs/auth.md) |
| CMS | Spaces, content blocks, media, experiments, personalization, webhooks, delivery API | [/docs/cms](/docs/cms) | [/docs/cms.md](/docs/cms.md) |
| Links | Short links, deep links, QR codes, click analytics, Link-in-Bio | [/docs/links](/docs/links) | [/docs/links.md](/docs/links.md) |
| Wallet | Apple/Google Wallet enrollment and pass management | [/docs/wallet](/docs/wallet) | [/docs/wallet.md](/docs/wallet.md) |
| Insights | Analytics and reporting | [/docs/insights](/docs/insights) | [/docs/insights.md](/docs/insights.md) |
| Offers | Promotions engine: cart evaluation, stacking, reason codes, redemption lifecycle, promotion catalog and policy, POS check | [/docs/offers](/docs/offers) | [/docs/offers.md](/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) | [/docs/flags.md](/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) | [/docs/prism.md](/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) | [/docs/mcp.md](/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](/docs/openapi/auth.yaml) | 1.0.0 | 60 |
| CMS | [/docs/openapi/cms.yaml](/docs/openapi/cms.yaml) | 1.5.0 | 70 |
| Links | [/docs/openapi/links.yaml](/docs/openapi/links.yaml) | 1.3.0 | 56 |
| Offers | [/docs/openapi/offers.yaml](/docs/openapi/offers.yaml) | 0.1.0 | 37 |
| Flags | [/docs/openapi/flags.yaml](/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](/docs/wallet), [Insights](/docs/insights),
[Prism](/docs/prism), [MCP Server](/docs/mcp)) 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`](/llms.txt) (and [`/docs/llms.txt`](/docs/llms.txt)),
following the [llms.txt](https://llmstxt.org/) 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.

## See also

- [Conventions](/docs/conventions)
- [Authentication](/docs/authentication)
- [Auth](/docs/auth)
