Home banner

​

Endpoints

​

GET /v1/web/home-banner

{
  "ok": true,
  "data": {
    "banner": {
      "id": "cmf6b1c2d0001qz8h3e4f5g6h",
      "studioId": "cmstudio0001qz8h7w8x9y0z",
      "isPublished": true,
      "source": "custom",
      "contentItemId": null,
      "title": "October challenge",
      "description": "Log five workouts this week.",
      "mediaKind": "image",
      "mediaUrl": "https://media.example.com/banners/october.jpg",
      "mediaThumbnailUrl": null,
      "textAlign": "start",
      "ctaKind": "link",
      "ctaLabel": "Read more",
      "ctaUrl": "https://example.com/challenge",
      "ctaColor": "brand",
      "ctaIcon": "article",
      "createdAt": "2026-09-28T07:00:00.000Z",
      "updatedAt": "2026-10-01T09:30:00.000Z",
      "contentItem": null
    }
  }
}

​

PATCH /v1/web/home-banner

​

Cross-field rules

​

Transform before save

• Empty strings in title, description, mediaUrl, mediaThumbnailUrl and ctaLabel become null.
• ctaUrl gets https:// prefixed when it does not contain ://.
• When source is content, the fields title, description, mediaKind, mediaUrl and mediaThumbnailUrl are forced to null. The banner stores nothing of its own and reads from the content item.

​

Service

{
  "ok": true,
  "data": {
    "banner": {
      "id": "cmf6b1c2d0001qz8h3e4f5g6h",
      "studioId": "cmstudio0001qz8h7w8x9y0z",
      "isPublished": true,
      "source": "content",
      "contentItemId": "cmcontent001qz8h1a2b3c4d",
      "title": null,
      "description": null,
      "mediaKind": null,
      "mediaUrl": null,
      "mediaThumbnailUrl": null,
      "textAlign": "center",
      "ctaKind": "content",
      "ctaLabel": "Watch",
      "ctaUrl": null,
      "ctaColor": "white",
      "ctaIcon": "play",
      "createdAt": "2026-09-28T07:00:00.000Z",
      "updatedAt": "2026-10-06T12:00:00.000Z",
      "contentItem": {
        "id": "cmcontent001qz8h1a2b3c4d",
        "type": "video",
        "title": "Warm-up routine",
        "description": "Ten minutes before every session.",
        "mediaKind": "video",
        "mediaUrl": "https://media.example.com/content/warmup.mp4",
        "thumbnailUrl": "https://media.example.com/content/warmup.jpg",
        "isPublished": true
      }
    }
  }
}

​

What counts as a playable video

• source is not content.
• mediaKind is video or youtube.
• The URL matches one of two patterns: a video file ending in .mp4, .m4v, .mov, .qt, .webm, .mkv or .m3u8 (optionally followed by a query string), or a YouTube or Vimeo page that carries a real video id (youtube.com/watch?v=, /shorts/, /embed/, /live/, /v/, youtu.be/, vimeo.com/ with at least six digits).

​

How the trainee app receives the banner

• There is no banner, or isPublished is false.
• source is content and the linked item is missing or has no title.
• source is custom and title is empty.

type TraineeBanner = {
  id: string;
  title: string;
  description: string | null;
  mediaKind: 'image' | 'video' | 'youtube' | 'none' | null;
  mediaUrl: string | null;
  mediaVideoUrl: string | null;
  textAlign: 'start' | 'center' | 'end';
  cta: {
    kind: 'content' | 'whatsapp' | 'link';
    label: string | null;
    contentItemId: string | null;
    url: string | null;
    color: 'brand' | 'white' | 'green' | 'yellow' | 'glass';
    icon: string;
  } | null;
};

• Content banner. title and description come from the item. Media is thumbnailUrl when present, otherwise the item’s mediaUrl. With a thumbnail, mediaKind is image. Without one, it is the item’s own kind, falling back to image for an unknown value. mediaVideoUrl is always null, because the button already opens the content item screen, which has its own player.
• Custom banner with image or YouTube media. mediaUrl and mediaKind pass through. A stored mediaKind that is not image, video or youtube (including none) is read as image.
• Custom banner with video media. mediaUrl is only ever drawn as a still, so it is replaced by mediaThumbnailUrl. With no thumbnail, both mediaUrl and mediaKind become null and the card renders as text only. mediaVideoUrl still carries the playable URL so the button can open the player.
• Button. ctaKind: "none" gives cta: null. content with an item gives a button that opens that item. content with no item but a playable own video gives a button with contentItemId: null and url: null, and the app plays mediaVideoUrl. content with neither gives no button. link needs ctaUrl, otherwise no button. whatsapp always gives a button with no URL. ctaColor and ctaIcon fall back to brand and none when the stored value is not in the enum.