# Conventions

Rules that hold across more than one Spoonity service, written down once
instead of five times. Read this after [index](/docs/index) and before any
per-service page — it will save you from assuming CMS's behavior also applies
to Links, or Links's to Wallet.

**The headline rule of this page: don't assume uniformity.** Spoonity's
services were built by different teams at different times. Where two services
genuinely agree, this page says so once. Where they disagree — and several
things below do — this page says so plainly, service by service, because a
false claim of consistency costs you more debugging time than an honest
inconsistency.

## Base URLs

| Service | Production | Local development |
|---|---|---|
| CMS | `https://cms.spoonity.com/api/v1` | `http://localhost:3700/api/v1` |
| Links | `https://links.spoonity.com/api/v1` | `http://localhost:3500/api/v1` |
| Wallet | `https://wallet-api.spoonity.com` | `http://localhost:3000` |
| Insights | not directly reachable — see [Insights](/docs/insights) | — |
| Offers | `https://offers.spoonity.com` | `http://localhost:8080` |
| Flags | `https://flags.spoonity.com` (SDK API under `/sdk/v1`, admin API under `/admin/v1`) | `http://localhost:8080` |
| Prism (`/api/*`) | `https://prism.spoonity.com/api/*` | — |

Notes:
- CMS's production Cloud Run host (`https://spoonity-cms-285397558465.us-central1.run.app/api/v1`)
  is also live and answers identically; `cms.spoonity.com` is preferred.
- **Wallet has no `/v1` (or any version) segment in its base URL** — the
  version lives further into the path instead, e.g. `POST /v1/enroll/session`,
  `POST /v1/api-keys`, but also `POST /enroll/app-session` with no version
  segment at all. Don't assume `{base}/v1/...` is the pattern for every Wallet
  route the way it is for CMS and Links.
- Insights has no stable, publicly documented base URL today. The service
  (`insights-api`) is a private, IAM-gated Cloud Run service, reachable only by
  an allow-listed Google identity or through one of its three brokers (Prism's
  own BFF, insights.spoonity.com and the Spoonity MCP server), never directly
  by an outside integrator. See [Insights](/docs/insights) for exactly what is and isn't
  reachable.
- `Prism (/api/*)` is listed for completeness, not as an integration surface —
  it is operator-session-only. See [Authentication](/docs/authentication).

## Versioning

Support for explicit version negotiation is **not uniform**:

- **CMS** is the only service with a version-negotiation header. It defaults
  every request to `v1`, accepts an explicit `Accept-Version: v1` (the only
  value it currently recognizes), and echoes the version it used back in an
  `X-API-Version` response header. CMS has a helper for RFC 8594
  deprecation headers (`Deprecation`, `Sunset`), but no route calls it
  today, so no response carries them. The legacy experiment fields
  `variant_a`/`variant_b`/`split_pct` (superseded by `variants[]`) are still
  accepted without any deprecation header.
- **Links** has no `Accept-Version`/`X-API-Version` mechanism and no
  deprecation headers at all. Its version lives only in the URL path
  (`/api/v1`); there is currently no `v2` and no stated plan for one.
- **Wallet** versions by path segment only (`/v1/...`), with no header
  negotiation.
- **Offers** versions by path segment only (`/v1/...`), with no header
  negotiation. Its POS surface (`/partners/pos/*`) and `/readyz` carry no
  version segment.

- **Flags** versions by path segment only (`/sdk/v1`, `/admin/v1`,
  `/auth/v1`), with no header negotiation. It adds response fields without a
  version bump, so clients must ignore fields they do not know.
- **Prism's `/api/*`** is unversioned — it's an internal proxy, not a
  contract integrators code against.

Don't send `Accept-Version` to Links or Wallet expecting it to do anything; it
is silently ignored (both are ordinary Express apps with no middleware that
reads it).

## Error envelope

There are **four different shapes** in production, not one:

**CMS and Links** (same two field names, not the same code set):
```json
{ "error": "insufficient_scope", "message": "This API key does not have the 'content:write' scope" }
```
`error` is a short machine-readable code (`bad_request`, `unauthorized`,
`forbidden`, `not_found`, `insufficient_scope`, `rate_limit`, …); `message` is
for humans. Some errors add extra fields alongside the two required ones —
e.g. an invalid-scope response echoes `valid_scopes`, a CMS invalid-role
response echoes `valid_roles` (Links has no roles), and a CMS
space-status-transition error adds `current_status` / `requested_status`.
The two services do not share one error format beyond those two fields.
Links answers `"error": "AppError"` (the class name, not a short code) for
errors raised inside its link, deep-link, bio-page and webhook services, so
read `message` too. CMS routes return their own codes and do not raise
`AppError`; an unhandled CMS error is `"error": "internal_error"`.

