Render a club's articles

This walkthrough builds a page that lists a club’s published articles and renders one of them, using a publishable content key from the browser. It assumes the content module is installed and you hold a key with your origin on its allowlist; see Authentication. Set up the values you need:

export API_BASE_URL=https://api.develop.fourdos.dev
export CONTENT_KEY=ck_live_…
export ORIGIN=https://www.yourclub.example
export PLATFORM_USER_ID=…  # the signed-in viewer, when the key has reader naming enabled

1. Fetch the list

curl "$API_BASE_URL/v1/content/articles?key=$CONTENT_KEY&limit=1" \
  -H "Origin: $ORIGIN"

200 OK:

{
  "articles": [
    {
      "id": "10000001-0000-7000-8000-000000000000",
      "slug": "match-report",
      "title": "Match report",
      "excerpt": "We won",
      "feature_image_url": null,
      "tags": ["match-report"],
      "author_name": null,
      "published_at": "2026-07-20T10:00:00.000Z",
      "updated_at": "2026-07-21T09:00:00.000Z",
      "format": "html",
      "html": "<p>We won.</p>"
    }
  ],
  "page_info": { "next_cursor": null, "has_more": false }
}

If you get a 403 here, the Origin you sent is not on the key’s allowlist. Browsers set that header themselves; curl does not, which is why the example sets it by hand. To evaluate the list for a member, add user_id to the URL. The key must have reader naming enabled; an absent, blank or unresolved reader gets the strictest answer for each gated article. One thing to fix in your head before you render any of this: html is the only field that arrives as HTML, and the only one sanitised for you. title, excerpt, author_name, feature_image_url and the block fields src, alt and caption are plain text an author typed. Every example below sets them through the DOM (textContent, img.alt = …) rather than pasting them into a template string, because an author writing Kane's "winner" in an alt box is enough to break markup built that way, and an author who means harm can do worse than break it.

2. Fetch one article

The list already contains every article’s body, so a news index needs one request. Fetch a single article when you are rendering its own page, from a route like /news/match-report:

curl "$API_BASE_URL/v1/content/articles/match-report?key=$CONTENT_KEY&user_id=$PLATFORM_USER_ID" \
  -H "Origin: $ORIGIN"

The response is the article object on its own, with no articles wrapper. Send user_id here too, and send the same one the list carried. This endpoint evaluates the gate the same way the list does, so a call that names no reader gets the strictest answer and a gated article comes back as a 403 for everyone. Leave the parameter out only when nobody is signed in.

3. Render the index in a page

Everything below runs in the browser. The key is publishable, so it belongs in this code.

<div id="news"></div>

<script type="module">
  const API = "https://api.develop.fourdos.dev";
  const KEY = "ck_live_…"; // publishable: the origin allowlist is the control
  const READER_USER_ID = null; // Set to the current viewer's platform user id when enabled

  const listUrl = new URL(`${API}/v1/content/articles`);

  listUrl.searchParams.set("key", KEY);
  listUrl.searchParams.set("limit", "10");
  if (READER_USER_ID !== null) listUrl.searchParams.set("user_id", READER_USER_ID);

  const response = await fetch(listUrl);
  if (!response.ok) {
    const { error } = await response.json();
    throw new Error(`${error.code}: ${error.message}`);
  }
  const { articles } = await response.json();

  const news = document.getElementById("news");

  for (const article of articles) {
    const item = document.createElement("article");

    if (article.locked === true) {
      const lock = document.createElement("p");
      lock.className = "lock";
      lock.textContent = `Requires ${article.required_tier} or higher.`;

      if (article.member_tier !== null) {
        lock.textContent += ` You are on ${article.member_tier}, ${article.xp_gap} XP away.`;
      } else {
        lock.textContent += ` ${article.xp_gap} XP away.`;
      }
      if (article.unlocks_at !== null) {
        lock.textContent += ` Opens to everyone on ${new Date(article.unlocks_at).toLocaleDateString()}.`;
      }
      item.append(lock);
      news.append(item);
      continue;
    }

    if (article.feature_image_url !== null) {
      const image = document.createElement("img");
      image.src = article.feature_image_url;
      image.alt = "";
      item.append(image);
    }

    const link = document.createElement("a");
    link.href = `/news/${encodeURIComponent(article.slug)}`;
    link.textContent = article.title;
    const heading = document.createElement("h2");
    heading.append(link);
    item.append(heading);

    const meta = document.createElement("p");
    meta.className = "meta";
    const time = document.createElement("time");
    time.dateTime = article.published_at;
    time.textContent = new Date(article.published_at).toLocaleDateString();
    meta.append(time);
    if (article.author_name !== null) meta.append(` by ${article.author_name}`);
    item.append(meta);

    if (article.excerpt !== null) {
      const excerpt = document.createElement("p");
      excerpt.textContent = article.excerpt;
      item.append(excerpt);
    }

    news.append(item);
  }
