Spoonity API Documentation View as Markdown Prism console

Spoonity CMS API#

Spoonity CMS is the content-management and delivery system vendor teams use to publish dynamic content — banners, promos, onboarding slides, FAQs and more — into their branded apps and web properties. Two audiences call this API: vendor operators and integrations (dashboard users, CI jobs, agents) manage content, spaces, media, experiments and webhooks through the management API; and the vendor's own end-user-facing apps fetch published content at runtime through the public, unauthenticated Content Delivery API. Almost everything under /api/v1 other than content delivery, remote app config, tracking and experiment conversions requires authentication and is scoped to one vendor.

Base URL: https://cms.spoonity.com — all management, delivery and tracking routes below are mounted under /api/v1. A Cloud Run domain mapping fronts the underlying https://spoonity-cms-285397558465.us-central1.run.app, which still answers directly; prefer the branded host. Local development runs at http://localhost:3700. https://content.spoonity.com is the CMS MCP server, not an API base URL: it forwards some paths to this service, but integrations should call cms.spoonity.com. Uploaded media is served from https://media.spoonity.com.

Rate limits: the management API (spaces, blocks, media, experiments, analytics, webhooks, users, search, activity, vendor settings, api-keys, brand, targeting lookups, legacy content import) is limited to 100 requests/min/IP by default (RATE_LIMIT_API_RPM); the Content Delivery, remote App Config, and Tracking APIs get a higher budget of 500 requests/min/IP (RATE_LIMIT_DELIVERY_RPM); POST /api/v1/auth/login and POST /api/v1/auth/select-vendor are limited to 10 requests/min/IP. All three send standard RateLimit-* headers and a 429 with { "error": "rate_limit", "message": "..." } when exceeded.

