Author and publish a hosted storefront

Read the current site

GET /v1/my/site is one honest read: the active manifest, the latest draft (the newest version the active pointer does not reference, null when the newest version is already live), and the full version history.

curl "https://api.ruo.pro/v1/my/site" -H "Authorization: Bearer fdk_your_key_here"
# -> { "active": { "version": 1, ... }, "draft": null, "versions": [ ... ] }

Author the manifest as data

The manifest names the blocks the renderer relies on — store, brand, theme, template.sections, seo, behavior — and preserves any extra properties verbatim. Each section is a registry type plus an open props bag:

{
  "brand": { "name": "Nova Peptide" },
  "theme": { "tokens": { "color.brand": "#0b6" } },
  "template": {
    "id": "base-v1",
    "sections": [
      { "type": "announcement-bar", "props": { "text": "Free shipping over $150" } },
      { "type": "header-nav", "props": {} },
      { "type": "epic-hero", "props": { "heading": "Research-grade peptides" } },
      { "type": "product-grid", "props": { "collection": "peptides" } },
      { "type": "legal-footer", "props": {} }
    ]
  }
}

See The manifest and sections for the block reference and Theming for how theme tokens map to CSS custom properties.

Save a draft

PUT /v1/my/site/draft writes a new version row without moving the active pointer, so nothing a visitor sees changes yet. It returns the version it minted:

curl -X PUT "https://api.ruo.pro/v1/my/site/draft" \
  -H "Authorization: Bearer fdk_your_key_here" \
  -H "content-type: application/json" \
  -d '{ "manifest": { "brand": { "name": "Nova Peptide" }, "template": { "sections": [] } } }'

{ "version": 2, "rowHash": "…" }

The draft save is where the RUO-claims guardrail scan runs. The scanner walks every string in the manifest tree for prohibited claim language and is fail-closed: a scanner error is a 503 (“scan did not run”), never a silent pass. A CRITICAL finding is a hard 422 and no version row is written — there is no merchant override.

The finding body names exactly what tripped the scan — one entry per finding with { path, term, rule, severity, context }.

Preview the draft

POST /v1/my/site/preview-token mints a short-lived signed token for one version. Nothing is written to the database — the expiry rides in the signed payload, and the token grants a render of exactly that immutable version:

curl -X POST "https://api.ruo.pro/v1/my/site/preview-token" \
  -H "Authorization: Bearer fdk_your_key_here" \
  -H "content-type: application/json" \
  -d '{ "version": 2 }'

{ "token": "…", "version": 2, "expiresAt": "2026-09-14T12:30:00.000Z" }

The renderer resolves it through the public GET /v1/preview-resolve?token=<token> route (served with Cache-Control: no-store). Expired, tampered, malformed, or unknown-version tokens all resolve to the same 404 invalid_preview_token — one code, no oracle, and no cross-tenant preview.

Publish

POST /v1/my/site/publish moves the active pointer to a version. Publishing does not re-scan — every version already passed the guardrail scan on its write:

curl -X POST "https://api.ruo.pro/v1/my/site/publish" \
  -H "Authorization: Bearer fdk_your_key_here" \
  -H "content-type: application/json" \
  -d '{ "version": 2 }'

{ "version": 2, "rowHash": "…" }

An unknown version is a 404 version_not_found. The moment this returns, the public read GET /v1/tenants/nova-peptide/site serves the new active manifest.

Roll back

Because any existing version can be published, rollback is the same route — re-publish the earlier version ({ "version": 1 }). The version table is append-only, so a rollback never destroys the version you rolled away from; publish it again to roll forward.