</script>

The locked branch renders the lock from the list response itself. The required tier name, reader’s tier name, XP gap and unlock moment are all on that row, so the index needs no second call to fill in the lock. excerpt, feature_image_url and author_name are each nullable, which is why every one of them is guarded above. Setting textContent and image.src assigns a value to a property; nothing in it is ever parsed as markup, so there is no escaping to remember and no way for a stray quote in a title to close an attribute. append with a string adds a text node, so the byline is safe the same way.

4. Render an article body

The default html format is one string, already rendered and sanitised at publish, so it is the one field you hand to innerHTML. The title beside it is not, so it goes in as text:

<article id="article">
  <h1></h1>
  <div class="body"></div>
</article>

<script type="module">
  const articleUrl = new URL(`${API}/v1/content/articles/${encodeURIComponent(slug)}`);

  articleUrl.searchParams.set("key", KEY);
  if (READER_USER_ID !== null) articleUrl.searchParams.set("user_id", READER_USER_ID);

  const response = await fetch(articleUrl);
  const payload = await response.json();

  if (!response.ok) {
    const { error } = payload;
    if (error.code !== "CONTENT_TIER_LOCKED") {
      throw new Error(`${error.code}: ${error.message}`);
    }
    const lock = document.createElement("p");
    lock.textContent = `Requires ${error.details.requiredTier} or higher. ${error.details.xpGap} XP away.`;

    document.querySelector("#article .body").replaceChildren(lock);
  } else {
    const article = payload;
    document.querySelector("#article h1").textContent = article.title;

    document.querySelector("#article .body").innerHTML = article.html;
  }
</script>

The reader goes on this URL as well. Without it the gate resolves no member, and a gated article refuses even for a member who is entitled to read it, so the locked branch would paint a lock over a page that should have opened. That renders the whole body except a video. A video embed arrives as an empty <div data-block="video-embed" data-src="…" data-provider="…">, never an <iframe>, so a browser shows nothing where it sits. If the club publishes video, take the block format below, or swap those elements for your own player after the line that sets innerHTML. Articles has the element and the swap.

5. Or render your own media components

Ask for ?format=blocks when you want your own image and video components instead of our markup. Text blocks still arrive as HTML fragments, so only the two media arms are yours to write:

const blocksUrl = new URL(`${API}/v1/content/articles/${encodeURIComponent(slug)}`);

blocksUrl.searchParams.set("key", KEY);
blocksUrl.searchParams.set("format", "blocks");
if (READER_USER_ID !== null) blocksUrl.searchParams.set("user_id", READER_USER_ID);

const response = await fetch(blocksUrl);
const article = await response.json();
if (!response.ok) {
  // A gated article refuses here the same way it does above; handle
  // CONTENT_TIER_LOCKED before you read article.blocks.
  throw new Error(`${article.error.code}: ${article.error.message}`);
}

const body = document.querySelector("#article .body");
body.replaceChildren();

for (const block of article.blocks) {
  switch (block.type) {
    case "image": {
      if (block.src === null) break;
      const figure = document.createElement("figure");
      const image = document.createElement("img");
      image.src = myCdn(block.src);
      image.alt = block.alt; // plain text, and never parsed as markup here
      image.loading = "lazy";
      figure.append(image);
      if (block.caption !== null) {
        const caption = document.createElement("figcaption");
        caption.textContent = block.caption;
        figure.append(caption);
      }
      body.append(figure);
      break;
    }
    case "video_embed":
      // myPlayer returns an element; build it from block.provider and block.src.
      if (block.src !== null) body.append(myPlayer(block.provider, block.src));
      break;
    case "divider":
      body.append(document.createElement("hr"));
      break;
    default: {
      // Text blocks carry a sanitised fragment; an unknown future type carries none.
      if (typeof block.html !== "string") break;
      const holder = document.createElement("div");
      holder.innerHTML = block.html;
      body.append(...holder.childNodes);
    }
  }
}

block.html is the only value here that goes anywhere near innerHTML, and it is the only one sanitised at publish. alt and caption are the author’s own text, which is why they are set as properties instead. Every block type and its fields are on Block format, including how to read a video id out of block.src for your own player.

6. Page through the archive

An archive page follows next_cursor until has_more is false. Pass the cursor back exactly as you received it, and pass the same filters on every request:

