Conventions#
Rules that hold across more than one Spoonity service, written down once instead of five times. Read this after 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 | — |
| 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.comis 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 alsoPOST /enroll/app-sessionwith 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 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.
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 explicitAccept-Version: v1(the only value it currently recognizes), and echoes the version it used back in anX-API-Versionresponse 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 fieldsvariant_a/variant_b/split_pct(superseded byvariants[]) are still accepted without any deprecation header.Links has no
Accept-Version/X-API-Versionmechanism and no deprecation headers at all. Its version lives only in the URL path (/api/v1); there is currently nov2and 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/readyzcarry 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):
{ "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):
{ "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):
{ "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.
Prism's own /api/* (not an integration surface, shown for completeness
since you may see it in a browser network tab):
{ "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:
{
"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.
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:
{ "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:
{ "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:
{ "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:
- 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.
- 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 trailingZ. The one stated exception is the content-preview token'sexpires_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'stimestamp) alike, are serialized as full ISO 8601 with a trailingZ. The bareYYYY-MM-DD HH:MM:SSshape appears only on the local SQLite development backend.Wallet returns full ISO 8601 with a trailing
Zon every timestamp observed (createdAt,lastUsedAt,revokedAt,expiresAt).Offers returns epoch milliseconds for record times (
created_at,updated_at,committed_at, historyat), ISO 8601 with a trailingZfor lock and hold expiries (lock.expires_at,hold_expires_at), andYYYY-MM-DDUTC dates in usage series.Flags uses Unix epoch milliseconds (integers) in the SDK API (
time,changeNumber,till) and full ISO 8601 with a trailingZon 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 or 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. The consumer-facing
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 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. 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.