Skip to content
Arc XP

Card Images

Audience: Front-end developers and product owners rendering recommendation and Catch-Up cards.

Every card returned by Content Recommendations carries a thumbnail_url. This page explains what that image is, how fresh it is, and how it behaves when something is missing — so you can render it directly without building your own resizing or fallback logic.

Where card images come from

When you ingest a content item, you supply a source image as thumbnail_url on the content payload (see the content endpoint). Arc XP generates a single feed-card-sized derivative from that source image once, at ingest time. There is one derivative per content item, shared across every site and recommendation surface that renders the item.

The derivative is what you receive as card.thumbnail_url on recommendation responses and on the Catch-Up Card — no separate image call or hydration step is needed.

Derivative properties

  • Format: JPEG.
  • Size: fitted within 640×640 pixels, preserving the source image’s aspect ratio (the image is scaled down to fit the box; it is not cropped or padded to a fixed square).

Because the image arrives already resized, you generally do not need to resize it again in your design system before rendering it into a card.

Freshness

The derivative is regenerated only when the item’s source image URL changes. Re-publishing an item with the same thumbnail_url reuses the existing derivative, so change the source image URL when you need a new image to take effect.

Fallback behavior

card.thumbnail_url is safe to render directly — it always resolves to a usable image URL when the item has one:

  • When a derivative exists, card.thumbnail_url is the generated derivative.
  • When a derivative hasn’t been generated yet, or generation didn’t complete, card.thumbnail_url falls back to the original source image URL you supplied. Image generation never blocks or delays ingestion, so a newly published item is immediately renderable with its source image while its derivative is prepared.
  • card is null (and therefore has no image) only when no matching content document is found — for example, an editor-pinned item that hasn’t synced yet. Continue to render cards that degrade gracefully when card or an individual field is absent.