Spoonity API Documentation View as Markdown Prism console

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:

Versioning#

Support for explicit version negotiation is not uniform:

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:

  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#

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.

See also#