**Wallet** (`wallet-api.spoonity.com`):
```json
{ "error": "programId does not match this API key's scope." }
```
One field. There is no separate machine-readable code — `error` *is* the
human-readable sentence. The exception is `/media/pass-image`, which answers
`{ "error": "<code>", "message": "…" }`. Don't write a client that switches on `error` by
exact string match against a stable enum; Wallet makes no such promise.

**Offers** (`offers.spoonity.com`):
```json
{ "error": { "code": "INVALID_REQUEST", "message": "Promotion validation failed",
    "issues": [ { "path": "discount_amount", "message": "percent discounts must be between 0 and 100" } ] } }
```
`error` is an object, not a string. `code` is an upper-case machine-readable
code (`INVALID_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`,
`VERSION_CONFLICT`, `OFFERS_UNAVAILABLE`, ...), `message` is for humans, and
`issues[]` (one `{ path, message }` per field) appears on validation errors.
Some codes add fields inside `error`, such as `version` on a conflict. The
full list is at [Offers](/docs/offers#error-codes).

**Prism's own `/api/*`** (not an integration surface, shown for completeness
since you may see it in a browser network tab):
```json
{ "error": "unauthorized", "detail": "Not signed in" }
```
Same idea as CMS/Links, but the human-readable field is named `detail`, not
`message`.

