Messages API

The messages API lets you fetch in-app messages and render their content. The SDKs call these endpoints automatically to display messages in your app. Free-tier Appspaces are limited to 1 message.

List active messages

GET /v1/api/messages

Auth: Any valid API key (publishable or secret)

Query parameters:

Param	Description
`trigger`	Filter by trigger type (`manual`, `milestone`, `event`)
`user_id`	If provided, enables segment-targeted message filtering

Response 200:

{
  "messages": [
    {
      "id": "msg_id",
      "name": "Welcome Modal",
      "title": "Welcome to the app!",
      "body": "Here's how to get started",
      "trigger": "manual",
      "trigger_value": null,
      "content": { },
      "background_color": "#ffffff",
      "priority": 10,
      "dismiss_days": 7,
      "max_impressions": 3,
      "min_interval_hours": 24
    }
  ]
}

Response fields

Field	Type	Description
`id`	string	Unique message ID
`name`	string	Internal name for the message
`title`	string	Message headline
`body`	string	Message body text
`trigger`	string	When the message should appear (`manual`, `milestone`, `event`)
`trigger_value`	string or null	Event name for `event` triggers, or milestone name for `milestone` triggers
`content`	object or null	Puck editor content structure (null if no visual content)
`background_color`	string	Hex background color
`priority`	number	Priority ranking (higher numbers display first)
`dismiss_days`	number	Days the message stays dismissed after the user closes it
`max_impressions`	number	Maximum times the message can be shown to a single user
`min_interval_hours`	number	Minimum hours between impressions for the same user

Segment targeting and A/B testing work the same as the Banners API.

Generate a render token

Generate a short-lived token to render a message’s HTML content. Used by SDKs to load message content in a WebView without exposing the API key.

POST /v1/api/messages/:id/render-token

Auth: Any valid API key (publishable or secret)

URL parameters: :id is the message ID.

Request body: None

Response 200:

{ "token": "eyJhbGciOi..." }

The token is short-lived and should be used immediately.

Render message HTML

Return the rendered HTML for a message. This endpoint accepts either an API key or a render token.

GET /v1/api/messages/:id/render

Auth: One of:

X-API-Key or Authorization: Bearer header (any valid key)
?token=<render-token> query parameter (from the render-token endpoint)

URL parameters: :id is the message ID.

Response 200:

Content-Type: text/html; charset=utf-8
Cache-Control: public, max-age=300
Body: fully rendered HTML string

Errors:

Status	Error
`401`	`API key or render token required`
`401`	`Invalid or expired render token`
`404`	`Message not found`
`404`	`Message has no content`