Banners API

The banners API returns active in-app banners for your mobile app. The SDKs call this endpoint automatically, but you can also call it directly for custom integrations. Free-tier Appspaces are limited to 1 banner.

Note

This endpoint returns banners for in-app display (mobile SDKs). For website smart banners (the banner.js script), the SDK uses the domain-resolved GET /api/banner/config endpoint instead, which does not require an API key.

List active banners

GET /v1/api/banners

Auth: Any valid API key (publishable or secret)

Query parameters:

Param	Description
label	Filter banners by label tag (e.g. summer-promo)
user_id	If provided, enables segment-targeted banner filtering

Response 200:

{
  "banners": [
    {
      "id": "banner_id",
      "label": "summer-promo",
      "title": "Flash Sale!",
      "body": "50% off all items this weekend",
      "action_url": "https://myapp.com/sale",
      "background_color": "#ff6600",
      "text_color": "#ffffff",
      "cta_text": "Shop Now",
      "position": "top",
      "dismiss_days": 3,
      "priority": 5
    }
  ]
}

Response fields

Field	Type	Description
id	string	Unique banner ID
label	string	Label tag for filtering
title	string	Banner headline
body	string	Banner body text
action_url	string	URL opened when the user taps the CTA
background_color	string	Hex color for the banner background
text_color	string	Hex color for the banner text
cta_text	string	Call-to-action button text
position	string	Display position (top or bottom)
dismiss_days	number	Number of days the banner stays dismissed after the user closes it
priority	number	Priority ranking (higher numbers display first)

Segment targeting

Banners can be targeted to specific audience segments. When a banner has a segment assigned:

• If user_id is provided and the user is in the segment, the banner is included.
• If user_id is not provided or the user is not in the segment, the banner is silently excluded.
• Banners with no segment assigned are shown to all users.

A/B testing

When multiple banners are part of an active A/B test, only the deterministically selected variant is returned. The variant is chosen based on a hash of the visitor’s IP address and User-Agent, ensuring the same visitor always sees the same variant.