**Flags** (`flags.spoonity.com`) returns RFC 7807 problem documents with
`Content-Type: application/problem+json`:
```json
{
  "type": "https://flags.spoonity.com/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "missing SDK key",
  "instance": "/sdk/v1/definitions"
}
```
`code` is the stable machine-readable field (`invalid_request`,
`unauthorized`, `forbidden`, `not_found`, `conflict`, `version_conflict`,
`payload_too_large`, `rate_limited`, `internal_error`); `detail` is for
humans. Validation failures add `errors: [{ "path", "message" }]` and a `429`
adds `retryAfter`. There is no `error` or `message` field, so a CMS/Links
error adapter will not read it. See [Flags](/docs/flags#conventions).

**Practical consequence:** a client that talks to more than one of these
services needs a per-service error adapter. There is no shared error type
across the platform today.

## Pagination

Two different styles are in production, and both are real:

**Page-based — CMS and Links.** Query params `page` (1-based) and, usually,
`limit` — capped per endpoint (CMS's `/activity` caps at 100, `/media` at
100; CMS's `/spaces` instead calls the same parameter `per_page`, capped at
200 — even within CMS the parameter name isn't fully consistent, so check the
specific endpoint's docs rather than assuming `limit` everywhere). The
response carries a sibling object (`pagination` on most CMS/Links list
endpoints, `meta` on CMS's `/spaces` and `/experiments`), shaped like:
```json
{ "page": 1, "limit": 50, "total": 214, "total_pages": 5 }
```
The `meta` object on CMS's `/spaces` and `/experiments` says `per_page`
where `pagination` says `limit` (`/experiments` takes `per_page`, capped at
100).

**Cursor-based — Prism's own audit API only** (`GET /api/audit`, not a
public integration surface, shown here because it's the platform's other real
pagination style and a genuine contrast with CMS/Links). Query params are
`cursor` (an opaque token from a previous response's `nextCursor`; omit it
for the first page) and `limit` (1–50, default 30 — out-of-range values are
clamped, not rejected). The response is:
```json
{ "events": [ /* … */ ], "nextCursor": "eyJ0cyI6Ii4uLiJ9" }
```
`nextCursor` is `null` when there is no next page.

Offers uses a third variant on its one paginated list,
`GET /v1/admin/promotions/{id}/redemptions`: `limit` plus a `before` cursor,
answered with `next_before` (`null` on the last page). Its other lists take
a `limit` and return everything up to it.

**Cursor-based, in the Flags admin API** (`/admin/v1`). Query params are
`cursor` (opaque; from a previous `nextCursor`) and `limit` (1 to 200,
default 50). Unlike Prism's audit API, out-of-range values and cursors the
service did not issue are **rejected** with `400 invalid_request`, not
clamped. The response is:
```json
{ "items": [ /* … */ ], "nextCursor": "Y2hlY2tvdXQtcmVkZXNpZ24" }
```
with `nextCursor: null` on the last page. The Flags SDK API does not paginate;
it uses change numbers (`since` / `till`) instead.

Neither style is "the standard" — pick the one the endpoint you're calling
actually documents, and never assume a `page` parameter works against a
cursor-paginated endpoint or vice versa.

## Rate limits

| Service | Surface | Limit | Keyed by | Window |
|---|---|---|---|---|
| CMS | Management API (`X-API-Key` / dashboard JWT) | 100 req/min (`RATE_LIMIT_API_RPM`, default) | Client IP | 60s |
| CMS | Content delivery API (`/content/`, `/track/`, `/app-config`) | 500 req/min (`RATE_LIMIT_DELIVERY_RPM`, default) | Client IP | 60s |
| CMS | `/auth/login` and friends | 10 req/min | Client IP | 60s |
| Links | Management API (`X-API-Key` / dashboard JWT) | 100 req/min (`RATE_LIMIT_API_RPM`, default) | **Hashed credential** (JWT or API key), not IP | 60s |
| Links | Redirect endpoints | 1000 req/min (`RATE_LIMIT_REDIRECT_RPM`, default) | Client IP | 60s |
| Links | `/auth/login` and friends | 10 req/min | Client IP | 60s |
| Wallet | API-key-authenticated calls: `/v1/enroll/session` and `/v1/members/favorite-store` share one bucket | 600 requests | Client IP | **15 minutes**, not 60s |
| Wallet | Operator login/vendor-select | 30 requests | Client IP | 15 minutes |
| Wallet | Public endpoints sharing one bucket: member lookup, `/api/site/*`, `/enroll`, `/enroll/s/:key`, `/enroll/app-session` | 120 requests | Client IP | 15 minutes |
| Flags | SDK reads (`/sdk/v1/definitions`, `memberships`, `segments`, `flags`, `stream`) | 600 requests (default) | SDK key | 60s, token bucket |
| Flags | SDK batches (`/sdk/v1/impressions`, `events`) | 60 requests (default) | SDK key | 60s, token bucket |
| Flags | `POST /sdk/v1/evaluate` with a server key | 6000 evaluated contexts (default) | SDK key | 60s, token bucket |
| Flags | Admin API (`/admin/v1`) | 300 requests (default) | Signed-in identity | 60s, token bucket |
| Flags | `/auth/v1/login`, `/auth/v1/select-vendor` | 10 requests | Client IP | 60s |

Two things are easy to get wrong here:
1. **The window length differs** — CMS and Links budget per 60 seconds,
   Wallet budgets per 15 minutes. "600/15min" is not "40/min"; don't convert
   between them and assume the limiter smooths evenly across the window.
2. **The key differs.** CMS limits its management API per client IP. Links
   deliberately limits its management API per *credential* instead (a hashed
   JWT or API key), specifically so one vendor behind a shared NAT can't
   exhaust another vendor's budget. If you're behind a proxy or shared
   egress IP, Links will treat you fairly and CMS may not.

Offers has no request rate limiter. It bounds request size instead (200
lines and 2000 units per cart, 50 entries per list), and a POS is expected
to time out its own `check` call at 800 ms.

All of the rate-limited services above set the standard `RateLimit-*` response headers
(`standardHeaders: true` in `express-rate-limit`) and respond `429` with
their normal per-service error envelope (CMS/Links: `{"error":"rate_limit",
"message":"…"}`), except Wallet, whose `429` body is express-rate-limit's
default plain-text message, not JSON. Flags uses its own token-bucket
limiter rather than `express-rate-limit`: it sets the same `RateLimit-Limit`,
`RateLimit-Remaining` and `RateLimit-Reset` headers (the last is seconds until
the bucket is full again), and a `429` is a problem document with
`code: "rate_limited"`, a `Retry-After` header and `retryAfter` in the body.

## Timestamps

- **CMS** documents an explicit contract: input accepts ISO 8601
  (`2026-07-28T15:04:05.000Z`); output is normalized to
  `'YYYY-MM-DD HH:MM:SS'` — UTC, space separator, **no trailing `Z`**. The one
  stated exception is the content-preview token's `expires_at`, which is a
  JWT expiry returned as true ISO 8601.
- **Links** has no equivalent stated contract. In production (MySQL) its
  timestamps, persisted (`created_at`, `updated_at`, `expires_at`,
  `clicked_at`) and computed (a webhook payload's `timestamp`) alike, are
  serialized as full ISO 8601 with a trailing `Z`. The bare
  `YYYY-MM-DD HH:MM:SS` shape appears only on the local SQLite development
  backend.
- **Wallet** returns full ISO 8601 with a trailing `Z` on every timestamp
  observed (`createdAt`, `lastUsedAt`, `revokedAt`, `expiresAt`).

- **Offers** returns epoch milliseconds for record times (`created_at`,
  `updated_at`, `committed_at`, history `at`), ISO 8601 with a trailing `Z`
  for lock and hold expiries (`lock.expires_at`, `hold_expires_at`), and
  `YYYY-MM-DD` UTC dates in usage series.

- **Flags** uses Unix epoch **milliseconds** (integers) in the SDK API
  (`time`, `changeNumber`, `till`) and full ISO 8601 with a trailing `Z` on
  admin resources (`createdAt`, `updatedAt`).

Parse leniently: don't assume a missing `Z` means "not UTC" (it doesn't — see
CMS above), and don't assume every field on a given service uses the same
shape (CMS's preview-token `expires_at` doesn't).

## Vendor scoping

For a scoped API key, a legacy vendor-wide key, or a dashboard JWT session
(CMS or Links), the vendor is **implicit in the credential** — it was fixed
when the key was minted or the session was issued. None of the documented
endpoints in [CMS](/docs/cms) or [Links](/docs/links) take a vendor id as a
request parameter, and none should be sent one.

Wallet scopes a key to one **program**, not directly to a vendor id — you
pass `programId` in the request; the vendor follows from which program that
is.

Offers follows the same rule: a vendor API key and a POS key
(`X-Spoonity-POS-Key`) each belong to one vendor, and no request body or
query parameter names one.

Flags works the same way: an SDK key belongs to one environment of one
brand, so the SDK API has no vendor parameter at all, and a Flags admin
session is bound to one vendor when it is issued. Flags admin paths do name
the workspace (`/workspaces/1047166/…`, `/environments/1047166:production/…`),
but only the session's own vendor resolves; any other answers `404`.

Among these management APIs, a vendor id is a client-supplied value only on
the internal service-to-service paths: the Google-OIDC path used by Prism's
own BFF and other trusted service accounts, and Links's `slp_` platform keys
(`X-Spoonity-Vendor`; Links also reads an optional `X-Spoonity-Vendor-Name`
when it auto-provisions a vendor, which Prism's BFF does not send). Neither
is available to, or needed by, an external integrator. See
[Authentication](/docs/authentication). The consumer-facing
[Auth](/docs/auth) API is different: a brand's app names its tenant on every
request with `X-Spoonity-Vendor`.

## Idempotency

CMS, Links, Wallet, Offers and Prism's BFF do not accept a client-supplied
idempotency key (e.g. an `Idempotency-Key` header). [Auth](/docs/auth) does,
on `POST /v1/otp/start`, `POST /v1/deferred/init` and
`POST /v1/deferred/upgrade`.

Offers uses ids from the request body instead. `POST /v1/evaluate` with the
same `evaluation_id` replaces the previous result for that checkout attempt
rather than creating a second one. On the POS surface, `check` is keyed by
`store_id` + `check_id`, and `close` and `void` are idempotent on
`pos_transaction_id`. See [Offers](/docs/offers#idempotency). Elsewhere, if a
`POST` fails partway (timeout, dropped connection), a retry is not guaranteed
safe unless the specific endpoint says otherwise.

A few operations are naturally idempotent by construction and are documented
as such at the endpoint: CMS's and Links' `DELETE /vendor/api-keys/:id`
(revoke) is explicitly safe to repeat. Wallet's enrollment flow relies on the
caller supplying its own `externalId` as a de-duplication key rather than on
any request-level idempotency mechanism. Flags guards definition writes with
optimistic concurrency instead: `PUT …/definition` takes `expectedVersion`,
and a stale value is `409 version_conflict`, so a blind retry of the same
write cannot apply twice. Its create routes (`POST /admin/v1/workspaces`,
flags, segments, environments) answer `409 conflict` when the thing already
exists, which a retry can treat as success.

## See also

- [Index](/docs/index) — what each service is for and which one you need
- [Authentication](/docs/authentication) — every auth mechanism in detail
- [CMS](/docs/cms) · [Links](/docs/links) · [Wallet](/docs/wallet) ·
  [Insights](/docs/insights) · [Offers](/docs/offers) · [Flags](/docs/flags) · [Prism](/docs/prism)