The management limiter is mounted once per router, and several routers share the bare /api/v1 prefix, so one request can be counted more than once as it falls through them. A request to /media, /analytics, /experiments, /users, /brand, /activity, /search, /lookups, /webhooks, /vendor/api-keys or /blocks/{id}/rules costs about 3 units; the Translations routes cost 4; /auth/*, /vendor/settings and /vendor/api-key/* cost 5; POST /spaces/{spaceId}/blocks, PUT /spaces/{spaceId}/reorder and the legacy import cost 2; the other /spaces routes and /blocks/{id} cost 1. The effective per-minute budget on a route is the limit divided by its cost, so plan for about 20 requests/min/IP on /vendor/settings, for example.

Versioning: every request is implicitly v1. Send Accept-Version: v1 to be explicit — no other value is currently recognized, and an unrecognized value silently falls back to v1 rather than erroring. Every response carries X-API-Version: v1.

Timestamps: datetime fields accept ISO 8601 on input (2026-07-28T15:04:05.000Z) and are returned as 'YYYY-MM-DD HH:MM:SS' (UTC, space separator, no Z). The one exception is the preview-token expires_at, a JWT expiry computed in-process and returned as true ISO 8601.

Errors: most error responses are { "error": "<machine_code>", "message": "<human text>" }. Several routes omit message entirely and return bare { "error": "<machine_code>" }: every error in the Webhooks group except the URL rejections, which carry a message (invalid_events and not_found stay bare; see Webhook URL rules); every Personalization error except missing_fields; the 404 on DELETE /users/{id}; the 404 on GET /translations/coverage/{spaceId}; the Experiments already_running and not_running 400s; and every Experiments 404 not_found except the one on GET /experiments/{id} (so PUT /experiments/{id}, POST /experiments/{id}/start, POST /experiments/{id}/stop, POST /experiments/{id}/winner, DELETE /experiments/{id} and the public POST /experiments/{id}/convert). These are called out because they deviate from the shape used everywhere else.

Authentication#

CMS accepts three credential types, checked in this order by every authenticated route.

1. Dashboard JWT sessions#

Authorization: Bearer <jwt>. Issued by POST /auth/login (→ /auth/select-vendor for a multi-vendor user, or auto-completed for a single-vendor one), or re-scoped to another vendor with POST /auth/switch-vendor. A JWT session carries no scopes array, so it has full scope access to every resource — scope checks exist only to narrow what an API key can do, never a signed-in human. What a JWT session may do is bounded by its role (admin | editor | viewer), looked up from vendor_users at login time. An email with no vendor_users row for the vendor gets admin, so a vendor's first user is an admin by default.

2. Scoped API keys#

X-API-Key: sck_<64 hex chars>. Minted per-vendor via POST /vendor/api-keys (dashboard session only — see Vendor Settings & API Keys). A key carries:

3. Legacy vendor-wide API key#

X-API-Key: <key>. A single, unscoped key stored directly on the vendor row (rotated via POST /vendor/api-key/rotate, a dashboard-session-only route). It authenticates as scopes: ['*'] and role: 'admin' — full read/write access to everything for that vendor, with no per-resource scoping. It carries the same sck_ prefix as a scoped key, so the prefix alone does not tell the two apart. Prefer a named scoped key for new integrations; the legacy key exists for vendors that provisioned before scoped keys shipped.

4. Service-to-service (not a public integration path)#

A Google-signed OIDC ID token in Authorization: Bearer <id_token> from a Google Cloud service account on a server-side allowlist (TRUSTED_SERVICE_ACCOUNTS), plus a required X-Spoonity-Vendor: <spoonity_vendor_id> header to select the tenant (vendors are auto-provisioned on first call). This exists for Spoonity-operated infrastructure (e.g. an internal MCP server) — it is not something a vendor integrator configures, and it is not documented further here.

Vendor context#

Every management request needs a resolved vendor: a JWT session carries vendorId in its payload, an API key resolves it from the row it was minted against, and a service token resolves it from X-Spoonity-Vendor. A request that authenticates but resolves no vendor gets 403 forbidden ("No vendor context. Authentication required.").


Content Delivery API#

This is the public read surface — the one vendor-integrator apps actually hit at runtime to render content. No authentication, no vendor scoping headers: the vendor and space are named directly in the URL. Responses are cacheable (ETag + Cache-Control: public, max-age=…) and rate-limited at the higher 500 req/min/IP delivery budget.

Surviving a database outage. Both endpoints below serve from an in-process "last-known-good" cache when the database is unreachable, instead of a bare 500: the most recent successful response for the exact same request (vendor, space, every query parameter, X-Spoonity-User, and the experiment client_id) is replayed with X-Content-Stale: true, X-Content-Stale-Age: <seconds since it was cached>, and Cache-Control: no-store — no ETag, so a stale response can never be revalidated into a 304 and pinned in a client cache. The response body also carries "_stale": true and "_stale_age_seconds": <n>. A request whose exact shape has never been served successfully (or whose cached entry has aged past 24h) gets a 503 with Retry-After: 5 instead — never an invented empty content payload, which would tell an app "this vendor has no content" and get cached as such. This never affects the happy path: every request still queries the database and gets fully fresh content; the cache is consulted only on a database error, and a preview-token request is never cached or replayed. A genuine application bug still surfaces as a 500 — only a database-connectivity failure degrades.

GET /content/{vendorSlug}#

List every currently-published space for a vendor (used by apps to discover available content). Only spaces with status: published inside their start_at/end_at window are listed, ordered by priority descending. The response sends Cache-Control: public, max-age=60, s-maxage=300 and a weak ETag.

Auth: None — public.

Path parameters:

Name Type Description
vendorSlug string The vendor's slug, e.g. acme-cafe.

Query parameters:

Name Type Description
platform string One of all, app, web, mobile_web, desktop_web, watch, tv, car. mobile_web/desktop_web also match spaces tagged web; a plain web request only matches web (never a sub-channel-only space).
category string Filter by space category.
region string Filter by space region (spaces with no region always match).
daypart string Filter by space daypart (spaces with no daypart always match).
tags string Comma-separated tag list; a space matches if it has any of the listed tags.

Request example:

curl "https://cms.spoonity.com/api/v1/content/acme-cafe?platform=app&category=promotion"

Response example:

{
  "spaces": [
    {
      "id": 42,
      "name": "Summer Promo",
      "slug": "summer-promo",
      "platform": "app",
      "description": "Iced drinks banner",
      "published_at": "2026-06-01 14:00:00",
      "category": "promotion",
      "campaign_id": "summer26",
      "tags": ["seasonal", "lto"],
      "priority": 10,
      "region": null,
      "daypart": null,
      "default_locale": "en-CA",
      "start_at": null,
      "end_at": null,
      "block_count": 3,
      "targeting": {
        "region": null,
        "daypart": null,
        "store_ids": null,
        "audience": null,
        "min_visits": null,
        "max_visits": null,
        "active_hours": null,
        "active_days": null
      }
    }
  ],
  "vendor": { "name": "Acme Cafe", "slug": "acme-cafe" }
}

Errors:

Status Code Meaning
404 not_found No vendor with that slug
503 service_unavailable Database unreachable and nothing cached for this vendor yet (Retry-After: 5)

GET /content/{vendorSlug}/{spaceSlug}#

Fetch one space's published content: blocks, resolved against scheduling, targeting, dayparting, audience segmentation, running A/B/n experiments, translation overlays and personalization rules. This is the single most important endpoint in the CMS API — it is what a rendered app screen calls.

Auth: None — public. Optional X-Spoonity-User header lets the CMS resolve verified audience context (loyalty tier, visit count, segments) server-side against the Spoonity platform when configured; when it isn't, or resolution fails, client-declared query params are used instead (content availability never depends on the loyalty API being reachable).

Path parameters:

Name Type Description
vendorSlug string The vendor's slug.
spaceSlug string The space's slug.

Query parameters:

Name Type Description
platform string Channel filter — see the list endpoint above for umbrella-matching semantics.
device_type string phone, tablet, or desktop. Drives device_type personalization rules only — never filters which blocks are returned.
locale string Preferred locale, e.g. fr-CA. Overlays a block's translation for that locale when one exists and differs from the space's default.
region string Region filter (blocks/spaces with no region always match).
store_id string Store-level targeting filter.
local_time string Client local time HH:mm, used for active_hours dayparting.
timezone string Client timezone — informational only, not currently applied server-side.
daypart string Explicit daypart filter and personalization-rule input.
loyalty_tier string Client-declared loyalty tier (overridden by X-Spoonity-User resolution when available).
visit_count integer Client-declared visit count (same override behavior).
segments string Comma-separated Spoonity segment ids (same override behavior).
country string Drives country personalization rules only.
client_id string Stable per-client id for deterministic experiment bucketing (hashed modulo 100). May also be sent as the X-Client-Id header.
fallback string false disables graceful fallback resolution — an eligibility miss returns a plain 404 instead of trying the space's own or the vendor's default fallback.
preview_token string A JWT from POST /spaces/{id}/preview-token. Bypasses status/window/targeting eligibility entirely for the exact space it was minted for; an invalid/expired/mismatched token is a hard 401, never a silent fallback to the published view.

Request example:

curl "https://cms.spoonity.com/api/v1/content/acme-cafe/summer-promo?platform=app&locale=fr-CA&loyalty_tier=gold"

Response example:

{
  "space": {
    "name": "Summer Promo",
    "slug": "summer-promo",
    "platform": "app",
    "published_at": "2026-06-01 14:00:00",
    "category": "promotion",
    "campaign_id": "summer26",
    "tags": ["seasonal", "lto"],
    "priority": 10,
    "region": null,
    "daypart": null,
    "default_locale": "en-CA",
    "start_at": null,
    "end_at": null,
    "targeting": { "region": null, "daypart": null, "store_ids": null, "audience": null, "min_visits": null, "max_visits": null, "active_hours": null, "active_days": null }
  },
  "blocks": [
    {
      "id": 101,
      "block_type": "hero_banner",
      "title": "Cold Brew Season",
      "subtitle": "Now $2 off",
      "body": null,
      "image_url": "https://media.spoonity.com/abc123_opt.webp",
      "background_url": null,
      "video_url": null,
      "poster_url": null,
      "image_asset": { "width": 1920, "height": 1080, "variants": { "thumb": { "url": "https://media.spoonity.com/abc123_thumb.webp", "width": 200, "height": 113 } } },
      "cta_text": "Order now",
      "cta_url": "https://links.spoonity.com/x7Qp9",
      "cta_deeplink": null,
      "cta_link_id": "88",
      "config": {},
      "platform": null,
      "sort_order": 0,
      "tags": [],
      "menu_item_id": null,
      "region": null,
      "store_ids": [],
      "audience": {},
      "_locale": "fr-CA"
    }
  ],
  "vendor": { "name": "Acme Cafe", "slug": "acme-cafe" },
  "_locale": "fr-CA",
  "_tracking": { "endpoint": "/api/v1/track/acme-cafe", "space_id": 42, "campaign_id": "summer26" },
  "_user_context": "declared"
}

Other response markers: _fallback: true and _fallback_for: "<requested slug>" on a fallback serve; _personalization: [{ field, rule_id, label }] on a block where a personalization rule fired; _preview: true on a preview-token serve, where non-published blocks also carry _status. _user_context is verified or declared, and is omitted when neither source supplied audience context. The response sends an ETag and Cache-Control: public, max-age=<space cache_ttl, default 60>, stale-while-revalidate=30 (max-age at most 30 for a fallback serve); a matching If-None-Match gets a 304. When the request carries X-Spoonity-User, the response adds Vary: X-Spoonity-User. A preview serve is Cache-Control: no-store, private with no ETag.

Errors:

Status Code Meaning
401 invalid_preview_token preview_token is malformed, expired, or minted for a different space
404 not_found Unknown vendor/space, or the space failed eligibility with no fallback available
503 service_unavailable Database unreachable and nothing cached for this exact request shape yet (Retry-After: 5)

Remote App Configuration#

Editor entry hidden as of 2026-11-19. The Spaces-page "Remote config" shortcut and the app_config entry in the block palette are hidden in the dashboard and in Prism. The server, GET /api/v1/app-config, block validation, MCP, the AppConfigForm (for existing blocks opened from a space) and the block labels/icons are unchanged. Remote config and switches are managed in Spoonity Flags (Prism -> Flags) and via MCP cms_set_app_config.

A convenience read endpoint for apps that want one small, cacheable document describing runtime config (API host, feature flags, legal/support links, theme, minimum app version) instead of walking the general Content Delivery API for it. Backed by a reserved content space (slug app-config) holding exactly one app_config block — see Content Blocks below for that block type's full field schema and how it's provisioned.

GET /app-config/{vendorSlug}#

Fetch the vendor's published app_config, plus a computed app-update status for the calling app's version. Serves only from a published app-config space with a published app_config block — a draft/half-edited config never reaches a production app, the same rule the content-delivery endpoints enforce.

Auth: None — public.

Path parameters:

Name Type Description
vendorSlug string The vendor's slug.

Query parameters:

Name Type Description
version string The calling app's own version (semver X.Y.Z), compared against app_version.min_version/latest_version to compute update.status. Omitted or unparseable → always "open".

Responses are ETag'd (derived from the config content and its update timestamp) and cacheable — Cache-Control: public, max-age=<space's cache_ttl, default 60>, stale-while-revalidate=30; a matching If-None-Match gets a 304.

Request example:

curl "https://cms.spoonity.com/api/v1/app-config/acme-cafe?version=2.4.0"

Response example:

{
  "config": {
    "api_host": "https://api.acme-cafe.com",
    "feature_flags": { "wallet": true, "egift": true, "ordering": false },
    "app_version": { "min_version": "2.0.0", "latest_version": "2.5.0" }
  },
  "update": {
    "status": "soft",
    "min_version": "2.0.0",
    "latest_version": "2.5.0",
    "update_url": null,
    "message": null
  }
}

update.status is one of open (no update needed, or no version info to compare against), soft (caller is below latest_version but at/above min_version — nag, don't block), or hard (caller is below min_version — block until updated).

Errors:

Status Code Meaning
404 vendor_not_found No vendor with that slug
404 app_config_not_found No published app-config space, or no published app_config block in it, for this vendor

Tracking#

POST /track/{vendorSlug}#

Public, batched endpoint for reporting impressions, clicks and conversions — the counterpart to _tracking.endpoint in every delivery response. Also public and rate-limited at the delivery budget.

Degraded mode on a database outage. This endpoint never fails a client over a database problem. If the database is unreachable — for the whole batch, or partway through it — the events that couldn't be persisted are dropped, not buffered or retried: the response is still 200, with degraded: true and a dropped count added alongside the usual accepted/rejected. A batch that completes normally never carries degraded/dropped at all. Do not retry a degraded batch — the dropped events are gone by design (an in-memory buffer on an autoscaled instance isn't durable enough to be worth the risk of a retry storm against a database that just came back). A cold instance that has never yet reached the database answers every /api/v1/* request, this one included, with a plain 503 (Retry-After: 5) instead — there is nothing to degrade into until the database has been reached at least once.

Auth: None — public.

Path parameters:

Name Type Description
vendorSlug string The vendor's slug.

Request body:

Name Type Required Description
events array (max 50) Yes Array of event objects.
events[].type string Yes impression, click, or conversion. Anything else is rejected.
events[].space_slug string No Resolved to a space id; an unknown slug rejects that event.
events[].block_id integer No
events[].client_id string No An impression with a client_id is deduplicated per (client_id, block_id, UTC day) — a duplicate is counted in rejected, not an error.
events[].platform string No
events[].locale string No
events[].region string No
events[].campaign_id string No Auto-filled from the space's campaign_id when omitted.

Request example:

curl -X POST https://cms.spoonity.com/api/v1/track/acme-cafe \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "type": "impression", "space_slug": "summer-promo", "block_id": 101, "client_id": "device-abc123" },
      { "type": "click", "space_slug": "summer-promo", "block_id": 101, "client_id": "device-abc123" }
    ]
  }'

Response example:

{ "accepted": 2, "rejected": 0 }

Degraded (database unreachable mid-batch):

{ "accepted": 0, "rejected": 0, "dropped": 2, "degraded": true }

Errors:

Status Code Meaning
400 bad_request events missing, empty, not an array, or longer than 50
404 not_found Unknown vendor slug
503 service_unavailable The service has never yet reached the database (Retry-After: 5)

Spaces#

A content space moves through a workflow: draft → review → approved → (scheduled) → published → archived. Only the transition endpoints below (plus an admin-only draft/archived escape hatch on PUT /spaces/{id}) may change status; every transition is activity-logged and fires a webhook. All Spaces and Blocks endpoints require an API key with content:read/content:write scope, or a dashboard JWT session.

GET /spaces#

List content spaces for the vendor.

Auth: content:read scope, or dashboard JWT.

Query parameters:

Name Type Description
platform string Filter by platform (also matches all-platform spaces).
status string Filter by workflow status.
search string Substring match on name or slug.
page integer Default 1.
per_page integer Default 50, max 200.

Request example:

curl "https://cms.spoonity.com/api/v1/spaces?status=published&page=1" \
  -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response example:

{
  "data": [ { "id": 42, "name": "Summer Promo", "slug": "summer-promo", "status": "published", "block_count": 3 } ],
  "total": 1,
  "meta": { "page": 1, "per_page": 50, "total": 1, "total_pages": 1 }
}

Errors:

Status Code Meaning
401 unauthorized Missing/invalid credentials
403 insufficient_scope Key lacks content:read

POST /spaces#

Create a content space. Always created in draft — status in the body is ignored; the publish window (start_at/end_at) is not settable here either.

Auth: content:write scope, or dashboard JWT — any role except viewer (a roleless key is allowed).

Request body:

Name Type Required Description
name string Yes
slug string No Auto-derived from name when omitted.
description string No
platform string No One of all, app, web, mobile_web, desktop_web, watch, tv, car. Default all.
category, campaign_id string, nullable No
tags string[] No
priority integer No Default 0.
region, city, country, daypart string No country defaults CA.
store_ids string[] No
active_hours { start, end } No
active_days string[] (sun..sat) No
audience { loyalty_tier?: string[], segments?: string[] } No
min_visits, max_visits integer No
default_locale string No Default en-CA. Not validated; use one of en-CA, fr-CA, en-US, es-US, fr-FR, pt-BR, the locales Translations supports.
fallback_space_id integer, nullable No Must reference an existing space of the same vendor.

Request example:

curl -X POST https://cms.spoonity.com/api/v1/spaces \
  -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Fall Promo", "platform": "app", "category": "promotion" }'

Response example (201):

{ "id": 55, "vendor_id": 7, "name": "Fall Promo", "slug": "fall-promo", "status": "draft", "platform": "app", "sort_order": 3 }

Errors:

Status Code Meaning
400 bad_request name missing, unknown platform, or invalid fallback_space_id
403 forbidden Caller is a viewer
409 conflict A space with that slug already exists for this vendor

POST /spaces/{id}/clone#

Server-side, all-or-nothing copy of a space (spoonity-cms #37). The copy is a draft with the source's settings and targeting (description, platform, category, campaign, tags, priority, region, city, country, store ids, daypart, active hours/days, audience, visit bounds, default locale), and every block is copied as a draft, in the same order, with all content columns. It is placed at the end of the vendor's space order. Translations, personalization rules and experiments are not copied. If any step fails the partial copy is deleted, so a caller never sees half a space.

Auth: content:write scope, or dashboard JWT — any role except viewer.

Path parameters:

Name Type Description
id integer Source space id.

Request body (the body itself is optional):

Name Type Required Description
name string No Default "<source name> (copy)".
slug string No Default "<source slug>-copy-<base36 timestamp>".

Request example:

curl -X POST https://cms.spoonity.com/api/v1/spaces/42/clone \
  -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Summer Promo (Copy)", "slug": "summer-promo-2" }'

Response example (201): the new space row plus blocks_copied. Logs a duplicated activity entry and fires space.created for the copy.

{ "id": 56, "vendor_id": 7, "name": "Summer Promo (Copy)", "slug": "summer-promo-2", "status": "draft", "platform": "app", "blocks_copied": 3 }

Errors:

Status Code Meaning
403 forbidden Caller is a viewer
404 not_found No such space for this vendor
409 conflict A space with that slug already exists (message: A space with slug "<slug>" already exists.)
500 clone_failed Failed to clone the space; nothing was created — the partial copy was rolled back

GET /spaces/{id}#

Get a single space with its blocks.

Auth: content:read scope, or dashboard JWT.

Path parameters:

Name Type Description
id integer Space id.

Request example:

curl https://cms.spoonity.com/api/v1/spaces/42 \
  -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response example:

{ "id": 42, "name": "Summer Promo", "slug": "summer-promo", "status": "published", "blocks": [ { "id": 101, "block_type": "hero_banner", "title": "Cold Brew Season" } ] }

Errors:

Status Code Meaning
404 not_found No such space for this vendor

PUT /spaces/{id}#

Update a space's content, scheduling and targeting fields. status is not freely writable: it may only be changed to draft or archived (every other value, including workflow states, is a 400 directing you to the workflow endpoint that owns the transition and its side effects), and only by an admin. Omitting status, or resending the current value, is always a plain content edit open to any non-viewer.

Auth: content:write scope, or dashboard JWT — non-viewer for a plain edit; admin required only when status is being changed to draft/archived.

Path parameters:

Name Type Description
id integer Space id.

Request body: same fields as POST /spaces (all optional — only supplied fields are updated), plus status (draft/archived only, as a change), start_at/end_at (ISO 8601 in).

Request example:

curl -X PUT https://cms.spoonity.com/api/v1/spaces/42 \
  -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "priority": 20, "region": "QC" }'

Response example:

{ "id": 42, "name": "Summer Promo", "slug": "summer-promo", "status": "published", "priority": 20, "region": "QC" }

Errors:

Status Code Meaning
400 bad_request Unknown platform, invalid fallback_space_id, or a status value the workflow reserves (echoes current_status/requested_status)
403 forbidden Caller is a viewer, or a non-admin tried to change status
404 not_found No such space for this vendor

DELETE /spaces/{id}#

Delete a space and all of its blocks.

Auth: content:write scope, or dashboard JWT — admin role required.

Path parameters:

Name Type Description
id integer Space id.

Request example:

curl -X DELETE https://cms.spoonity.com/api/v1/spaces/42 \
  -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response example:

{ "success": true, "message": "Space deleted" }

Errors:

Status Code Meaning
403 forbidden Caller is not an admin
404 not_found No such space for this vendor

POST /spaces/{id}/submit#

draft → review. Stamps submitted_by/submitted_at.

Auth: content:write scope, or dashboard JWT — admin or editor (viewers rejected).

Path parameters: id (integer, space id).

Request example:

curl -X POST https://cms.spoonity.com/api/v1/spaces/42/submit \
  -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response example:

{ "id": 42, "status": "review", "submitted_by": "editor@acme-cafe.com", "message": "Space submitted for review" }

Errors:

Status Code Meaning
403 forbidden Caller is a viewer or has no role
404 not_found No such space for this vendor
409 invalid_transition Space is not currently draft

POST /spaces/{id}/approve#

review → approved. Stamps approved_by/approved_at, clears rejection_reason.

Auth: content:write scope, or dashboard JWT — admin.

Path parameters: id (integer, space id).

Request example:

curl -X POST https://cms.spoonity.com/api/v1/spaces/42/approve \
  -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response example:

{ "id": 42, "status": "approved", "approved_by": "admin@acme-cafe.com", "message": "Space approved" }

Errors:

Status Code Meaning
403 forbidden Caller is not an admin
404 not_found No such space for this vendor
409 invalid_transition Space is not currently review

POST /spaces/{id}/reject#

review → draft. Stores an optional reason.

Auth: content:write scope, or dashboard JWT — admin.

Path parameters: id (integer, space id).

Request body:

Name Type Required Description
reason string, nullable No Blank/omitted stores null.

Request example:

curl -X POST https://cms.spoonity.com/api/v1/spaces/42/reject \
  -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Needs French translation before review" }'

Response example:

{ "id": 42, "status": "draft", "rejection_reason": "Needs French translation before review", "message": "Space rejected — returned to draft" }

Errors:

Status Code Meaning
403 forbidden Caller is not an admin
404 not_found No such space for this vendor
409 invalid_transition Space is not currently review

POST /spaces/{id}/schedule#

approved → scheduled. The background scheduler publishes the space once start_at passes.

Auth: content:write scope, or dashboard JWT — admin.

Path parameters: id (integer, space id).

Request body:

Name Type Required Description
start_at string (ISO 8601) No* *Required unless already set on the space. Past dates allowed.
end_at string (ISO 8601), nullable No

Request example:

curl -X POST https://cms.spoonity.com/api/v1/spaces/42/schedule \
  -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "start_at": "2026-09-01T08:00:00.000Z" }'

Response example:

{ "id": 42, "status": "scheduled", "start_at": "2026-09-01 08:00:00", "message": "Space scheduled to publish at 2026-09-01 08:00:00" }

Errors:

Status Code Meaning
400 bad_request Malformed start_at/end_at, or no start_at set anywhere
403 forbidden Caller is not an admin
404 not_found No such space for this vendor
409 invalid_transition Space is not currently approved

POST /spaces/{id}/publish#

Publish a space. Legal from approved or scheduled (or any status with force: true, logged as forced). Snapshots current blocks as a new version, promotes draft blocks, enriches image variants, and — when settings.auto_shorten_cta is true — rewrites CTA URLs to short links.

Auth: content:write scope, or dashboard JWT — admin.

Path parameters: id (integer, space id).

Request body:

Name Type Required Description
force boolean No Default false. Publishes from any status, bypassing the approved/scheduled requirement.

Request example:

curl -X POST https://cms.spoonity.com/api/v1/spaces/42/publish \
  -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response example:

{ "id": 42, "status": "published", "published_at": "2026-08-31 12:00:00", "version": 4, "message": "Space published (v4)" }

Errors:

Status Code Meaning
403 forbidden Caller is not an admin
404 not_found No such space for this vendor
409 invalid_transition Space is not approved/scheduled and force was not set

POST /spaces/{id}/unpublish#

Revert a space to draft from any status — the sanctioned published → draft path.

Auth: content:write scope, or dashboard JWT — admin.

Path parameters: id (integer, space id).

Request example:

curl -X POST https://cms.spoonity.com/api/v1/spaces/42/unpublish \
  -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response example:

{ "id": 42, "status": "draft", "message": "Space reverted to draft" }

Errors:

Status Code Meaning
403 forbidden Caller is not an admin
404 not_found No such space for this vendor

POST /spaces/{id}/preview-token#

Mint a 30-minute JWT that serves this space through the real delivery pipeline regardless of workflow status, with draft blocks included. Append it to the delivery URL as ?preview_token=….

Auth: content:write scope, or dashboard JWT — admin or editor (viewers cannot mint tokens).

Path parameters: id (integer, space id).

Request example:

curl -X POST https://cms.spoonity.com/api/v1/spaces/42/preview-token \
  -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response example:

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "expires_at": "2026-08-31T12:30:00.000Z",
  "preview_url": "https://cms.spoonity.com/api/v1/content/acme-cafe/summer-promo?preview_token=eyJhbGciOiJIUzI1NiJ9..."
}

Errors:

Status Code Meaning
403 forbidden Caller is a viewer or has no role
404 not_found No such space (or vendor)

GET /spaces/{id}/versions#

List a space's publish-version history (newest first). Each row carries block_count derived from the snapshot; the snapshot itself is not returned.

Auth: content:read scope, or dashboard JWT.

Path parameters: id (integer, space id).

Request example:

curl https://cms.spoonity.com/api/v1/spaces/42/versions \
  -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response example:

{ "data": [ { "id": 9, "space_id": 42, "version_number": 4, "message": "Version 4", "published_by": "admin@acme-cafe.com", "created_at": "2026-08-31 12:00:00", "block_count": 3 } ] }

Errors: none beyond auth — an unknown space id returns an empty list, not a 404.

POST /spaces/{id}/versions/{versionId}/restore#

Restore a space's blocks from a version's snapshot in place (spoonity-cms #37; it used to delete and re-insert everything). Blocks that still exist keep their ids, so their translations, personalization rules and experiment links survive, and they keep their current status, so a published space keeps delivering while the content is swapped. Blocks that were removed since the snapshot are re-created (new ids; published if the space is published, otherwise drafts). Blocks added after the snapshot are deleted. Every content column is written back (block_type, title, subtitle, body, image_url, background_url, video_url, poster_url, cta_text, cta_url, cta_deeplink, cta_link_id, config, platform, tags, menu_item_id, region, store_ids, audience) and sort_order follows snapshot order. Both snapshot shapes (a bare block array and { blocks }) are accepted. The space's own status is untouched and no webhook fires.

Auth: content:write scope, or dashboard JWT — admin.

Path parameters:

Name Type Description
id integer Space id.
versionId integer Version id.

Request example:

curl -X POST https://cms.spoonity.com/api/v1/spaces/42/versions/9/restore \
  -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response example:

{ "success": true, "message": "Restored to version 4", "blocks_restored": 3 }

Errors:

Status Code Meaning
403 forbidden Caller is not an admin
404 not_found No such version for this space

Content Blocks#

Blocks are the individual content units inside a space (hero_banner, promo_card, featured_items, announcement, custom_json, text_block, image_gallery, video, faq, onboarding_slide, carousel, app_icon, points_program, egift_artwork, app_config). faq, carousel, onboarding_slide, app_icon, points_program, egift_artwork and app_config have a validated config shape; other types accept opaque JSON.

points_program and egift_artwork config#

Both types carry config.items[], like faq/carousel above them.

app_config — remote app configuration#

At most one app_config block per space (a second POST to the same space is a 409). Every top-level section is optional — draft incrementally and only the sections you send are validated:

Field Type Notes
api_host string Must be an https:// URL.
locales.default string
locales.supported string[]
feature_flags.{wallet,egift,ordering,credit,journey,scan,messages,stores,home_barcode,wallet_pass,meta_events,geo_promotions,auth_engine,qa_feedback,transaction_rating} boolean Unknown keys under feature_flags are rejected. qa_feedback enables the in-app QA feedback control (spoonity-cms #35).
qa_feedback.testers string[] At most 200 entries, each at most 254 characters: a full email (name@example.com) or a whole-domain entry (@example.com). Trimmed, lowercased and de-duplicated (first occurrence wins) on save. An invalid entry is a 400 bad_request naming its index.
flags.{clientKey,baseUrl,enabled} object How native apps get their Spoonity Flags client key remotely (#33). clientKey must be a client key (sdk_c_ + 26 base32 chars) — a server key (sdk_s_…) is rejected by name because the public endpoint serves this section; baseUrl must be https://; enabled: true requires a clientKey; unknown fields are rejected.
legal.{terms_url,privacy_url,faq_url} string (URL) http(s).
support.{email,phone,whatsapp} string Plain contact strings, not URLs — never Links-enforced.
support.url string Must be https://. Links-eligible at warn only, regardless of CMS_LINKS_MODE — see below.
social.website string (URL) Links-eligible at warn only.
social.{instagram,facebook,tiktok,x} string Handles, not URLs — never Links-enforced.
store_order.url_template string Excluded from Links enforcement outright — it carries placeholders (e.g. {store_id}), not a literal navigable URL.
store_order.mode string One of pickup, delivery, both.
store_order.doxi_handoff boolean
loyalty.primary_currency_id number
loyalty.display_divisor number Must be positive.
loyalty.display_currency string
loyalty.progress_currencies[] array of { currency_id, label, target } All three fields required per entry.
theme.colors.{primary,secondary,background,text,accent} string #RRGGBB hex.
theme.fonts.{heading,body} string
app_version.min_version, app_version.latest_version string Semver X.Y.Z (optional -prerelease suffix).
app_version.status string One of open, soft, hard — informational; GET /app-config/{vendorSlug} computes its own update.status from min_version/latest_version against the caller's version rather than trusting this field.
app_version.update_url.{android,ios} string (URL) Excluded from Links enforcement outright — must point at the OS app store, not a short link.
app_version.message.{en,es} string

legal.terms_url/legal.privacy_url/legal.faq_url, social.website, and support.url are the only app_config fields Spoonity Links enforcement touches, and only ever at warn semantics — a raw external URL there adds a link_warnings entry, but an app_config save never hard-fails (require mode) or gets silently rewritten (auto mode) over these fields, regardless of the vendor's CMS_LINKS_MODE. api_host, store_order.url_template, and app_version.update_url are excluded from Links enforcement entirely — see Spoonity Links enforcement.

feature_flags.*, store_order.doxi_handoff and qa_feedback.testers are now legacy bootstrap/fallback values: their source of truth is Spoonity Flags, where the flag key is the same field name. The CMS keeps validating and serving them so apps can seed the Flags SDK and fall back when a brand has no active Flags block. GET /app-config/{vendorSlug} serves flags normalized to exactly { clientKey, baseUrl, enabled } (enabled is false unless a valid client key is present).

POST /vendors/{vendorSlug}/app-config#

Create-or-update the vendor's one reserved app_config space+block in a single call — the operator/automation "just set it" path, not the editorial draft→review→approve workflow. Idempotent: finds or creates the app-config space (platform app) and its one app_config block, merges the request body into the stored config at top-level-section granularity (each top-level key present in the body replaces that whole section; omitted keys keep their previous value), validates the merged result against the schema above, and immediately publishes both the block and the space.

Auth: content:write scope, or dashboard JWT — non-viewer. vendorSlug must match the authenticated vendor (a mismatch is a 403, not a 404 — this is a service/admin-only path, not a lookup).

Path parameters:

Name Type Description
vendorSlug string Must match the authenticated vendor.

Request body: any subset of the app_config fields documented above, at top-level-section granularity.

Request example:

curl -X POST https://cms.spoonity.com/api/v1/vendors/acme-cafe/app-config \
  -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "feature_flags": { "wallet": true, "egift": true }, "app_version": { "min_version": "2.0.0" } }'

Response example:

{
  "space": { "id": 60, "slug": "app-config", "status": "published" },
  "block": { "id": 210, "block_type": "app_config", "status": "published", "config": { "feature_flags": { "wallet": true, "egift": true }, "app_version": { "min_version": "2.0.0" } } }
}

Errors:

Status Code Meaning
400 bad_request Merged config fails schema validation (see the field table above)
403 forbidden Caller is a viewer, or vendorSlug doesn't match the authenticated vendor

Every navigation-URL field on a block create/update — block-level cta_url/cta_deeplink, plus the item-level cta_url/cta_deeplink on carousel items and deeplink on points_program items — is checked against CMS_LINKS_MODE (env var; one of require, auto, warn; default auto) whenever it carries a raw http(s):// value that isn't already a Spoonity Link: a URL on the default short domain (links.spoonity.com), or under the vendor's own Links base (its x.spnty.co/<vendor slug> path on the shared host, or its verified custom domain). In warn mode only the default short domain is recognised, so a shared-host or custom-domain URL still gets a warning there. An app-scheme deep link (anything that doesn't parse as an http(s) URL, e.g. myapp://) is always left untouched, in every mode. auto is the code default; cms.spoonity.com currently runs with warn.

app_config blocks are the one exception: their eligible fields (legal.terms_url/legal.privacy_url/legal.faq_url, social.website, support.url) are always evaluated at warn semantics regardless of the configured mode — see the app_config section above. app_config.api_host, store_order.url_template, and app_version.update_url are excluded from enforcement outright.

POST /spaces/{spaceId}/blocks#

Add a block to a space, created as draft.

Auth: content:write scope, or dashboard JWT — non-viewer.

Path parameters: spaceId (integer).

Request body:

Name Type Required Description
block_type string Yes One of the 15 types above.
title, subtitle, body string No
image_url, background_url, video_url, poster_url string No
cta_text, cta_url, cta_deeplink string No Subject to Spoonity Links enforcement.
config object No Validated for faq/carousel/onboarding_slide/app_icon/points_program/egift_artwork/app_config; empty/absent always allowed.
platform string No Overrides the space's platform for this block; null inherits.
tags string[] No
menu_item_id, region string, nullable No
store_ids string[], nullable No
audience object, nullable No

Request example:

curl -X POST https://cms.spoonity.com/api/v1/spaces/42/blocks \
  -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "block_type": "hero_banner", "title": "Cold Brew Season", "cta_text": "Order now", "cta_url": "https://acme-cafe.com/menu" }'

Response example:

{ "id": 101, "space_id": 42, "block_type": "hero_banner", "title": "Cold Brew Season", "status": "draft", "sort_order": 0 }

A response carries a top-level link_warnings array (see above) only in warn mode, and only when at least one in-scope field held a raw URL.

Errors:

Status Code Meaning
400 bad_request Unknown block_type/platform, or config fails type-specific validation
403 forbidden Caller is a viewer
404 not_found No such space for this vendor
409 conflict block_type is app_config and the space already has one
422 link_required (require mode) An in-scope field holds a raw URL
422 link_creation_failed (auto mode) Minting a short link for an in-scope field failed

PUT /blocks/{id}#

Update a block. Any subset of fields.

Auth: content:write scope, or dashboard JWT — non-viewer.

Path parameters: id (integer, block id).

Request body: same fields as create, plus status (draft/published — block-level visibility within its space; freely editor-settable, no workflow bypass since delivery only ever serves blocks of a space that is itself published) and sort_order.

Request example:

curl -X PUT https://cms.spoonity.com/api/v1/blocks/101 \
  -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Cold Brew Season — Extended" }'

Response example:

{ "id": 101, "space_id": 42, "title": "Cold Brew Season — Extended", "status": "draft" }

Errors:

Status Code Meaning
400 bad_request Unknown platform, or config fails validation
403 forbidden Caller is a viewer
404 not_found No such block for this vendor
422 link_required (require mode) An in-scope field holds a raw URL
422 link_creation_failed (auto mode) Minting a short link for an in-scope field failed

DELETE /blocks/{id}#

Permanently delete a content block.

Auth: content:write scope, or dashboard JWT — admin.

Path parameters: id (integer, block id).

Request example:

curl -X DELETE https://cms.spoonity.com/api/v1/blocks/101 \
  -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response example:

{ "success": true, "message": "Block deleted" }

Errors:

Status Code Meaning
403 forbidden Caller is not an admin
404 not_found No such block for this vendor

POST /blocks/{id}/duplicate#

Clone a block into the same space as a new draft, titled " (copy)" and appended at the end of the sort order. Only the content, CTA, <code>config</code> and <code>platform</code> fields are copied: <code>tags</code>, <code>menu_item_id</code>, <code>region</code>, <code>store_ids</code> and <code>audience</code> are not. Returns <code>201</code>. No webhook fires.</p> <p><strong>Auth:</strong> <code>content:write</code> scope, or dashboard JWT — non-viewer.</p> <p><strong>Path parameters:</strong> <code>id</code> (integer, block id).</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/blocks/101/duplicate \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "id": 102, "space_id": 42, "title": "Cold Brew Season (copy)", "status": "draft" }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>403</td> <td>forbidden</td> <td>Caller is a viewer</td> </tr> <tr> <td>404</td> <td>not_found</td> <td>No such block for this vendor</td> </tr> </tbody></table> </div><h3 id="post-blocksidshorten-cta">POST /blocks/{id}/shorten-cta<a class="anchor" href="#post-blocksidshorten-cta" aria-label="Permalink">#</a></h3> <p>Replace the block's <code>cta_url</code> with a tracked <a href="https://links.spoonity.com" target="_blank" rel="noopener noreferrer">Spoonity Links</a> short link, preserving the original in <code>config.cta_url_original</code> (never clobbered on re-shorten). The same rewrite happens automatically at publish time when <code>settings.auto_shorten_cta</code> is <code>true</code>.</p> <p><strong>Auth:</strong> <code>content:write</code> scope, or dashboard JWT — <strong>admin or editor</strong>.</p> <p><strong>Path parameters:</strong> <code>id</code> (integer, block id).</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/blocks/101/shorten-cta \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "id": 101, "cta_url": "https://links.spoonity.com/x7Qp9", "short_url": "https://links.spoonity.com/x7Qp9", "code": "x7Qp9" }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>bad_request</td> <td>The block has no <code>cta_url</code> to shorten</td> </tr> <tr> <td>403</td> <td>forbidden</td> <td>Caller is a viewer or has no role</td> </tr> <tr> <td>404</td> <td>not_found</td> <td>No such block for this vendor</td> </tr> <tr> <td>502</td> <td>links_error</td> <td>The Links service did not return a short link</td> </tr> <tr> <td>503</td> <td>links_not_configured</td> <td>Not running on GCP and <code>LINKS_API_KEY</code> is unset</td> </tr> </tbody></table> </div><h3 id="post-blocksidshorten-field">POST /blocks/{id}/shorten-field<a class="anchor" href="#post-blocksidshorten-field" aria-label="Permalink">#</a></h3> <p>Generalized version of <code>shorten-cta</code> above: replaces <strong>any</strong> in-scope navigation-URL field — block- level <code>cta_url</code>/<code>cta_deeplink</code>, or an item-level field inside <code>config.items[]</code> (<code>cta_url</code>/ <code>cta_deeplink</code> on a <code>carousel</code> item, <code>deeplink</code> on a <code>points_program</code> item) — with a tracked <code>links.spoonity.com</code> short link. The original value is preserved the first time a field is shortened (<code>config.cta_url_original</code> for block-level <code>cta_url</code>, <code><field>_original</code> on the item otherwise) and never clobbered on re-shorten.</p> <p><strong>Auth:</strong> <code>content:write</code> scope, or dashboard JWT — <strong>admin or editor</strong>.</p> <p><strong>Path parameters:</strong> <code>id</code> (integer, block id).</p> <p><strong>Request body:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>field</code></td> <td>string</td> <td>Yes</td> <td>The field name to shorten.</td> </tr> <tr> <td><code>item_id</code></td> <td>string</td> <td>Only for an item-level field</td> <td>The item's stable <code>id</code> within <code>config.items[]</code>. A field name valid at both block and item scope (e.g. <code>cta_url</code>) is disambiguated by whether <code>item_id</code> is present.</td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/blocks/101/shorten-field \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "field": "deeplink", "item_id": "abc123def0" }'</code></pre> <p><strong>Response example (item-level):</strong></p> <pre><code class="language-json">{ "id": 101, "short_url": "https://links.spoonity.com/aZ3kq", "code": "aZ3kq", "link_id": 77, "item_id": "abc123def0" }</code></pre> <p>A block-level shorten instead returns the full updated block plus <code>short_url</code>/<code>code</code>/<code>link_id</code>, the same shape as <code>shorten-cta</code>.</p> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>bad_request</td> <td><code>field</code> is not a valid field for this block type at the given scope; <code>item_id</code> is required for an item-level field and was omitted; or the field is already empty</td> </tr> <tr> <td>404</td> <td>not_found</td> <td>No such block for this vendor, or (item-level) no item with that <code>item_id</code></td> </tr> <tr> <td>502</td> <td>links_error</td> <td>The Links service did not return a short link</td> </tr> <tr> <td>503</td> <td>links_not_configured</td> <td>Not running on GCP and <code>LINKS_API_KEY</code> is unset</td> </tr> </tbody></table> </div><h3 id="get-linkssearch">GET /links/search<a class="anchor" href="#get-linkssearch" aria-label="Permalink">#</a></h3> <p>Proxy to the Links API's own link search, so an editor can pick an existing Spoonity Link instead of always minting a new one. Never a hard error — an unavailable Links integration or a failed search call returns an empty list rather than a 5xx (this is a UX affordance, not load-bearing data).</p> <p><strong>Auth:</strong> Any valid API key or dashboard JWT — <strong>not scope-gated</strong>.</p> <p><strong>Query parameters:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>q</code></td> <td>string</td> <td>Search text.</td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl "https://cms.spoonity.com/api/v1/links/search?q=summer" \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "links": [ { "id": 88, "short_url": "https://links.spoonity.com/x7Qp9", "code": "x7Qp9", "destination_url": "https://acme-cafe.com/menu", "title": "Summer Promo" } ] }</code></pre> <p><strong>Errors:</strong> none — an unavailable Links integration or a failed search resolves to <code>{ "links": [] }</code>.</p> <h3 id="get-vendorlinks-domain">GET /vendor/links-domain<a class="anchor" href="#get-vendorlinks-domain" aria-label="Permalink">#</a></h3> <p>The domain(s) a URL must be on to count as "already a tracked Spoonity Link" for this vendor: the default short domain, plus whatever Links domain the vendor is enrolled on. <code>mode</code> is the vendor's Links <strong>domain</strong> mode (<code>shared</code>, <code>custom</code> or <code>none</code>), not <code>CMS_LINKS_MODE</code>. <code>short_link_base</code> is the base editors should build and recognise the vendor's links against: <code>x.spnty.co/<vendor slug></code> for a shared-host vendor, the custom domain for a custom-domain vendor, and the default short domain otherwise. <code>custom_domain</code> is set only when <code>mode</code> is <code>custom</code>. The Links lookup is cached for 5 minutes and falls back to <code>mode: "none"</code> when Links is unreachable.</p> <p><strong>Auth:</strong> Any valid API key or dashboard JWT — <strong>not scope-gated</strong>.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/vendor/links-domain \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "short_domain": "links.spoonity.com", "custom_domain": null, "mode": "shared", "short_link_base": "x.spnty.co/acme-cafe" }</code></pre> <p><strong>Errors:</strong> none beyond auth.</p> <h3 id="put-spacesspaceidreorder">PUT /spaces/{spaceId}/reorder<a class="anchor" href="#put-spacesspaceidreorder" aria-label="Permalink">#</a></h3> <p>Rewrite every listed block's <code>sort_order</code> to its index in <code>block_ids</code>.</p> <p><strong>Auth:</strong> <code>content:write</code> scope, or dashboard JWT — non-viewer.</p> <p><strong>Path parameters:</strong> <code>spaceId</code> (integer).</p> <p><strong>Request body:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>block_ids</code></td> <td>integer[]</td> <td>Yes</td> <td>Block ids in their new display order.</td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X PUT https://cms.spoonity.com/api/v1/spaces/42/reorder \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "block_ids": [102, 101] }'</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "success": true, "blocks": [ { "id": 102, "sort_order": 0 }, { "id": 101, "sort_order": 1 } ] }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>bad_request</td> <td><code>block_ids</code> missing or not an array</td> </tr> <tr> <td>403</td> <td>forbidden</td> <td>Caller is a viewer</td> </tr> <tr> <td>404</td> <td>not_found</td> <td>No such space for this vendor</td> </tr> </tbody></table> </div><hr> <h2 id="media">Media<a class="anchor" href="#media" aria-label="Permalink">#</a></h2> <p>Uploaded raster images (JPEG/PNG/WebP) are optimized server-side: the stored original is re-encoded, EXIF-stripped and capped at 2560px (<code>original_url</code>), a size-budgeted WebP primary becomes <code>url</code>, and responsive WebP <code>variants</code> (<code>thumb</code>/<code>md</code>/<code>lg</code>) are generated. GIF/SVG/video/PDF pass through untouched. <strong>Wallet-pass integrations must reference <code>original_url</code></strong> (format- preserved PNG/JPEG), never the WebP <code>url</code>. In production, newly stored assets are served from <code>https://media.spoonity.com/<filename></code> (<code>MEDIA_CDN_BASE_URL</code>); older rows keep the URL recorded at upload time.</p> <h3 id="get-media">GET /media<a class="anchor" href="#get-media" aria-label="Permalink">#</a></h3> <p>List media assets.</p> <p><strong>Auth:</strong> <code>media:read</code> scope, or dashboard JWT.</p> <p><strong>Query parameters:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>page</code></td> <td>integer</td> <td>Default <code>1</code>.</td> </tr> <tr> <td><code>limit</code></td> <td>integer</td> <td>Default <code>50</code>, max <code>100</code>.</td> </tr> <tr> <td><code>folder</code></td> <td>string</td> <td>Use <code>__unfiled__</code> for assets with no folder.</td> </tr> <tr> <td><code>tag</code></td> <td>string</td> <td>Single tag filter.</td> </tr> <tr> <td><code>q</code></td> <td>string</td> <td>Substring match on <code>original_name</code>/<code>alt_text</code>.</td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl "https://cms.spoonity.com/api/v1/media?folder=hero-images" \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": [ { "id": 9, "filename": "abc123.jpg", "url": "https://media.spoonity.com/abc123_opt.webp", "original_url": "https://media.spoonity.com/abc123.jpg", "width": 1920, "height": 1080, "variants": { "thumb": { "url": "...", "width": 200, "height": 113 } }, "tags": [], "protected": false, "deleted_at": null } ], "pagination": { "page": 1, "limit": 50, "total": 1, "total_pages": 1 } }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>403</td> <td>insufficient_scope</td> <td>Key lacks <code>media:read</code></td> </tr> </tbody></table> </div><h3 id="get-mediafolders">GET /media/folders<a class="anchor" href="#get-mediafolders" aria-label="Permalink">#</a></h3> <p>Distinct folders with asset counts, for the media library sidebar.</p> <p><strong>Auth:</strong> <code>media:read</code> scope, or dashboard JWT.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/media/folders \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": [ { "folder": "hero-images", "count": 4 } ], "total": 10, "unfiled": 6 }</code></pre> <p><strong>Errors:</strong> none beyond auth.</p> <h3 id="post-media">POST /media<a class="anchor" href="#post-media" aria-label="Permalink">#</a></h3> <p>Upload a media file. Allowed types: <code>jpg, jpeg, png, gif, webp, svg, mp4, webm, pdf</code>; default max size 10 MB (<code>UPLOAD_MAX_SIZE_MB</code>). <code>multipart/form-data</code>. When the client reports a generic <code>application/octet-stream</code> (or no) content type, the type is taken from the file extension, so WebP, mp4 and webm uploads from curl are still optimised and served with the right <code>Content-Type</code>.</p> <p><strong>Auth:</strong> <code>media:write</code> scope, or dashboard JWT. No role restriction — any authenticated role (including <code>viewer</code>) may upload.</p> <p><strong>Request body (multipart/form-data):</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>file</code></td> <td>binary</td> <td>Yes</td> <td></td> </tr> <tr> <td><code>alt_text</code></td> <td>string</td> <td>No</td> <td></td> </tr> <tr> <td><code>folder</code></td> <td>string</td> <td>No</td> <td></td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/media \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -F "file=@hero.jpg" \ -F "folder=hero-images"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "id": 9, "filename": "abc123.jpg", "url": "https://media.spoonity.com/abc123_opt.webp", "original_url": "https://media.spoonity.com/abc123.jpg", "width": 1920, "height": 1080, "folder": "hero-images" }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>bad_request</td> <td>No <code>file</code> part in the upload</td> </tr> <tr> <td>413</td> <td>file_too_large</td> <td>File over the size limit; <code>message</code>: <code>File is too large. The maximum upload size is <n> MB.</code> (spoonity-cms #37; was a <code>500</code>)</td> </tr> <tr> <td>415</td> <td>unsupported_file_type</td> <td>Extension not in <code>jpg, jpeg, png, gif, webp, svg, mp4, webm, pdf</code>; <code>message</code> lists the accepted types (was a <code>500</code>)</td> </tr> <tr> <td>400</td> <td>bad_request</td> <td>Any other malformed multipart upload (<code>message</code>: <code>Invalid upload: ...</code>)</td> </tr> <tr> <td>500</td> <td>upload_failed</td> <td>Storage write or processing failed</td> </tr> </tbody></table> </div><h3 id="post-mediareprocess-all">POST /media/reprocess-all<a class="anchor" href="#post-mediareprocess-all" aria-label="Permalink">#</a></h3> <p>Re-run the optimization pipeline for every raster asset of the vendor with current settings. Non-raster assets are skipped; unreadable/undecodable ones count as failed.</p> <p><strong>Auth:</strong> <code>media:write</code> scope, or dashboard JWT — <strong>admin</strong>.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/media/reprocess-all \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "processed": 8, "skipped": 2, "failed": 0, "bytes_saved": 412300 }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>403</td> <td>forbidden</td> <td>Caller is not an admin</td> </tr> </tbody></table> </div><h3 id="post-mediaidreprocess">POST /media/{id}/reprocess<a class="anchor" href="#post-mediaidreprocess" aria-label="Permalink">#</a></h3> <p>Re-run optimization for one asset.</p> <p><strong>Auth:</strong> <code>media:write</code> scope, or dashboard JWT — <strong>admin or editor</strong>.</p> <p><strong>Path parameters:</strong> <code>id</code> (integer, asset id).</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/media/9/reprocess \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "asset": { "id": 9, "url": "https://media.spoonity.com/abc123_opt.webp" }, "bytes_saved": 51200 }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>not_optimizable</td> <td>Not a still raster image</td> </tr> <tr> <td>403</td> <td>forbidden</td> <td>Caller is a viewer or has no role</td> </tr> <tr> <td>404</td> <td>not_found</td> <td>No such asset for this vendor</td> </tr> <tr> <td>422</td> <td>reprocess_failed</td> <td>Stored original could not be read or decoded</td> </tr> </tbody></table> </div><h3 id="patch-mediaid">PATCH /media/{id}<a class="anchor" href="#patch-mediaid" aria-label="Permalink">#</a></h3> <p>Update <code>alt_text</code>, <code>folder</code> and/or <code>tags</code>.</p> <p><strong>Auth:</strong> <code>media:write</code> scope, or dashboard JWT — <strong>admin or editor</strong>; changing <code>protected</code> additionally requires <strong>admin</strong> even if other fields in the same body would be allowed for an editor.</p> <p><strong>Path parameters:</strong> <code>id</code> (integer, asset id).</p> <p><strong>Request body:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>alt_text</code></td> <td>string, nullable</td> <td>No</td> <td></td> </tr> <tr> <td><code>folder</code></td> <td>string, nullable</td> <td>No</td> <td></td> </tr> <tr> <td><code>tags</code></td> <td>string[], nullable</td> <td>No</td> <td><code>[]</code>/<code>null</code> clears all tags.</td> </tr> <tr> <td><code>protected</code></td> <td>boolean</td> <td>No</td> <td>Admin-only. Blocks a <code>?hard=true</code> delete while <code>true</code>.</td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X PATCH https://cms.spoonity.com/api/v1/media/9 \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "alt_text": "Iced coffee with cream", "tags": ["hero", "summer"] }'</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "id": 9, "alt_text": "Iced coffee with cream", "tags": ["hero", "summer"], "protected": false }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>bad_request</td> <td>No updatable field supplied, or a malformed value</td> </tr> <tr> <td>403</td> <td>forbidden</td> <td>Caller is a viewer/roleless, or an editor attempted to set <code>protected</code></td> </tr> <tr> <td>404</td> <td>not_found</td> <td>No such asset for this vendor</td> </tr> </tbody></table> </div><h3 id="delete-mediaid">DELETE /media/{id}<a class="anchor" href="#delete-mediaid" aria-label="Permalink">#</a></h3> <p>Default is a <strong>soft delete</strong> (<code>deleted_at</code> stamped, hidden from listings, file keeps serving so existing references never 404). <code>?hard=true</code> permanently destroys the file, its variants, and the row; refused while <code>protected</code>.</p> <p><strong>Auth:</strong> <code>media:write</code> scope, or dashboard JWT — <strong>admin</strong>.</p> <p><strong>Path parameters:</strong> <code>id</code> (integer, asset id).</p> <p><strong>Query parameters:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>hard</code></td> <td>boolean</td> <td>Default <code>false</code>.</td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X DELETE "https://cms.spoonity.com/api/v1/media/9?hard=false" \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "success": true, "message": "Asset removed from library. Its file stays online so existing references (wallet passes, published content) keep working; use ?hard=true to permanently destroy it.", "soft": true }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>403</td> <td>forbidden</td> <td>Caller is not an admin</td> </tr> <tr> <td>404</td> <td>not_found</td> <td>No such asset for this vendor</td> </tr> <tr> <td>409</td> <td>protected</td> <td><code>?hard=true</code> requested but the asset is marked <code>protected</code></td> </tr> </tbody></table> </div><hr> <h2 id="personalization">Personalization<a class="anchor" href="#personalization" aria-label="Permalink">#</a></h2> <p>Block-level rules that override a field at delivery time based on request context (e.g. "if <code>loyalty_tier=gold</code>, override <code>image_url</code>"). Higher-<code>priority</code> rules win per field. <strong>These write routes carry no role restriction.</strong> Any authenticated caller with <code>content:write</code> scope may create, update or delete rules, a viewer-role session included, because no <code>denyRole('viewer')</code> is applied here.</p> <blockquote> <p><strong>Response shape note:</strong> the 404s in this section are bare <code>{ "error": "not_found" }</code>, and the enum validation failures are <code>{ "error": "<code>", "valid": [...] }</code>. Neither includes a <code>message</code> field, unlike the rest of the API. <code>missing_fields</code> is the exception: it is the usual <code>{ "error", "message" }</code> shape.</p> </blockquote> <h3 id="get-blocksblockidrules">GET /blocks/{blockId}/rules<a class="anchor" href="#get-blocksblockidrules" aria-label="Permalink">#</a></h3> <p>List a block's personalization targeting rules.</p> <p><strong>Auth:</strong> <code>content:read</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>blockId</code> (integer).</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/blocks/101/rules \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": [ { "id": 5, "block_id": 101, "condition_type": "loyalty_tier", "condition_value": "gold", "override_field": "image_url", "override_value": "https://media.spoonity.com/gold-hero.jpg", "priority": 10, "label": "Gold tier hero" } ] }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>404</td> <td>not_found</td> <td>No such block for this vendor (no <code>message</code> field)</td> </tr> </tbody></table> </div><h3 id="post-blocksblockidrules">POST /blocks/{blockId}/rules<a class="anchor" href="#post-blocksblockidrules" aria-label="Permalink">#</a></h3> <p>Add a personalization targeting rule to a block.</p> <p><strong>Auth:</strong> <code>content:write</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>blockId</code> (integer).</p> <p><strong>Request body:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>condition_type</code></td> <td>string</td> <td>Yes</td> <td><code>loyalty_tier, platform, device_type, region, country, daypart, segment, visit_count_gte, visit_count_lte</code>.</td> </tr> <tr> <td><code>condition_value</code></td> <td>string</td> <td>Yes</td> <td>For <code>device_type</code>: <code>phone</code>/<code>tablet</code>/<code>desktop</code>. For <code>visit_count_*</code>: a number (as a string).</td> </tr> <tr> <td><code>override_field</code></td> <td>string</td> <td>Yes</td> <td><code>title, subtitle, body, image_url, background_url, cta_text, cta_url, cta_deeplink</code>.</td> </tr> <tr> <td><code>override_value</code></td> <td>string</td> <td>Yes</td> <td></td> </tr> <tr> <td><code>priority</code></td> <td>integer</td> <td>No</td> <td>Default <code>0</code>.</td> </tr> <tr> <td><code>label</code></td> <td>string, nullable</td> <td>No</td> <td></td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/blocks/101/rules \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "condition_type": "loyalty_tier", "condition_value": "gold", "override_field": "image_url", "override_value": "https://media.spoonity.com/gold-hero.jpg", "priority": 10 }'</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": { "id": 5, "block_id": 101, "condition_type": "loyalty_tier", "condition_value": "gold", "override_field": "image_url", "override_value": "https://media.spoonity.com/gold-hero.jpg", "priority": 10, "label": null } }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>missing_fields</td> <td>A required field is absent (<code>{ error, message }</code>)</td> </tr> <tr> <td>400</td> <td>invalid_condition / invalid_field / invalid_condition_value</td> <td>Unrecognized enum value (<code>{ error, valid: [...] }</code>)</td> </tr> <tr> <td>404</td> <td>not_found</td> <td>No such block for this vendor (no <code>message</code> field)</td> </tr> </tbody></table> </div><h3 id="put-blocksblockidrulesruleid">PUT /blocks/{blockId}/rules/{ruleId}<a class="anchor" href="#put-blocksblockidrulesruleid" aria-label="Permalink">#</a></h3> <p>Omitted fields are left unchanged, and a <code>null</code> value also leaves the field unchanged, so <code>priority</code> and <code>label</code> cannot be cleared here. The rule is looked up by <code>ruleId</code> within the vendor; the <code>blockId</code> in the path is not checked against it.</p> <p><strong>Auth:</strong> <code>content:write</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>blockId</code>, <code>ruleId</code> (integers).</p> <p><strong>Request body:</strong> <code>condition_value</code>, <code>override_value</code>, <code>priority</code>, <code>label</code> — all optional.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X PUT https://cms.spoonity.com/api/v1/blocks/101/rules/5 \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "priority": 20 }'</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": { "id": 5, "priority": 20 } }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>404</td> <td>not_found</td> <td>No rule with that id for this vendor (no <code>message</code> field)</td> </tr> </tbody></table> </div><h3 id="delete-blocksblockidrulesruleid">DELETE /blocks/{blockId}/rules/{ruleId}<a class="anchor" href="#delete-blocksblockidrulesruleid" aria-label="Permalink">#</a></h3> <p>Remove a personalization targeting rule. As with <code>PUT</code>, the rule is looked up by <code>ruleId</code> within the vendor and the path's <code>blockId</code> is not checked.</p> <p><strong>Auth:</strong> <code>content:write</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>blockId</code>, <code>ruleId</code> (integers).</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X DELETE https://cms.spoonity.com/api/v1/blocks/101/rules/5 \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "success": true }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>404</td> <td>not_found</td> <td>No rule with that id for this vendor (no <code>message</code> field)</td> </tr> </tbody></table> </div><hr> <h2 id="translations">Translations<a class="anchor" href="#translations" aria-label="Permalink">#</a></h2> <p>Block-level localized overrides. Like Personalization, <strong>write routes carry no role restriction</strong> beyond <code>content:write</code> scope: any authenticated caller with that scope may write translations, a viewer-role session included. Supported locales: <code>en-CA, fr-CA, en-US, es-US, fr-FR, pt-BR</code>.</p> <h3 id="get-blocksblockidtranslations">GET /blocks/{blockId}/translations<a class="anchor" href="#get-blocksblockidtranslations" aria-label="Permalink">#</a></h3> <p>List a block's locale overrides.</p> <p><strong>Auth:</strong> <code>content:read</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>blockId</code> (integer).</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/blocks/101/translations \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": [ { "block_id": 101, "locale": "fr-CA", "title": "Saison café glacé", "updated_at": "2026-08-01 09:00:00" } ], "meta": { "block_id": 101, "supported_locales": ["en-CA", "fr-CA", "en-US", "es-US", "fr-FR", "pt-BR"], "translated_locales": ["fr-CA"], "coverage": "1/5" } }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>404</td> <td>not_found</td> <td>No such block for this vendor</td> </tr> </tbody></table> </div><h3 id="get-blocksblockidtranslationslocale">GET /blocks/{blockId}/translations/{locale}<a class="anchor" href="#get-blocksblockidtranslationslocale" aria-label="Permalink">#</a></h3> <p>Get a block's override for one locale.</p> <p><strong>Auth:</strong> <code>content:read</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>blockId</code> (integer), <code>locale</code> (string, one of the supported locales).</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/blocks/101/translations/fr-CA \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": { "block_id": 101, "locale": "fr-CA", "title": "Saison café glacé" } }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>404</td> <td>not_found</td> <td>No such block for this vendor, or no translation for that locale</td> </tr> </tbody></table> </div><h3 id="put-blocksblockidtranslationslocale">PUT /blocks/{blockId}/translations/{locale}<a class="anchor" href="#put-blocksblockidtranslationslocale" aria-label="Permalink">#</a></h3> <p>Upsert. At least one translatable field must be present; unsupplied fields keep their previous value (<code>COALESCE</code>).</p> <p><strong>Auth:</strong> <code>content:write</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>blockId</code> (integer), <code>locale</code> (string).</p> <p><strong>Request body:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>title</code>, <code>subtitle</code>, <code>body</code>, <code>cta_text</code>, <code>image_url</code>, <code>video_url</code>, <code>poster_url</code></td> <td>string</td> <td>At least one</td> <td></td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X PUT https://cms.spoonity.com/api/v1/blocks/101/translations/fr-CA \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "title": "Saison café glacé", "cta_text": "Commander" }'</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": { "block_id": 101, "locale": "fr-CA", "title": "Saison café glacé", "cta_text": "Commander", "updated_at": "2026-08-31 12:00:00" } }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>unsupported_locale</td> <td><code>locale</code> is not one of the six supported values</td> </tr> <tr> <td>400</td> <td>empty_translation</td> <td>No translatable field supplied</td> </tr> <tr> <td>404</td> <td>not_found</td> <td>No such block for this vendor</td> </tr> </tbody></table> </div><h3 id="delete-blocksblockidtranslationslocale">DELETE /blocks/{blockId}/translations/{locale}<a class="anchor" href="#delete-blocksblockidtranslationslocale" aria-label="Permalink">#</a></h3> <p>Remove a block's override for one locale, falling back to the default.</p> <p><strong>Auth:</strong> <code>content:write</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>blockId</code> (integer), <code>locale</code> (string).</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X DELETE https://cms.spoonity.com/api/v1/blocks/101/translations/fr-CA \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "success": true, "message": "Translation for fr-CA removed" }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>404</td> <td>not_found</td> <td>No such block for this vendor, or no translation for that locale</td> </tr> </tbody></table> </div><h3 id="item-level-translations">Item-level translations<a class="anchor" href="#item-level-translations" aria-label="Permalink">#</a></h3> <p>The block-level translation overlay above only ever translates a block's own top-level fields (<code>title</code>, <code>subtitle</code>, …) — it never reaches inside <code>config.items[]</code>. Item-level translations extend the same overlay model to fields <em>inside</em> a block's config: <code>faq</code> question/answer, <code>carousel</code> item titles, <code>points_program</code> reward titles, and so on. Each override is addressed by a path <code>config.<key>[<ref>].<field></code>, where <code><key></code> is the item-array key for the block type (<code>items</code> everywhere except <code>image_gallery</code>, which uses <code>images</code>), <code><ref></code> is the item's stable <code>id</code> (or a plain array index as a legacy fallback for items saved before ids existed), and <code><field></code> is one of that block type's translatable item fields:</p> <div class="scroll-box"><table> <thead> <tr> <th>Block type</th> <th>Translatable item fields</th> </tr> </thead> <tbody><tr> <td><code>faq</code></td> <td><code>question</code>, <code>answer</code></td> </tr> <tr> <td><code>carousel</code></td> <td><code>title</code>, <code>subtitle</code>, <code>cta_text</code></td> </tr> <tr> <td><code>featured_items</code></td> <td><code>label</code></td> </tr> <tr> <td><code>image_gallery</code></td> <td><code>alt</code></td> </tr> <tr> <td><code>points_program</code></td> <td><code>title</code>, <code>subtitle</code>, <code>description</code>, <code>badge</code></td> </tr> <tr> <td><code>egift_artwork</code></td> <td><code>label</code></td> </tr> </tbody></table> </div><p>This is purely additive to the 7-field block-level overlay — neither existing translations nor existing stored blocks are affected.</p> <h3 id="get-blocksblockidtranslationslocaleitems">GET /blocks/{blockId}/translations/{locale}/items<a class="anchor" href="#get-blocksblockidtranslationslocaleitems" aria-label="Permalink">#</a></h3> <p>Item-level translations for one block/locale, as a flat <code>{ path: value }</code> map.</p> <p><strong>Auth:</strong> <code>content:read</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>blockId</code> (integer), <code>locale</code> (string).</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/blocks/101/translations/fr-CA/items \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": { "config.items[abc123def0].question": "Quelle est votre politique de retour ?" } }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>404</td> <td>not_found</td> <td>No such block for this vendor</td> </tr> </tbody></table> </div><h3 id="put-blocksblockidtranslationslocaleitems">PUT /blocks/{blockId}/translations/{locale}/items<a class="anchor" href="#put-blocksblockidtranslationslocaleitems" aria-label="Permalink">#</a></h3> <p>Upsert (and clear) item-level translations for one block/locale in a single call.</p> <p><strong>Auth:</strong> <code>content:write</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>blockId</code> (integer), <code>locale</code> (string).</p> <p><strong>Request body:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>translations</code></td> <td>object (<code>{ path: string | null }</code>)</td> <td>Yes, at least one entry</td> <td>A <code>null</code> or empty-string value <strong>deletes</strong> that path's translation — unlike the block-level <code>PUT</code> above, item translations map 1:1 to rows, so clearing one doesn't need a separate <code>DELETE</code> call.</td> </tr> </tbody></table> </div><p>Every path is validated against the block's type and its <strong>current</strong> <code>config</code> — the array key must match the type (<code>items</code>/<code>images</code>), the field must be translatable for the type, and the referenced item must actually exist (by id, or by index as the legacy fallback). An unknown/malformed path <code>400</code>s the <strong>whole</strong> request before anything is written. Value types are checked later, while writing: a value that is neither a string nor <code>null</code> <code>400</code>s at that entry, and entries processed before it stay applied.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X PUT https://cms.spoonity.com/api/v1/blocks/101/translations/fr-CA/items \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "translations": { "config.items[abc123def0].question": "Quelle est votre politique de retour ?" } }'</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": { "config.items[abc123def0].question": "Quelle est votre politique de retour ?" } }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>unsupported_locale</td> <td><code>locale</code> is not one of the six supported values</td> </tr> <tr> <td>400</td> <td>bad_request</td> <td><code>translations</code> missing/empty/not an object, a value isn't a string or <code>null</code>, or a path is unknown/malformed for this block's current config (<code>details.path</code> names the offending path)</td> </tr> <tr> <td>404</td> <td>not_found</td> <td>No such block for this vendor</td> </tr> </tbody></table> </div><h3 id="delete-blocksblockidtranslationslocaleitems">DELETE /blocks/{blockId}/translations/{locale}/items<a class="anchor" href="#delete-blocksblockidtranslationslocaleitems" aria-label="Permalink">#</a></h3> <p>Remove one item-level translation.</p> <p><strong>Auth:</strong> <code>content:write</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>blockId</code> (integer), <code>locale</code> (string).</p> <p><strong>Query parameters:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>path</code></td> <td>string</td> <td>Yes</td> <td>The exact path to remove.</td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X DELETE "https://cms.spoonity.com/api/v1/blocks/101/translations/fr-CA/items?path=config.items%5Babc123def0%5D.question" \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "success": true, "message": "Item translation at config.items[abc123def0].question removed" }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>bad_request</td> <td>Query param <code>path</code> is missing</td> </tr> <tr> <td>404</td> <td>not_found</td> <td>No such block for this vendor, or no item translation at that path</td> </tr> </tbody></table> </div><h3 id="get-translationscoveragespaceid">GET /translations/coverage/{spaceId}<a class="anchor" href="#get-translationscoveragespaceid" aria-label="Permalink">#</a></h3> <p>Per-locale translation completeness across all blocks in a space — both the block-level overlay and, additively, the item-level fields above.</p> <p><strong>Auth:</strong> <code>content:read</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>spaceId</code> (integer).</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/translations/coverage/42 \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": { "fr-CA": { "translated": 2, "total": 3, "pct": 67, "item_fields": { "translated": 4, "total": 6, "pct": 67 } } }, "total_blocks": 3, "total_item_fields": 6, "default_locale": "en-CA" }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>404</td> <td>not_found</td> <td>No such space for this vendor (no <code>message</code> field — undocumented in the prior spec)</td> </tr> </tbody></table> </div><hr> <h2 id="experiments-abn-testing">Experiments (A/B/n testing)<a class="anchor" href="#experiments-abn-testing" aria-label="Permalink">#</a></h2> <p>Multivariate testing with two or more variants and deterministic <code>client_id</code>-hash bucket assignment. Legacy 2-variant fields (<code>variant_a</code>, <code>variant_b</code>, <code>split_pct</code>) still work but are deprecated (sunset 2026-12-31) in favor of the <code>variants[]</code> array; using them on <code>POST /experiments</code> sets <code>Deprecation: true</code> and <code>Sunset: 2026-12-31</code> response headers and adds <code>_deprecated_fields</code> and <code>_migration</code> to the body.</p> <h3 id="get-experiments">GET /experiments<a class="anchor" href="#get-experiments" aria-label="Permalink">#</a></h3> <p>List A/B/n experiments for this vendor.</p> <p><strong>Auth:</strong> <code>experiments:read</code> scope, or dashboard JWT.</p> <p><strong>Query parameters:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>page</code></td> <td>integer</td> <td>Default <code>1</code>.</td> </tr> <tr> <td><code>per_page</code></td> <td>integer</td> <td>Default <code>20</code>, max <code>100</code>.</td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/experiments \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": [ { "id": 3, "name": "Hero CTA test", "space_id": 42, "status": "running", "variants": [ { "label": "a", "block_id": 101, "traffic_pct": 50, "impressions": 1200, "conversions": 90, "conversion_rate": 0.075 }, { "label": "b", "block_id": 102, "traffic_pct": 50, "impressions": 1180, "conversions": 110, "conversion_rate": 0.0932, "confidence_vs_control": 90, "lift_pct": 24.3 } ], "total_impressions": 2380, "total_conversions": 200 } ], "meta": { "page": 1, "per_page": 20, "total": 1, "total_pages": 1 } }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>403</td> <td>insufficient_scope</td> <td>Key lacks <code>experiments:read</code></td> </tr> </tbody></table> </div><h3 id="post-experiments">POST /experiments<a class="anchor" href="#post-experiments" aria-label="Permalink">#</a></h3> <p>Create an experiment in <code>draft</code>. Provide either <code>variants[]</code> (two or more entries; no maximum is enforced) or legacy <code>variant_a</code>/<code>variant_b</code>. Returns <code>201</code>.</p> <p><strong>Auth:</strong> <code>experiments:write</code> scope, or dashboard JWT.</p> <p><strong>Request body:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>name</code></td> <td>string</td> <td>Yes</td> <td></td> </tr> <tr> <td><code>space_id</code></td> <td>integer</td> <td>Yes</td> <td></td> </tr> <tr> <td><code>hypothesis</code></td> <td>string, nullable</td> <td>No</td> <td></td> </tr> <tr> <td><code>variants</code></td> <td>array of <code>{ label, block_id, traffic_pct }</code></td> <td>No*</td> <td>*Either this or <code>variant_a</code>+<code>variant_b</code>. <code>traffic_pct</code> values must sum to exactly 100 — <strong>the route enforces no per-variant minimum/maximum</strong>, only the sum. Labels and block ids must be unique within the array, and each block must belong to <code>space_id</code>.</td> </tr> <tr> <td><code>variant_a</code>, <code>variant_b</code></td> <td>integer (block id)</td> <td>No*</td> <td>Legacy 2-variant path.</td> </tr> <tr> <td><code>split_pct</code></td> <td>integer</td> <td>No</td> <td>Legacy: variant A's traffic share. Default <code>50</code>.</td> </tr> <tr> <td><code>flags_flag_key</code></td> <td>string, nullable</td> <td>No</td> <td>Key of an existing flag in the vendor's Spoonity Flags environment (<code>^[a-z0-9][a-z0-9_-]{0,63}$</code>; <code>flagsFlagKey</code> is accepted as an alias). Empty/<code>null</code> clears it. See <a href="#flags-assigned-experiments">Flags-assigned experiments</a>.</td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/experiments \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "name": "Hero CTA test", "space_id": 42, "variants": [ { "label": "a", "block_id": 101, "traffic_pct": 50 }, { "label": "b", "block_id": 102, "traffic_pct": 50 } ] }'</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": { "id": 3, "name": "Hero CTA test", "space_id": 42, "status": "draft", "variants": [ { "label": "a", "block_id": 101, "traffic_pct": 50 }, { "label": "b", "block_id": 102, "traffic_pct": 50 } ] } }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>missing_fields</td> <td><code>name</code>/<code>space_id</code> absent, or neither <code>variants</code> nor <code>variant_a</code>+<code>variant_b</code> provided</td> </tr> <tr> <td>400</td> <td>duplicate_labels / duplicate_blocks / invalid_traffic / invalid_blocks / invalid_variants</td> <td>Variant validation failure</td> </tr> <tr> <td>400</td> <td>invalid_flags_flag_key</td> <td><code>flags_flag_key</code> does not match the flag-key pattern (<code>message</code> explains)</td> </tr> </tbody></table> </div><h3 id="flags-assigned-experiments">Flags-assigned experiments<a class="anchor" href="#flags-assigned-experiments" aria-label="Permalink">#</a></h3> <p>Experiments carry two extra read fields (spoonity-cms #33): <code>flags_flag_key</code> (string or <code>null</code>) and <code>flags_assignment_active</code> (boolean) — <code>true</code> when the server runs with <code>EXPERIMENTS_ASSIGNMENT=flags</code> (default <code>legacy</code>) <strong>and</strong> the experiment has a key. When active, the Content Delivery API asks Spoonity Flags for the visitor's treatment (a dry-run <code>POST /sdk/v1/evaluate</code> for <code>flags_flag_key</code>, using the request's platform, locale, region, store, daypart, tier, visit count and segments as targeting attributes) and maps it to a variant: treatment name equal to the variant label (case-insensitive), or <code>variant-<label></code> / <code>variant_<label></code>, or a treatment config JSON with <code>"variant": "<label>"</code>. Anything else — Flags unreachable, no server key for the vendor, unknown flag, <code>control</code>, an unmapped treatment, or no <code>client_id</code> — falls back to the legacy bucket (<code>hash(client_id) mod 100</code> over cumulative <code>traffic_pct</code>). The CMS's own impression counts always run (they feed stats and the winner view); when Flags assigned, the exposure is also forwarded to Flags in batches. The CMS never creates or edits the flag.</p> <h3 id="get-experimentsid">GET /experiments/{id}<a class="anchor" href="#get-experimentsid" aria-label="Permalink">#</a></h3> <p>Get experiment details, per-variant stats and a 30-day daily time series.</p> <p><strong>Auth:</strong> <code>experiments:read</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>id</code> (integer).</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/experiments/3 \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": { "id": 3, "name": "Hero CTA test", "status": "running", "variants": [ { "label": "a", "impressions": 1200, "conversions": 90 } ] }, "daily": [ { "date": "2026-08-30", "variant": "a", "cnt": 400, "type": "impression" } ] }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>404</td> <td>not_found</td> <td>No such experiment for this vendor</td> </tr> </tbody></table> </div><h3 id="put-experimentsid">PUT /experiments/{id}<a class="anchor" href="#put-experimentsid" aria-label="Permalink">#</a></h3> <p>Update <code>name</code>, <code>hypothesis</code>, <code>split_pct</code>, <code>variants[]</code> or <code>flags_flag_key</code>. Cannot edit a <code>running</code> experiment. When the experiment has a <code>flags_flag_key</code> and Flags assignment is active, the response also carries <code>flags_warnings</code> (string[], never an error): flag missing, Flags unreachable, no server key for the vendor, or a treatment that does not map to a variant (and vice versa).</p> <p><strong>Auth:</strong> <code>experiments:write</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>id</code> (integer).</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X PUT https://cms.spoonity.com/api/v1/experiments/3 \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "hypothesis": "Variant B increases order-page CTR" }'</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": { "id": 3, "hypothesis": "Variant B increases order-page CTR" } }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>running</td> <td>Experiment is currently running — stop it first</td> </tr> <tr> <td>400</td> <td>invalid_traffic</td> <td><code>variants[]</code> percentages don't sum to 100</td> </tr> <tr> <td>400</td> <td>invalid_flags_flag_key</td> <td><code>flags_flag_key</code> does not match the flag-key pattern</td> </tr> <tr> <td>404</td> <td>not_found</td> <td>No such experiment for this vendor</td> </tr> </tbody></table> </div><h3 id="post-experimentsidstart">POST /experiments/{id}/start<a class="anchor" href="#post-experimentsidstart" aria-label="Permalink">#</a></h3> <p>Only one experiment may run per space at a time.</p> <p><strong>Auth:</strong> <code>experiments:write</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>id</code> (integer).</p> <p><code>data.assignment</code> is <code>flags</code> when Flags assignment is active for this experiment, otherwise <code>legacy</code>; <code>data.flags_warnings</code> (string[]) is present when there is something to fix (see <code>PUT /experiments/{id}</code>). Warnings never block the start. The activity log records <code>started</code>.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/experiments/3/start \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": { "id": "3", "status": "running", "assignment": "legacy" } }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>already_running / completed / conflict</td> <td>Bad state, or another experiment is already running for this space</td> </tr> <tr> <td>404</td> <td>not_found</td> <td>No such experiment for this vendor</td> </tr> </tbody></table> </div><h3 id="post-experimentsidstop">POST /experiments/{id}/stop<a class="anchor" href="#post-experimentsidstop" aria-label="Permalink">#</a></h3> <p>Stop a running experiment without declaring a winner. The activity log records <code>stopped</code>.</p> <p><strong>Auth:</strong> <code>experiments:write</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>id</code> (integer).</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/experiments/3/stop \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": { "id": "3", "status": "stopped" } }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>not_running</td> <td>Experiment is not currently running</td> </tr> <tr> <td>404</td> <td>not_found</td> <td>No such experiment for this vendor</td> </tr> </tbody></table> </div><h3 id="post-experimentsidwinner">POST /experiments/{id}/winner<a class="anchor" href="#post-experimentsidwinner" aria-label="Permalink">#</a></h3> <p>Declare a winning variant; marks the experiment <code>completed</code>.</p> <p><strong>Auth:</strong> <code>experiments:write</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>id</code> (integer).</p> <p><strong>Request body:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>winner</code></td> <td>string</td> <td>Yes</td> <td>Variant label (<code>a</code>, <code>b</code>, <code>c</code>, …) — must exist in the experiment.</td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/experiments/3/winner \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "winner": "b" }'</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": { "id": "3", "status": "completed", "winner": "b" } }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>invalid_winner</td> <td><code>winner</code> missing or not a valid variant label</td> </tr> <tr> <td>404</td> <td>not_found</td> <td>No such experiment for this vendor</td> </tr> </tbody></table> </div><h3 id="delete-experimentsid">DELETE /experiments/{id}<a class="anchor" href="#delete-experimentsid" aria-label="Permalink">#</a></h3> <p>Cannot delete while running. Removes all impression/conversion data.</p> <p><strong>Auth:</strong> <code>experiments:write</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>id</code> (integer).</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X DELETE https://cms.spoonity.com/api/v1/experiments/3 \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "success": true }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>running</td> <td>Stop the experiment before deleting it</td> </tr> <tr> <td>404</td> <td>not_found</td> <td>No such experiment for this vendor</td> </tr> </tbody></table> </div><h3 id="post-experimentsidconvert">POST /experiments/{id}/convert<a class="anchor" href="#post-experimentsidconvert" aria-label="Permalink">#</a></h3> <p>Public endpoint. Client apps call this after a measurable user action (a CTA click, a purchase). A repeat conversion for the same <code>(client_id, event_type)</code> is silently ignored by a unique index and still answers <code>{ "recorded": true }</code>. A conversion sent without <code>client_id</code> is never deduplicated.</p> <p><strong>Auth:</strong> None — public.</p> <p><strong>Path parameters:</strong> <code>id</code> (integer, experiment id).</p> <p><strong>Request body:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>variant</code></td> <td>string</td> <td>Yes</td> <td>Variant label the client was shown.</td> </tr> <tr> <td><code>client_id</code></td> <td>string</td> <td>No</td> <td></td> </tr> <tr> <td><code>event_type</code></td> <td>string</td> <td>No</td> <td>Default <code>cta_click</code>.</td> </tr> <tr> <td><code>space_slug</code>, <code>platform</code></td> <td>string</td> <td>No</td> <td></td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/experiments/3/convert \ -H "Content-Type: application/json" \ -d '{ "variant": "b", "client_id": "device-abc123", "event_type": "cta_click" }'</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "recorded": true }</code></pre> <p>If the experiment isn't running:</p> <pre><code class="language-json">{ "recorded": false, "reason": "experiment_not_running" }</code></pre> <p><code>{ "recorded": false, "reason": "already_converted" }</code> appears only when the insert itself fails. The variant label is validated only while the experiment is running.</p> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>invalid_variant</td> <td><code>variant</code> missing, not a string, or not a label on this experiment</td> </tr> <tr> <td>404</td> <td>not_found</td> <td>No such experiment</td> </tr> </tbody></table> </div><hr> <h2 id="analytics">Analytics<a class="anchor" href="#analytics" aria-label="Permalink">#</a></h2> <p>Aggregate statistics derived from CMS tables — no separate analytics store. All endpoints are read-only (<code>analytics:read</code> scope covers every one; there is no <code>analytics:write</code>).</p> <h3 id="get-analyticsoverview">GET /analytics/overview<a class="anchor" href="#get-analyticsoverview" aria-label="Permalink">#</a></h3> <p>KPI counts with period-over-period change, plus a content freshness score (0–100).</p> <p><strong>Auth:</strong> <code>analytics:read</code> scope, or dashboard JWT.</p> <p><strong>Query parameters:</strong> <code>range</code> — <code>7d</code> (default), <code>30d</code>, or <code>90d</code>.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl "https://cms.spoonity.com/api/v1/analytics/overview?range=30d" \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "total_spaces": 12, "published_spaces": 8, "draft_spaces": 3, "total_blocks": 41, "total_media": 20, "total_versions": 30, "activity_events": 55, "activity_change": 12, "new_spaces": 2, "spaces_change": 0, "publish_rate": 67, "freshness_score": 88, "range": "30d" }</code></pre> <p><strong>Errors:</strong> none beyond auth.</p> <h3 id="get-analyticsactivity-trends">GET /analytics/activity-trends<a class="anchor" href="#get-analyticsactivity-trends" aria-label="Permalink">#</a></h3> <p>Daily event counts by action.</p> <p><strong>Auth:</strong> <code>analytics:read</code> scope, or dashboard JWT.</p> <p><strong>Query parameters:</strong> <code>range</code> — <code>7d</code> (default), <code>30d</code>, <code>90d</code>.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl "https://cms.spoonity.com/api/v1/analytics/activity-trends?range=7d" \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "dates": ["2026-08-25", "2026-08-26"], "series": { "created": [1, 0], "published": [0, 1] }, "totals": [1, 1], "range": "7d" }</code></pre> <p><strong>Errors:</strong> none beyond auth.</p> <h3 id="get-analyticscontent-breakdown">GET /analytics/content-breakdown<a class="anchor" href="#get-analyticscontent-breakdown" aria-label="Permalink">#</a></h3> <p>Distributions across block types, platforms, workflow statuses and activity action types.</p> <p><strong>Auth:</strong> <code>analytics:read</code> scope, or dashboard JWT.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/analytics/content-breakdown \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "block_types": [ { "block_type": "hero_banner", "cnt": 12 } ], "platforms": [ { "platform": "app", "cnt": 9 } ], "statuses": [ { "status": "published", "cnt": 8 } ], "action_types": [ { "action": "created", "cnt": 30 } ] }</code></pre> <p><strong>Errors:</strong> none beyond auth.</p> <h3 id="get-analyticstop-spaces">GET /analytics/top-spaces<a class="anchor" href="#get-analyticstop-spaces" aria-label="Permalink">#</a></h3> <p>Top 10 spaces ranked by recent activity, then block count.</p> <p><strong>Auth:</strong> <code>analytics:read</code> scope, or dashboard JWT.</p> <p><strong>Query parameters:</strong> <code>range</code> — default <code>30d</code>.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/analytics/top-spaces \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": [ { "id": 42, "name": "Summer Promo", "status": "published", "block_count": 3, "version_count": 4, "recent_activity": 6 } ], "range": "30d" }</code></pre> <p><strong>Errors:</strong> none beyond auth.</p> <h3 id="get-analyticsdelivery-stats">GET /analytics/delivery-stats<a class="anchor" href="#get-analyticsdelivery-stats" aria-label="Permalink">#</a></h3> <p>Daily delivery <strong>API fetches</strong> (not user impressions — see content-performance for those), top- served spaces, platform split and average response time.</p> <p><strong>Auth:</strong> <code>analytics:read</code> scope, or dashboard JWT.</p> <p><strong>Query parameters:</strong> <code>range</code> — default <code>30d</code>.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/analytics/delivery-stats \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "dates": ["2026-08-01"], "impressions": [340], "response_ms": [42], "top_served": [ { "space_slug": "summer-promo", "impressions": 340 } ], "platforms": [ { "platform": "app", "cnt": 300 } ], "total_impressions": 340, "avg_response_ms": 42, "range": "30d" }</code></pre> <p><code>response_ms</code> is the per-day average response time, index-aligned with <code>dates</code> (and <code>impressions</code>). It is <code>null</code> — never <code>0</code> — on a day with no delivery events or no timing data, so a quiet day reads as a gap rather than a real 0ms reading; <code>dates</code> is always ascending.</p> <p><strong>Errors:</strong> none beyond auth.</p> <h3 id="get-analyticscontent-performance">GET /analytics/content-performance<a class="anchor" href="#get-analyticscontent-performance" aria-label="Permalink">#</a></h3> <p>Impression/click/conversion aggregates from <code>POST /track/{vendorSlug}</code> events.</p> <p><strong>Auth:</strong> <code>analytics:read</code> scope, or dashboard JWT.</p> <p><strong>Query parameters:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>days</code></td> <td>integer</td> <td>Default <code>30</code>. Clamped into <code>1</code> to <code>365</code>; an out-of-range value is not an error.</td> </tr> <tr> <td><code>group_by</code></td> <td>string</td> <td><code>space</code> (default), <code>block</code>, <code>campaign</code>, or <code>day</code>.</td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl "https://cms.spoonity.com/api/v1/analytics/content-performance?group_by=block&days=7" \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "group_by": "block", "days": 7, "data": [ { "block_id": 101, "impressions": 1200, "clicks": 90, "conversions": 12, "ctr": 0.075, "title": "Cold Brew Season", "block_type": "hero_banner" } ], "totals": { "impressions": 1200, "clicks": 90, "conversions": 12, "ctr": 0.075 } }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>bad_request</td> <td>Unrecognized <code>group_by</code></td> </tr> </tbody></table> </div><h3 id="get-analyticsuser-activity">GET /analytics/user-activity<a class="anchor" href="#get-analyticsuser-activity" aria-label="Permalink">#</a></h3> <p>Top 10 team members by event count, with per-action breakdown.</p> <p><strong>Auth:</strong> <code>analytics:read</code> scope, or dashboard JWT.</p> <p><strong>Query parameters:</strong> <code>range</code> — default <code>30d</code>.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/analytics/user-activity \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": [ { "user_email": "editor@acme-cafe.com", "total": 22, "creates": 5, "updates": 15, "publishes": 2, "deletes": 0 } ], "range": "30d" }</code></pre> <p><strong>Errors:</strong> none beyond auth.</p> <h3 id="get-analyticsheatmap">GET /analytics/heatmap<a class="anchor" href="#get-analyticsheatmap" aria-label="Permalink">#</a></h3> <p>7×24 grid (day-of-week × hour) of activity-log event counts.</p> <p><strong>Auth:</strong> <code>analytics:read</code> scope, or dashboard JWT.</p> <p><strong>Query parameters:</strong> <code>range</code> — default <code>30d</code>.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/analytics/heatmap \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "grid": [[0,0,0,1,2], [0,0,0,0,0]], "range": "30d" }</code></pre> <p><strong>Errors:</strong> none beyond auth.</p> <hr> <h2 id="activity-log">Activity Log<a class="anchor" href="#activity-log" aria-label="Permalink">#</a></h2> <h3 id="get-activity">GET /activity<a class="anchor" href="#get-activity" aria-label="Permalink">#</a></h3> <p>Audit trail of CMS content changes for the vendor. <strong>Not scope-gated</strong> — any authenticated principal with vendor context can read it, regardless of API key scopes.</p> <p><strong>Auth:</strong> Any valid API key or dashboard JWT (no specific scope required).</p> <p><strong>Query parameters:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>page</code></td> <td>integer</td> <td>Default <code>1</code>.</td> </tr> <tr> <td><code>limit</code></td> <td>integer</td> <td>Default <code>50</code>, max <code>100</code>.</td> </tr> <tr> <td><code>entity_type</code></td> <td>string</td> <td><code>space, block, media, experiment, webhook, user</code>.</td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl "https://cms.spoonity.com/api/v1/activity?entity_type=space&limit=10" \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": [ { "id": 88, "vendor_id": 7, "user_email": "admin@acme-cafe.com", "action": "published", "entity_type": "space", "entity_id": 42, "entity_name": "Summer Promo", "details": { "version": 4 }, "created_at": "2026-08-31 12:00:00" } ], "pagination": { "page": 1, "limit": 10, "total": 1, "total_pages": 1 } }</code></pre> <p>Experiment start/stop are logged as <code>started</code>/<code>stopped</code> (spoonity-cms #37); older rows that were written as <code>published</code>/<code>unpublished</code> are mapped to those names on read for <code>entity_type=experiment</code>. Space actions keep <code>published</code>/<code>unpublished</code>.</p> <p><strong>Errors:</strong> none beyond auth.</p> <hr> <h2 id="search">Search<a class="anchor" href="#search" aria-label="Permalink">#</a></h2> <h3 id="get-search">GET /search<a class="anchor" href="#get-search" aria-label="Permalink">#</a></h3> <p>Server-side full-text search (SQL <code>LIKE</code>) across spaces, blocks and experiments, ranked spaces → blocks → experiments. <strong>Not scope-gated</strong> — any authenticated principal with vendor context can search, regardless of API key scopes.</p> <p><strong>Auth:</strong> Any valid API key or dashboard JWT (no specific scope required).</p> <p><strong>Query parameters:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>q</code></td> <td>string</td> <td>Yes</td> <td>At least 2 characters.</td> </tr> <tr> <td><code>types</code></td> <td>string</td> <td>No</td> <td>Comma-separated <code>spaces,blocks,experiments</code>. Default all three.</td> </tr> <tr> <td><code>limit</code></td> <td>integer</td> <td>No</td> <td>Default <code>20</code>, max <code>50</code>.</td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl "https://cms.spoonity.com/api/v1/search?q=cold+brew&types=spaces,blocks" \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": [ { "id": 42, "name": "Summer Promo", "result_type": "space", "block_count": 3 }, { "id": 101, "title": "Cold Brew Season", "result_type": "block", "space_name": "Summer Promo" } ], "query": "cold brew", "total": 2 }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>query_too_short</td> <td><code>q</code> missing or under 2 characters</td> </tr> </tbody></table> </div><hr> <h2 id="targeting-lookups">Targeting Lookups<a class="anchor" href="#targeting-lookups" aria-label="Permalink">#</a></h2> <p>Feeds the dashboard's targeting pickers (space/block <code>region</code>, <code>store_ids</code>, <code>audience</code>) from the vendor's own Spoonity loyalty account, so an editor sees "Flagship" and "Gold" instead of raw ids and codes. Requires a Spoonity service credential (<code>SPOONITY_SERVICE_USERNAME</code>/ <code>SPOONITY_SERVICE_PASSWORD</code>, or <code>SPOONITY_SESSION_KEY</code>) to be configured — for a single-vendor account this happens automatically after the next login; a multi-vendor deployment needs the service credential set explicitly. <code>SPOONITY_PLATFORM_HOST_MAP</code> overrides the platform host for vendors that live on a dedicated cluster rather than <code>api.spoonity.com</code>.</p> <p><strong>Both endpoints always answer <code>200</code>.</strong> "I cannot offer you a list right now" is a normal outcome here, not a client error — no credential configured, the platform unreachable, or a tenancy check that failed all fall back to the dashboard's free-text input rather than raising an error. The body carries <code>available: false</code> plus a <code>reason</code> instead of an HTTP error status.</p> <p><strong>Auth (both endpoints):</strong> dashboard JWT, the legacy vendor-wide key, or a scoped key with <code>*</code> — <code>spaces</code> is <strong>not</strong> in the mintable scope vocabulary (see <a href="#authentication">Authentication</a>), so a newly-minted scoped key cannot reach either route no matter which scopes it's given; only a full-access key or a signed-in session can. Reachable by <strong>every</strong> role, <code>viewer</code> included — an editor picking a targeting value needs the name whether or not they can save the space.</p> <h3 id="get-lookups">GET /lookups<a class="anchor" href="#get-lookups" aria-label="Permalink">#</a></h3> <p>A status summary, so the dashboard can decide once whether to render pickers or free-text inputs, without fetching all four lists up front.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/lookups \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "configured": true, "kinds": ["tiers", "segments", "stores", "regions"], "vendor_id": 7 }</code></pre> <p><strong>Errors:</strong> none beyond auth.</p> <h3 id="get-lookupskind">GET /lookups/{kind}<a class="anchor" href="#get-lookupskind" aria-label="Permalink">#</a></h3> <p>The option list for one lookup kind, in <code>items</code>, each already shaped for a picker: <code>{ value, label, subtitle? }</code>. <code>value</code> is exactly what a space/block stores for that targeting field — tier <strong>names</strong>, region <strong>codes</strong>, store/segment <strong>ids as strings</strong> — so it's also what the Content Delivery API compares client-declared/resolved context against.</p> <p><strong>Path parameters:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>kind</code></td> <td>string</td> <td>One of <code>tiers</code>, <code>segments</code>, <code>stores</code>, <code>regions</code>.</td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/lookups/tiers \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "kind": "tiers", "available": true, "items": [ { "value": "gold", "label": "Gold" }, { "value": "silver", "label": "Silver" } ], "source": "spoonity", "stale": false }</code></pre> <p>Unavailable (still <code>200</code>):</p> <pre><code class="language-json">{ "kind": "tiers", "available": false, "items": [], "reason": "not_configured", "note": "Spoonity lookups are not available yet. A single-vendor account lights these up automatically after logging in again; otherwise set SPOONITY_SERVICE_USERNAME and SPOONITY_SERVICE_PASSWORD (or SPOONITY_SESSION_KEY) to enable them for every vendor." }</code></pre> <p><code>reason</code> is one of <code>not_configured</code>, <code>auth_failed</code> (couldn't authenticate against the Spoonity identity server), <code>tenant_mismatch</code> (the platform host answered for a different vendor — set <code>SPOONITY_PLATFORM_HOST_MAP</code> for this vendor), or <code>upstream_error</code> (the platform didn't answer in time). A fresh list is cached for 5 minutes and served with <code>stale: false</code>. <code>stale: true</code> means an upstream call just failed and the last list fetched for this vendor and kind was served instead, whatever its age.</p> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>404</td> <td>unknown_lookup</td> <td><code>kind</code> isn't one of the four values above (echoes <code>valid</code>)</td> </tr> </tbody></table> </div><hr> <h2 id="webhooks">Webhooks<a class="anchor" href="#webhooks" aria-label="Permalink">#</a></h2> <p>Outbound event notifications. Deliveries are <code>POST</code>ed as <code>{ event, vendor_id, timestamp, data }</code> with <code>X-Spoonity-Signature: sha256=<hmac></code>, <code>X-Spoonity-Event</code> and <code>X-Spoonity-Delivery</code> headers. A failed delivery is attempted at most 3 times in total (retries after 2s and 4s). Verify by HMAC-SHA256'ing the raw body with the webhook's <code>secret</code>. Every error in this group is bare <code>{ "error": "<code>" }</code> with no <code>message</code>, except URL rejections (<code>missing_url</code>, <code>invalid_url</code>) which add a <code>message</code>. Events: <code>space.created</code>, <code>space.submitted</code>, <code>space.approved</code>, <code>space.rejected</code>, <code>space.scheduled</code>, <code>space.published</code>, <code>space.unpublished</code>, <code>space.deleted</code>, <code>space.updated</code>, <code>experiment.started</code>, <code>experiment.stopped</code>, <code>experiment.completed</code>, <code>block.created</code>, <code>block.updated</code>, <code>block.deleted</code>, <code>content.performance.daily</code> (an aggregated <code>{ days, spaces }</code> push after each hourly rollup, not one delivery per event). <strong>Write routes carry no role restriction</strong> beyond <code>webhooks:write</code> scope.</p> <h3 id="webhook-url-rules">Webhook URL rules<a class="anchor" href="#webhook-url-rules" aria-label="Permalink">#</a></h3> <p>Webhook URLs are vendor-supplied and the CMS calls them from inside its own network, so they are checked at create/update and again at delivery (spoonity-cms #36, CM-12). A URL is <strong>rejected</strong> with <code>400 { "error": "invalid_url", "message": "..." }</code> when it:</p> <ul> <li>is longer than 2048 characters or not a parseable URL;</li> <li>does not use <code>https://</code> (<code>http://</code> is accepted only on a development server);</li> <li>uses an IP literal, in any encoding (<code>http://169.254.169.254/</code>, <code>http://2852039166/</code>, <code>[::1]</code>);</li> <li>uses <code>localhost</code>, <code>metadata</code>, <code>metadata.google.internal</code>, any <code>*.localhost</code>, <code>*.internal</code>, <code>*.local</code>, <code>*.localdomain</code> or <code>*.home.arpa</code> name, or a single-label name (no dot);</li> <li>has a name that fails to resolve, or resolves to <strong>any</strong> private or reserved address (loopback, RFC 1918, link-local incl. the <code>169.254.169.254</code> metadata server, CGNAT, multicast, TEST-NETs, and IPv6 equivalents including mapped/NAT64/6to4/Teredo forms).</li> </ul> <p>At delivery the connection is pinned to the address that was checked (defeating DNS rebinding) and <strong>redirects are never followed</strong> — a <code>3xx</code> counts as a failed delivery. A blocked destination is not retried. Stored URLs that predate this check and are now refused are skipped on fan-out (logged server-side only), and <code>POST /webhooks/{id}/test</code> returns <code>400 invalid_url</code> for them; update the URL to fix. <code>PUT</code> re-validates only when <code>url</code> is sent.</p> <h3 id="get-webhooks">GET /webhooks<a class="anchor" href="#get-webhooks" aria-label="Permalink">#</a></h3> <p>List registered webhook endpoints for this vendor.</p> <p><strong>Auth:</strong> <code>webhooks:read</code> scope, or dashboard JWT.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/webhooks \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": [ { "id": 4, "url": "https://acme-cafe.com/webhooks/cms", "events": ["space.published"], "is_active": true, "last_fired_at": "2026-08-30 10:00:00" } ] }</code></pre> <p><strong>Errors:</strong> none beyond auth.</p> <h3 id="post-webhooks">POST /webhooks<a class="anchor" href="#post-webhooks" aria-label="Permalink">#</a></h3> <p>Returns the signing <code>secret</code> once — never returned again on subsequent reads.</p> <p><strong>Auth:</strong> <code>webhooks:write</code> scope, or dashboard JWT.</p> <p><strong>Request body:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>url</code></td> <td>string (URI)</td> <td>Yes</td> <td></td> </tr> <tr> <td><code>events</code></td> <td>string[]</td> <td>No</td> <td>Defaults to every supported event when omitted.</td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/webhooks \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "url": "https://acme-cafe.com/webhooks/cms", "events": ["space.published", "space.unpublished"] }'</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": { "id": 4, "url": "https://acme-cafe.com/webhooks/cms", "events": ["space.published", "space.unpublished"], "is_active": true, "secret": "3f9c1a...b02e" } }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>missing_url / invalid_url / invalid_events</td> <td>Validation failure. <code>missing_url</code> and <code>invalid_url</code> carry a <code>message</code> (see <a href="#webhook-url-rules">Webhook URL rules</a>); <code>invalid_events</code> echoes <code>invalid</code>/<code>valid</code> arrays</td> </tr> </tbody></table> </div><h3 id="get-webhooksid">GET /webhooks/{id}<a class="anchor" href="#get-webhooksid" aria-label="Permalink">#</a></h3> <p>Returns the webhook (secret withheld) plus its last 50 delivery attempts — there is no separate deliveries endpoint.</p> <p><strong>Auth:</strong> <code>webhooks:read</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>id</code> (integer).</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/webhooks/4 \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": { "id": 4, "url": "https://acme-cafe.com/webhooks/cms", "events": ["space.published"], "is_active": true }, "deliveries": [ { "id": 900, "status_code": 200, "created_at": "2026-08-30 10:00:00" } ] }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>404</td> <td>not_found</td> <td>No such webhook for this vendor</td> </tr> </tbody></table> </div><h3 id="put-webhooksid">PUT /webhooks/{id}<a class="anchor" href="#put-webhooksid" aria-label="Permalink">#</a></h3> <p>Update a webhook endpoint's URL, events, or active state.</p> <p><strong>Auth:</strong> <code>webhooks:write</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>id</code> (integer).</p> <p><strong>Request body:</strong> <code>url</code>, <code>events</code>, <code>is_active</code> — all optional.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X PUT https://cms.spoonity.com/api/v1/webhooks/4 \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "is_active": false }'</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": { "id": 4, "is_active": false } }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>invalid_url</td> <td><code>url</code> fails the <a href="#webhook-url-rules">Webhook URL rules</a>; carries a <code>message</code></td> </tr> <tr> <td>404</td> <td>not_found</td> <td>No such webhook for this vendor</td> </tr> </tbody></table> </div><h3 id="post-webhooksidrotate-secret">POST /webhooks/{id}/rotate-secret<a class="anchor" href="#post-webhooksidrotate-secret" aria-label="Permalink">#</a></h3> <p>Generate a new signing secret for a webhook endpoint, invalidating the old one.</p> <p><strong>Auth:</strong> <code>webhooks:write</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>id</code> (integer).</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/webhooks/4/rotate-secret \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": { "secret": "a1b2c3...f9e8" } }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>404</td> <td>not_found</td> <td>No such webhook for this vendor</td> </tr> </tbody></table> </div><h3 id="post-webhooksidtest">POST /webhooks/{id}/test<a class="anchor" href="#post-webhooksidtest" aria-label="Permalink">#</a></h3> <p>Fires a <code>space.published</code> event with <code>data: { test: true, message, webhook_id }</code> to <strong>only</strong> the webhook in the path (spoonity-cms #36 — it used to fan out to every subscribed webhook), whether or not that webhook is active or subscribed to <code>space.published</code>. A stored URL that no longer passes the <a href="#webhook-url-rules">Webhook URL rules</a> is refused before sending.</p> <p><strong>Auth:</strong> <code>webhooks:write</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>id</code> (integer).</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/webhooks/4/test \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "success": true, "message": "Test webhook queued for delivery" }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>invalid_url</td> <td>The stored URL is no longer allowed; <code>message</code> ends <code>Update the URL before testing.</code></td> </tr> <tr> <td>404</td> <td>not_found</td> <td>No such webhook for this vendor</td> </tr> </tbody></table> </div><h3 id="delete-webhooksid">DELETE /webhooks/{id}<a class="anchor" href="#delete-webhooksid" aria-label="Permalink">#</a></h3> <p>Also deletes its delivery history.</p> <p><strong>Auth:</strong> <code>webhooks:write</code> scope, or dashboard JWT.</p> <p><strong>Path parameters:</strong> <code>id</code> (integer).</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X DELETE https://cms.spoonity.com/api/v1/webhooks/4 \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "success": true }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>404</td> <td>not_found</td> <td>No such webhook for this vendor</td> </tr> </tbody></table> </div><hr> <h2 id="team-users">Team (Users)<a class="anchor" href="#team-users" aria-label="Permalink">#</a></h2> <p>Per-vendor team members and their dashboard roles. Not scope-gated (no <code>requireScope</code> at all) — gated purely by <code>requireRole('admin')</code> on the writes.</p> <h3 id="get-users">GET /users<a class="anchor" href="#get-users" aria-label="Permalink">#</a></h3> <p>List this vendor's team members and their dashboard roles.</p> <p><strong>Auth:</strong> Any valid API key or dashboard JWT (no specific scope or role required).</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/users \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "data": [ { "id": 2, "email": "editor@acme-cafe.com", "role": "editor", "added_by": "admin@acme-cafe.com", "created_at": "2026-05-01 09:00:00" } ] }</code></pre> <p><strong>Errors:</strong> none beyond auth.</p> <h3 id="post-users">POST /users<a class="anchor" href="#post-users" aria-label="Permalink">#</a></h3> <p>Upserts a team member by email — this is also how an existing member's role is changed (there is no <code>PUT /users/{id}</code>).</p> <p><strong>Auth:</strong> Dashboard JWT or API key — <strong>admin</strong> role required.</p> <p><strong>Request body:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>email</code></td> <td>string</td> <td>Yes</td> <td></td> </tr> <tr> <td><code>role</code></td> <td>string</td> <td>Yes</td> <td><code>admin</code>, <code>editor</code>, or <code>viewer</code>.</td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/users \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "email": "newmember@acme-cafe.com", "role": "editor" }'</code></pre> <p><strong>Response example (new member, 201):</strong></p> <pre><code class="language-json">{ "data": { "id": 5, "email": "newmember@acme-cafe.com", "role": "editor" } }</code></pre> <p>Updating an existing member's role returns <code>200</code> with <code>{ "data": {...}, "updated": true }</code>.</p> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>missing_fields / invalid_role</td> <td></td> </tr> <tr> <td>403</td> <td>forbidden</td> <td>Caller is not an admin</td> </tr> </tbody></table> </div><h3 id="delete-usersid">DELETE /users/{id}<a class="anchor" href="#delete-usersid" aria-label="Permalink">#</a></h3> <p>Requires admin. A member may not remove themselves.</p> <p><strong>Auth:</strong> Dashboard JWT or API key — <strong>admin</strong> role required.</p> <p><strong>Path parameters:</strong> <code>id</code> (integer, <code>vendor_users</code> row id).</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X DELETE https://cms.spoonity.com/api/v1/users/5 \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "success": true }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>self_removal</td> <td>Cannot remove your own account</td> </tr> <tr> <td>403</td> <td>forbidden</td> <td>Caller is not an admin</td> </tr> <tr> <td>404</td> <td>not_found</td> <td>No such member for this vendor (bare <code>{ "error": "not_found" }</code>, no <code>message</code>)</td> </tr> </tbody></table> </div><hr> <h2 id="brand">Brand<a class="anchor" href="#brand" aria-label="Permalink">#</a></h2> <p>One brand record per vendor — the palette, wordmark and artwork a wallet Pass Studio uses to render a customer's loyalty pass. This is the CMS side of the Wallet pass brand: the CMS is the system of record, and <code>wallet-api.spoonity.com</code> reads/writes it through these same routes rather than its own storage.</p> <h3 id="get-brand">GET /brand<a class="anchor" href="#get-brand" aria-label="Permalink">#</a></h3> <p>This vendor's brand record.</p> <p><strong>Auth:</strong> <code>vendor:read</code> scope, or dashboard JWT.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/brand \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "vendorId": "7", "company": "Acme Cafe Inc.", "name": "Acme Cafe", "colors": { "primary": "#38bdf8", "text": "#0f172a" }, "palette": ["#38bdf8", "#0f172a", "#ffffff"], "logoUri": "https://media.spoonity.com/acme-logo.png", "iconUri": "https://media.spoonity.com/acme-icon.png", "heroUri": null, "sourceUrl": "https://acme-cafe.com", "updatedAt": "2026-08-01T09:00:00.000Z" }</code></pre> <p>The <strong><code>404</code> is load-bearing</strong>, not just tidy REST: a Pass Studio uses it to decide a vendor has never been onboarded and opens its first-run brand-setup flow. A vendor that has never had a brand written for it is a <code>404</code>, not an empty-but-present record.</p> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>404</td> <td>not_found</td> <td>This vendor has no brand record yet</td> </tr> </tbody></table> </div><h3 id="put-brand">PUT /brand<a class="anchor" href="#put-brand" aria-label="Permalink">#</a></h3> <p>Merge a partial patch into the vendor's brand record, creating it if none exists yet. Returns the complete, post-merge brand either way.</p> <p><strong>Merge semantics</strong> — this is the whole point of the endpoint: a field <strong>absent</strong> from the body keeps its previously stored value; a field <strong>present and <code>null</code></strong> clears it; only a present, non-null field overwrites. There is no way to "clear to empty string" — <code>null</code> is the only clear signal. <code>vendorId</code> and <code>updatedAt</code> are not writable — the vendor always comes from the authenticated session and the timestamp is server-set, so echoing a <code>GET</code> response straight back into a <code>PUT</code> can never move a brand onto another tenant.</p> <p><strong>Auth:</strong> <code>vendor:write</code> scope, or dashboard JWT — <strong><code>denyRole('viewer')</code>, deliberately not <code>requireRole('admin')</code>.</strong> The Wallet Pass Studio authenticates as a Google-OIDC service identity, which this API grants the <code>editor</code> role by default — an <code>admin</code>-only gate would 403 the one caller this route exists for. A read-only human (<code>viewer</code>) is refused; a roleless API key and an editor (human or service) can write it.</p> <p><strong>Request body:</strong> any subset of the following, each independently nullable to clear it:</p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>company</code></td> <td>string</td> <td></td> </tr> <tr> <td><code>name</code></td> <td>string</td> <td></td> </tr> <tr> <td><code>colors</code></td> <td>object</td> <td></td> </tr> <tr> <td><code>palette</code></td> <td>array</td> <td></td> </tr> <tr> <td><code>logoUri</code>, <code>iconUri</code>, <code>heroUri</code></td> <td>string</td> <td></td> </tr> <tr> <td><code>sourceUrl</code></td> <td>string</td> <td></td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X PUT https://cms.spoonity.com/api/v1/brand \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \ -H "Content-Type: application/json" \ -d '{ "heroUri": "https://media.spoonity.com/acme-hero.png" }'</code></pre> <p><strong>Response example:</strong> the complete brand, same shape as <code>GET /brand</code>.</p> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>bad_request</td> <td>Body isn't a JSON object, or a field's value is the wrong type (e.g. <code>colors</code> sent as a string)</td> </tr> <tr> <td>403</td> <td>forbidden</td> <td>Caller is a viewer</td> </tr> </tbody></table> </div><hr> <h2 id="vendor-settings--api-keys">Vendor Settings & API Keys<a class="anchor" href="#vendor-settings--api-keys" aria-label="Permalink">#</a></h2> <h3 id="get-vendorsettings">GET /vendor/settings<a class="anchor" href="#get-vendorsettings" aria-label="Permalink">#</a></h3> <p>Returns the vendor row (<code>id</code>, <code>spoonity_vendor_id</code>, <code>name</code>, <code>slug</code>, <code>logo_url</code>, <code>brand_color</code>, <code>settings</code>) plus <code>base_url</code> — this service's own public origin, so a caller whose own origin differs from the CMS's (e.g. the Prism shell) can still build a correct <code>${base_url}/api/v1/content/:vendorSlug/:slug</code> link.</p> <p><strong>Auth:</strong> <code>vendor:read</code> scope, or dashboard JWT. (Reachable by a scoped API key, <strong>not</strong> dashboard-session-only — see the note in Authentication above.)</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/vendor/settings \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "id": 7, "spoonity_vendor_id": "v_9001", "name": "Acme Cafe", "slug": "acme-cafe", "logo_url": null, "brand_color": "#38bdf8", "settings": { "auto_shorten_cta": false }, "base_url": "https://cms.spoonity.com" }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>404</td> <td>not_found</td> <td>Vendor not found</td> </tr> </tbody></table> </div><h3 id="put-vendorsettings">PUT /vendor/settings<a class="anchor" href="#put-vendorsettings" aria-label="Permalink">#</a></h3> <p>Update this vendor's account-level settings.</p> <p><strong>Auth:</strong> <code>vendor:write</code> scope, or dashboard JWT — <strong>admin</strong> role required.</p> <p><strong>Request body:</strong> <code>name</code>, <code>slug</code>, <code>logo_url</code>, <code>brand_color</code>, <code>settings</code>, all optional. <code>settings</code> <strong>replaces</strong> the stored settings object as a whole rather than merging into it, so send every key you want to keep (for example <code>auto_shorten_cta</code> and <code>default_fallback_space_slug</code>). Empty <code>name</code> or <code>slug</code> values are ignored; <code>logo_url</code> and <code>brand_color</code> accept <code>null</code> or <code>""</code> to clear. <code>base_url</code> is never persisted even if echoed back in a naive round-trip of the GET response.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X PUT https://cms.spoonity.com/api/v1/vendor/settings \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "settings": { "auto_shorten_cta": true } }'</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "id": 7, "name": "Acme Cafe", "slug": "acme-cafe", "settings": { "auto_shorten_cta": true } }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>403</td> <td>forbidden</td> <td>Caller is not an admin</td> </tr> <tr> <td>403</td> <td>insufficient_scope</td> <td>Key lacks <code>vendor:write</code></td> </tr> </tbody></table> </div><h3 id="get-vendorapi-keystatus">GET /vendor/api-key/status<a class="anchor" href="#get-vendorapi-keystatus" aria-label="Permalink">#</a></h3> <p>Check whether the legacy vendor-wide API key exists, without exposing it.</p> <p><strong>Auth:</strong> <code>vendor:read</code> scope, or dashboard JWT. (Reachable by a scoped API key — see the note above.)</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/vendor/api-key/status \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "exists": true, "hint": "ab12", "last_rotated": "2026-06-01 09:00:00" }</code></pre> <p><strong>Errors:</strong> none beyond auth.</p> <h3 id="post-vendorapi-keyrotate">POST /vendor/api-key/rotate<a class="anchor" href="#post-vendorapi-keyrotate" aria-label="Permalink">#</a></h3> <p>Generate a new legacy vendor-wide key; the old one stops working immediately.</p> <p><strong>Auth:</strong> Dashboard JWT session <strong>only</strong> (<code>requireJwtSession</code> blocks API keys and service tokens outright) — <strong>admin</strong> role also required.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/vendor/api-key/rotate \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "api_key": "sck_a1b2c3d4e5f6...f6a1", "hint": "f6a1", "message": "Store this key securely. It will not be shown again." }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>403</td> <td>forbidden</td> <td>Caller used an API key/service token, or is not an admin</td> </tr> </tbody></table> </div><h3 id="get-vendorapi-keys">GET /vendor/api-keys<a class="anchor" href="#get-vendorapi-keys" aria-label="Permalink">#</a></h3> <p>List every scoped key ever issued for the vendor (including revoked), newest first. The secret is never returned — only <code>key_hint</code> (last 4 characters).</p> <p><strong>Auth:</strong> Dashboard JWT session <strong>only</strong> — an <code>X-API-Key</code> request is rejected by <code>requireJwtSession</code> regardless of its scopes.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/vendor/api-keys \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">[ { "id": 12, "name": "CMS MCP server", "key_hint": "ab12", "scopes": ["content:read", "content:write"], "role": "editor", "is_active": true, "last_used_at": "2026-08-30 08:00:00", "revoked_at": null, "created_at": "2026-07-01 10:00:00", "created_by": "admin@acme-cafe.com" } ]</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>401</td> <td>unauthorized</td> <td>Missing/invalid credentials</td> </tr> <tr> <td>403</td> <td>forbidden</td> <td>An API key was used instead of a dashboard session</td> </tr> </tbody></table> </div><h3 id="post-vendorapi-keys">POST /vendor/api-keys<a class="anchor" href="#post-vendorapi-keys" aria-label="Permalink">#</a></h3> <p>Mint a named, scoped key. Returns the secret <strong>exactly once</strong>. A vendor may hold at most 20 active keys.</p> <p><strong>Auth:</strong> Dashboard JWT session <strong>only</strong>; minting a key that carries a <code>role</code> additionally requires <strong>admin</strong>.</p> <p><strong>Request body:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>name</code></td> <td>string (max 100)</td> <td>Yes</td> <td></td> </tr> <tr> <td><code>scopes</code></td> <td>string[]</td> <td>Yes</td> <td>From the vocabulary in <a href="#2-scoped-api-keys">Authentication</a>. At least one.</td> </tr> <tr> <td><code>role</code></td> <td>string, nullable</td> <td>No</td> <td><code>viewer</code>/<code>editor</code>/<code>admin</code>. Omit/<code>null</code>/<code>""</code> for a roleless key. Requires an admin session.</td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/vendor/api-keys \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \ -H "Content-Type: application/json" \ -d '{ "name": "Reporting job", "scopes": ["content:read", "analytics:read"] }'</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "id": 13, "name": "Reporting job", "api_key": "sck_9f2c1a4b7e...ab12", "hint": "ab12", "scopes": ["content:read", "analytics:read"], "role": null, "message": "Store this key securely. It will not be shown again." }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>bad_request</td> <td>Missing/blank/over-long <code>name</code>; missing/empty/unrecognized <code>scopes</code> (echoes <code>valid_scopes</code>); unrecognized <code>role</code> (echoes <code>valid_roles</code>); or the 20-key limit is reached</td> </tr> <tr> <td>403</td> <td>forbidden</td> <td>A non-admin session requested a <code>role</code>, or an API key was used instead of a dashboard session</td> </tr> </tbody></table> </div><h3 id="delete-vendorapi-keysid">DELETE /vendor/api-keys/{id}<a class="anchor" href="#delete-vendorapi-keysid" aria-label="Permalink">#</a></h3> <p>Soft-revokes the key (<code>is_active: false</code>, <code>revoked_at</code> stamped); the row is kept for audit and still appears in the list. Idempotent.</p> <p><strong>Auth:</strong> Dashboard JWT session <strong>only</strong>.</p> <p><strong>Path parameters:</strong> <code>id</code> (integer, key id).</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X DELETE https://cms.spoonity.com/api/v1/vendor/api-keys/13 \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."</code></pre> <p><strong>Response example:</strong> <code>204 No Content</code> (empty body).</p> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>bad_request</td> <td><code>id</code> is not a number</td> </tr> <tr> <td>403</td> <td>forbidden</td> <td>An API key was used instead of a dashboard session</td> </tr> <tr> <td>404</td> <td>not_found</td> <td>No such key for this vendor</td> </tr> </tbody></table> </div><hr> <h2 id="legacy-content-import">Legacy Content Import<a class="anchor" href="#legacy-content-import" aria-label="Permalink">#</a></h2> <h3 id="post-vendorsvendorslugimportlegacy-content">POST /vendors/{vendorSlug}/import/legacy-content<a class="anchor" href="#post-vendorsvendorslugimportlegacy-content" aria-label="Permalink">#</a></h3> <p>One-time (per vendor, safely re-runnable) migration path for onboarding a vendor's existing content — home banners, offers, FAQs, the points program, eGift artwork and similar — from an outgoing platform's export format into the CMS's own spaces and blocks. Idempotent: re-running the same import updates the same CMS space(s) rather than creating duplicates, and a space that was renamed after import is still found on re-run and is never renamed back.</p> <p><strong>Auth:</strong> <code>content:write</code> scope, or dashboard JWT — non-viewer. <code>vendorSlug</code> must match the authenticated vendor.</p> <p><strong>Path parameters:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>vendorSlug</code></td> <td>string</td> <td>Must match the authenticated vendor.</td> </tr> </tbody></table> </div><p><strong>Request body:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>groups</code></td> <td>object (<code>{ <group name>: LegacyExportRecord[] }</code>)</td> <td>Yes</td> <td>The export, grouped by legacy content type. Each record needs at least a numeric <code>home_id</code>; the rest of the shape is intentionally permissive — it mirrors whatever the outgoing export produced.</td> </tr> <tr> <td><code>merchant_id</code></td> <td>string or number</td> <td>No</td> <td>Recorded on the activity-log entry when not a dry run.</td> </tr> <tr> <td><code>dry_run</code></td> <td>boolean</td> <td>No</td> <td><strong>Default <code>true</code>.</strong> Only an explicit <code>false</code> writes anything — matches the companion CLI's dry-run-unless-<code>--apply</code> default. A dry run returns the same report shape, with nothing persisted.</td> </tr> <tr> <td><code>options.space_prefix</code></td> <td>string</td> <td>No</td> <td>Prepended to every space slug this import would create.</td> </tr> <tr> <td><code>options.publish</code></td> <td>boolean</td> <td>No</td> <td>Opt-in: publish each written/updated space immediately instead of leaving it in its current workflow status.</td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/vendors/acme-cafe/import/legacy-content \ -H "X-API-Key: sck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "groups": { "faqs": [ { "home_id": 501, "primary_content": "Do you offer refunds?", "secondary_content": "Yes, within 14 days." } ] }, "dry_run": true }'</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "dry_run": true, "spaces": [ { "slug": "app-faqs", "group": "faqs", "action": "reused", "unknown_group": false, "blocks": [ { "block_type": "faq", "action": "updated", "home_ids": [501], "warnings": [] } ], "published": false, "would_publish": false } ], "media": { "uploaded": 0, "reused": 0, "failed": [] }, "skipped_items": [] }</code></pre> <p>An item that the legacy system itself would have skipped (an empty title or image, matching the outgoing platform's own display rule) is reported in <code>skipped_items</code>, not silently dropped without a trace. A group this importer has no specific mapping for still imports — as an opaque <code>custom_json</code> block — and is flagged with <code>unknown_group: true</code> so an operator notices.</p> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>bad_request</td> <td><code>groups</code> missing/malformed, or an item is missing its numeric <code>home_id</code></td> </tr> <tr> <td>403</td> <td>forbidden</td> <td>Caller is a viewer, or <code>vendorSlug</code> doesn't match the authenticated vendor</td> </tr> <tr> <td>500</td> <td>import_failed</td> <td>The import failed unexpectedly (partial writes are possible on a mid-import failure; safe to re-run)</td> </tr> </tbody></table> </div><hr> <h2 id="vendor-authentication-dashboard-login-flow">Vendor Authentication (dashboard login flow)<a class="anchor" href="#vendor-authentication-dashboard-login-flow" aria-label="Permalink">#</a></h2> <p>These are how a <strong>human dashboard user</strong> obtains the JWT used above — not something a server integration calls routinely.</p> <h3 id="post-authlogin">POST /auth/login<a class="anchor" href="#post-authlogin" aria-label="Permalink">#</a></h3> <p>Authenticate against the Spoonity Identity Server. A single-vendor user gets a token immediately; a multi-vendor user gets a short-lived <code>selection_token</code> for <code>/auth/select-vendor</code>. Rate-limited to 10 requests/min/IP.</p> <p><strong>Auth:</strong> None.</p> <p><strong>Request body:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Required</th> </tr> </thead> <tbody><tr> <td><code>email</code></td> <td>string</td> <td>Yes</td> </tr> <tr> <td><code>password</code></td> <td>string</td> <td>Yes</td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "admin@acme-cafe.com", "password": "REDACTED" }'</code></pre> <p><strong>Response example (single vendor):</strong></p> <pre><code class="language-json">{ "success": true, "requires_vendor_selection": false, "token": "eyJhbGciOiJIUzI1NiJ9...", "vendor": { "id": 7, "spoonity_vendor_id": "v_9001", "name": "Acme Cafe", "slug": "acme-cafe" }, "user": { "email": "admin@acme-cafe.com" }, "identities": [ { "id": "v_9001", "name": "Acme Cafe" } ] }</code></pre> <p><strong>Response example (multi-vendor):</strong></p> <pre><code class="language-json">{ "success": true, "requires_vendor_selection": true, "selection_token": "eyJhbGciOiJIUzI1NiJ9...", "identities": [ { "id": "v_9001", "name": "Acme Cafe" }, { "id": "v_9002", "name": "Acme Bakery" } ] }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>bad_request</td> <td><code>email</code>/<code>password</code> missing</td> </tr> <tr> <td>401</td> <td>unauthorized</td> <td>Invalid credentials</td> </tr> <tr> <td>403</td> <td>forbidden</td> <td>Email domain not allowlisted, the identity server would not list the account's vendors, the account is linked to no vendors, or the single vendor's scoped session was refused</td> </tr> <tr> <td>500</td> <td>internal</td> <td>The identity server could not be reached</td> </tr> </tbody></table> </div><h3 id="post-authselect-vendor">POST /auth/select-vendor<a class="anchor" href="#post-authselect-vendor" aria-label="Permalink">#</a></h3> <p>Second leg of a multi-vendor login. Send the <code>selection_token</code> from <code>/auth/login</code> with the chosen <code>vendor_id</code> (an <code>email</code>+<code>password</code> fallback is supported for legacy clients). Rate-limited to 10 requests/min/IP.</p> <p><strong>Auth:</strong> None (the <code>selection_token</code> itself is the credential).</p> <p><strong>Request body:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead> <tbody><tr> <td><code>vendor_id</code></td> <td>string</td> <td>Yes</td> <td>The Spoonity vendor id. A CMS slug is not accepted.</td> </tr> <tr> <td><code>selection_token</code></td> <td>string</td> <td>No*</td> <td>*Or <code>email</code>+<code>password</code>.</td> </tr> <tr> <td><code>email</code>, <code>password</code></td> <td>string</td> <td>No</td> <td>Legacy alternative.</td> </tr> <tr> <td><code>vendor_name</code></td> <td>string</td> <td>No</td> <td>Used when auto-provisioning a new vendor.</td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/auth/select-vendor \ -H "Content-Type: application/json" \ -d '{ "selection_token": "eyJhbGciOiJIUzI1NiJ9...", "vendor_id": "v_9002" }'</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "token": "eyJhbGciOiJIUzI1NiJ9...", "vendor": { "id": 8, "spoonity_vendor_id": "v_9002", "name": "Acme Bakery", "slug": "acme-bakery", "logo_url": null, "brand_color": null }, "user": { "email": "admin@acme-cafe.com", "id": "admin@acme-cafe.com", "role": "admin" } }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>bad_request</td> <td><code>vendor_id</code> missing, or neither <code>selection_token</code> nor credentials supplied</td> </tr> <tr> <td>401</td> <td>unauthorized</td> <td>The <code>selection_token</code> is invalid or expired</td> </tr> <tr> <td>403</td> <td>forbidden</td> <td>Email domain not allowlisted, the vendor isn't one of the caller's identities, or (legacy <code>email</code>+<code>password</code> path) the identity server refused the credentials for that vendor</td> </tr> <tr> <td>500</td> <td>internal</td> <td>The identity server could not be reached</td> </tr> </tbody></table> </div><h3 id="post-authswitch-vendor">POST /auth/switch-vendor<a class="anchor" href="#post-authswitch-vendor" aria-label="Permalink">#</a></h3> <p>Re-issue a JWT scoped to another vendor already authorized at login (<code>allowedVendors</code> on the current token) — no credentials needed. Auto-provisions the vendor's CMS row on first switch.</p> <p><strong>Auth:</strong> Dashboard JWT. The route runs <code>requireAuth</code> only, so an API key or service token is authenticated too, but it carries no <code>allowedVendors</code> and gets the <code>403</code>.</p> <p><strong>Request body:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Required</th> </tr> </thead> <tbody><tr> <td><code>vendor_id</code></td> <td>string</td> <td>Yes</td> </tr> <tr> <td><code>vendor_name</code></td> <td>string</td> <td>No</td> </tr> </tbody></table> </div><p><strong>Request example:</strong></p> <pre><code class="language-bash">curl -X POST https://cms.spoonity.com/api/v1/auth/switch-vendor \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \ -H "Content-Type: application/json" \ -d '{ "vendor_id": "v_9002" }'</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "token": "eyJhbGciOiJIUzI1NiJ9...", "vendor": { "id": 8, "spoonity_vendor_id": "v_9002", "name": "Acme Bakery", "slug": "acme-bakery", "logo_url": null, "brand_color": null }, "user": { "email": "admin@acme-cafe.com", "id": "admin@acme-cafe.com", "role": "admin" } }</code></pre> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>400</td> <td>bad_request</td> <td><code>vendor_id</code> missing</td> </tr> <tr> <td>403</td> <td>forbidden</td> <td>Vendor is not in the token's <code>allowedVendors</code></td> </tr> <tr> <td>404</td> <td>not_found</td> <td>Vendor could not be resolved</td> </tr> </tbody></table> </div><h3 id="get-authme">GET /auth/me<a class="anchor" href="#get-authme" aria-label="Permalink">#</a></h3> <p>Current user + vendor info from the presented credential.</p> <p><strong>Auth:</strong> Dashboard JWT, API key or service token. Not scope-gated.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/api/v1/auth/me \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "user": { "email": "admin@acme-cafe.com", "id": "admin@acme-cafe.com" }, "vendor": { "id": 7, "spoonity_vendor_id": "v_9001", "name": "Acme Cafe", "slug": "acme-cafe", "logo_url": null, "brand_color": "#38bdf8" } }</code></pre> <p><strong>Errors:</strong> none beyond auth.</p> <h3 id="development-only-post-authdev-login">Development-only: POST /auth/dev-login<a class="anchor" href="#development-only-post-authdev-login" aria-label="Permalink">#</a></h3> <p>The route source also defines <code>POST /auth/dev-login</code>, a credential-free login that auto-provisions a demo vendor. It is gated on <code>config.isDev</code> and returns a plain <code>404 not_found</code> whenever the service is not running in development mode — <strong>it is never reachable in production</strong> and is not part of the public API surface (the upstream <code>openapi.yaml</code> deliberately excludes it too). It is documented here only so its existence is not a surprise when reading route source.</p> <hr> <h2 id="health-and-discovery">Health and discovery<a class="anchor" href="#health-and-discovery" aria-label="Permalink">#</a></h2> <p>These routes sit outside <code>/api/v1</code>, so they are not in the OpenAPI spec. They are public, need no credentials, and are not rate limited.</p> <h3 id="get-health">GET /health<a class="anchor" href="#get-health" aria-label="Permalink">#</a></h3> <p>Liveness and readiness in one document. The deploy workflow gates on this returning <code>200</code>.</p> <p><strong>Auth:</strong> None.</p> <p><strong>Request example:</strong></p> <pre><code class="language-bash">curl https://cms.spoonity.com/health</code></pre> <p><strong>Response example:</strong></p> <pre><code class="language-json">{ "status": "healthy", "service": "spoonity-cms", "timestamp": "2026-09-30T10:40:33.607Z", "uptime_seconds": 140742, "version": "1.2.0", "checks": { "database": "ok" } }</code></pre> <p><code>status</code> is <code>healthy</code> (<code>200</code>), <code>starting</code> (<code>503</code>: the process is listening but has never reached the database; it retries on its own, and the body may add a <code>detail</code> string) or <code>degraded</code> (<code>503</code>: the database was reachable and is not any more; delivery serves last-good content and tracking drops events).</p> <p><strong>Errors:</strong></p> <div class="scroll-box"><table> <thead> <tr> <th>Status</th> <th>Code</th> <th>Meaning</th> </tr> </thead> <tbody><tr> <td>503</td> <td>(status <code>starting</code> or <code>degraded</code>)</td> <td>The database is not reachable. The body has the same shape as the <code>200</code>.</td> </tr> </tbody></table> </div><h3 id="get-docsopenapiyaml">GET /docs/openapi.yaml<a class="anchor" href="#get-docsopenapiyaml" aria-label="Permalink">#</a></h3> <p>The CMS repository's own OpenAPI file, served as-is. It lags the route source: it lacks 15 of the operations documented here (the item-level translation routes, app config, brand, lookups, the Links helper routes and the legacy import). Prefer the maintained copy at <a href="/docs/openapi/cms.yaml">openapi/cms.yaml</a>.</p> <p><strong>Auth:</strong> None.</p> <pre><code class="language-bash">curl https://cms.spoonity.com/docs/openapi.yaml</code></pre> <h3 id="get-docsguides">GET /docs/guides<a class="anchor" href="#get-docsguides" aria-label="Permalink">#</a></h3> <p>HTML index of the CMS developer guides; <code>GET /docs/guides/{slug}</code> renders one guide, and an unknown slug is an HTML <code>404</code>.</p> <p><strong>Auth:</strong> None.</p> <pre><code class="language-bash">curl https://cms.spoonity.com/docs/guides</code></pre> <footer class="page"> Machine-readable copies of this page: <a href="/docs/cms.md">/docs/cms.md</a><a href="/llms.txt">/llms.txt</a> </footer> </main> </div> </body> </html>