API Reference

What you can do

You already published Maya's homepage hero to Production. The React SDK and <rulecms-widget> already call this GET for her. This page is when her app — a PHP host, a cache warmer, a test — fetches that snapshot itself.

Two everyday jobs:

• Pull the published hero from something that is not React. Send a Staging or Production token and the published key. Read data.widget.itemList. Render it however that host already renders cards.
• Prove the token and published key work before you wire a new host. One GET. A 200 with her name and itemList is the smoke test.

She builds with the ten built-in cards — Text, Image, Video, Icon, Button, Divider, Embed, List, Accordion, Custom — or a library she registered. Ask AI can compose. It cannot publish. This GET only returns what she already published.

A ruleset that chooses among published heroes is a different request. That is Resolve from your app, a POST. This page is the hard-coded get.

How it thinks

You send two query parameters: a token and a published key. The token names the team and environment. The published key names the snapshot. The widget must belong to that same team and environment. Mix them and the request fails.

This path returns the last published snapshot, not the live composer draft. Unpublished heads are not found. A Staging or Production token — no dev. prefix — plus a published key {environmentId}---widget-… loads from https://widget-cache.rulecms.com. That response is cached until she republishes.

Here is the case that surprises people. Maya pastes a draft widget-… key next to a Production token, or she sends widgetKey on this URL the way Development does. This GET wants publishedKey. Development is a different host, a different query name, and a dev. token. That runbook is Development Integration. Do not mix the samples.

The Default Widget is Production-only. Promote copies the draft to the next environment; it does not publish. Copy To is only for extra environments she named herself. See Widgets and Publishing.

Fetch Maya's published hero

You do this on the published widget page in Staging or Production. The tab is labeled Integration, not Integrate. If the hero still lives only in Development, promote the draft and publish first — then come back here.

1. Open the organization → team → project → environment where she published the hero. Staging is the QA stop. Production is the live site.
2. Open Maya's homepage hero — the published widget, not the composer.
3. Open the Integration tab.
4. Copy the PublishedKey. It looks like {environmentId}---widget-….
5. Copy (or create) an enabled client token for that same environment. It must not start with dev.. Tokens live on that tab and on Projects, Environments & Tokens.
6. GET the snapshot. Query names are token and publishedKey. Look at data.widget.itemList. That is a safe stop.

curl "https://widget-cache.rulecms.com/api/v1/c/widget/get?token=YOUR_STAGING_OR_PRODUCTION_TOKEN&publishedKey=ENVIRONMENT_ID---widget-…"

The same request as fetch:

const res = await fetch(
  "https://widget-cache.rulecms.com/api/v1/c/widget/get?" +
    new URLSearchParams({
      token: process.env.RULECMS_TOKEN,
      publishedKey: process.env.HERO_PUBLISHED_KEY,
    })
);
const body = await res.json();
const itemList = body.data.widget.itemList;

A 200 looks like this. The rows in itemList are the cards she dropped.

{
  "success": true,
  "data": {
    "widget": {
      "publishedKey": "{environmentId}---widget-…",
      "name": "Homepage hero",
      "version": "1.0.0",
      "environmentName": "Production",
      "itemList": { "rows": [ … ] },
      "lastPublishedAt": "…"
    },
    "childCollections": { }
  }
}

childCollections, the CSS catalogs, published-key formats, and what a non-200 usually means live on Response and published keys.

What to read next

This page is the story and the first GET. The rest of the 200, drafts, and the other hosts live on the pages below.

• Response and published keys — data.widget, childCollections, CSS catalog fields, env---widget versus embedded ___ keys, and the error table.
• Development Integration — The draft GET. Same response fields; a dev. token, widgetKey, and https://rulecms.com.
• HTML Custom Element Embed — The same GET, rendered by <rulecms-widget>.
• Resolve from your app — POST a ruleset instead of hard-coding this published key.
• Publishing — How the hero became the snapshot this GET returns.
• Projects, Environments & Tokens — Copy the token. Pair a Staging or Production token with the published key.

How this fits

This GET does not replace the React SDK or the HTML embed. Those clients already call it. This page is when Maya fetches the snapshot herself. Widgets is how she creates the hero. Publishing is how the site gets a snapshot. Tokens live on Projects, Environments & Tokens.

The Default Widget is in Production. She published this hero. Promote copies the draft; it does not publish. When she wants the live draft instead, Development Integration is the Integrate tab. A browser preview on RuleCMS itself is /render?publishedKey=…&appToken=…. Use it to glance at the snapshot. Build on this GET, the SDK, or the HTML embed.