async function everyArticle() {
  const all = [];
  let cursor = null;

  do {
    const url = new URL(`${API}/v1/content/articles`);
    url.searchParams.set("key", KEY);
    url.searchParams.set("limit", "50"); // 50 is the maximum
    if (cursor !== null) url.searchParams.set("cursor", cursor);

    const page = await (await fetch(url)).json();
    all.push(...page.articles);
    cursor = page.page_info.has_more ? page.page_info.next_cursor : null;
  } while (cursor !== null);

  return all;
}

The loop stops on has_more, not on how many articles came back. A page can hold fewer than limit (an article that cannot be served is dropped rather than failing the page), so stopping on a short page would silently cut the archive off there. Each article carries a whole rendered body, so a page of 50 is a large response. Prefer the default limit of 10 for anything a reader waits on, and save the full walk for a build step.

7. A featured article and a tag filter

A homepage usually wants one article pinned to the top and a section index wants one tag:

// Newest first, with the cup final preview hoisted above them
`${API}/v1/content/articles?key=${KEY}&pinned=cup-final-preview`

// Match reports only
`${API}/v1/content/articles?key=${KEY}&tag=match-report`

The pinned article is returned in addition to limit and is removed from its natural position, so it appears exactly once. If you page beyond the first page, pass pinned on every request or it appears a second time. A pinned slug that names nothing published is ignored and the page is served normally, so a homepage does not break when the featured article is unpublished.

8. Report the read

The page now renders an article. One more call tells the platform that a member read it, which raises that member’s affinity for the tags the article carries and puts the article on the club’s analytics screen:

<script type="module">
  import { createEngagementClient } from "engagement-sdk";

  const engage = createEngagementClient({
    key: "ek_live_…",  // the tracking key, NOT the content key above
    endpoint: API
  });

  // After the article is on screen, and only when you know who is reading:
  if (viewer.platformUserId) {
    engage.reportInteraction({
      action: "content.read",       // or content.shared, content.liked
      id: article.id,               // the article's id, not its slug
      userId: viewer.platformUserId
    });
  }
</script>

Four things about that call:

It takes the other key. Reading articles uses a content key (ck_live_…); reporting an interaction rides the engagement rail and uses a publishable tracking key (ek_live_…). Both are publishable, and neither works in the other’s place.
It takes the id, not the slug. article.id is in every response above.
It takes no tags, and offers no way to send any. The server reads them off the article, so the affinity a read raises is for the tags your marketer chose in the editor.
It needs a signed-in reader. userId is the reader’s platform user id. There is no anonymous path, so a logged-out visitor is not counted. Passing an empty string is safe: the call is dropped without a request, and it is dropped even when you have called identify(), so a read after the reader signs out is never filed under the reader who signed in before.

reportInteraction never throws into your page and never blocks the render. A failed report is reported through the client’s onError callback and nowhere else, and a read made as the reader leaves goes out with navigator.sendBeacon rather than being lost. A refresh does not inflate anything: a read counts once per member, per article, per day, and a repeat of a report that is still in flight (an effect firing on every render, say) is dropped rather than sent. If reads for one article stay at zero while others climb, check that the article has tags. An article published without any cannot produce an interaction event at all, and the call answers content_untagged. The engagement SDK reference has every refusal reason and the delivery table. Interactions never earn XP.

Caching

Responses without user_id carry Cache-Control: private, max-age=60, so an anonymous browser can reuse them for a minute. A request with user_id carries Cache-Control: no-store, even when the key does not opt in or the reader does not resolve. It is deliberately not public: the key is in the URL, and revoking a key has to take effect at once. If you want a shared cache, call these endpoints from your backend or build step and cache the result under your own rules.

Where to go next

Articles for every parameter and every error response.
Block format for the ?format=blocks shape.
Engagement SDK for reporting reads, shares and likes.

Get started

Concepts

Walkthroughs

Content API

SDK

1. Fetch the list

2. Fetch one article

3. Render the index in a page

4. Render an article body

5. Or render your own media components

6. Page through the archive

7. A featured article and a tag filter

8. Report the read

Caching

Where to go next

​1. Fetch the list

​2. Fetch one article

​3. Render the index in a page

​4. Render an article body

​5. Or render your own media components

​6. Page through the archive

​7. A featured article and a tag filter

​8. Report the read

​Caching

​Where to go next

1. Fetch the list

2. Fetch one article

3. Render the index in a page

4. Render an article body

5. Or render your own media components

6. Page through the archive

7. A featured article and a tag filter

8. Report the read

Caching

Where to go next