InApp
Operations
List in-app messages
Lists the App's in-app messages newest first with cursor pagination. status filters on the display status (all, draft, active, scheduled, paused, completed); search matches the message name. Each item carries its all-time impressions, reach and ctr (percentage 0-100, null when reach is 0). active_count is the App's active messages and active_limit the plan ceiling, null for self-hosted Companies or when the plan lookup fails (the activation gate stays authoritative).
Authorizations
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parameters
Path Parameters
App ID
Query Parameters
all (default), draft, active, scheduled, paused or completed
Name search, at most 200 characters
Page size, 1 to 100 (default 50)
next_cursor of the previous page
Responses
OK
Create an in-app message
Creates an in-app message scoped to the App as a draft, or as active when status is "active" (checked against the plan's active-message limit). Unknown fields are rejected.
Authorizations
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parameters
Path Parameters
App ID
Request Body
Responses
Created
Estimate an in-app audience
Counts the App's devices that match at least one of segment_ids (every device when empty), match none of exclude_segment_ids, and run on one of the platforms (any platform when empty). Subscribed and unsubscribed devices both count, since in-app messages do not depend on push permission. Unknown fields are rejected.
Authorizations
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parameters
Path Parameters
App ID
Request Body
Responses
OK
List the in-app messages a device may show now
Returns the active messages the device is eligible for, oldest first, filtered by window, platform, frequency and segment: up to 5 shown at session start and up to 10 shown on an event (trigger). The device proves ownership with its push token; a wrong token, an unknown device and a device of another App all answer 403. A disabled App returns an empty list. Rate limited per device. Client key only.
Authorizations
App Client key (ck_...). Device-facing calls only.
Parameters
Path Parameters
App ID
Request Body
Responses
OK
List in-app trigger event names
Lists the distinct event names used as triggers by the App's non-deleted messages, sorted, at most 50. The dashboard offers them as suggestions; event names are not registered anywhere else.
Authorizations
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parameters
Path Parameters
App ID
Responses
OK
Get an in-app message
Fetches a single in-app message by ID, scoped to the App.
Authorizations
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parameters
Path Parameters
App ID
Message ID
Responses
OK
Delete an in-app message
Soft-deletes a message: it disappears from lists and device fetches, and its metrics stay readable by ID.
Authorizations
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parameters
Path Parameters
App ID
Message ID
Responses
No Content
Update an in-app message
Partially updates a message. An omitted key keeps its stored value; null clears media_id, image_url, starts_at, ends_at, style, image_action and dismiss_after_seconds (trigger: null is session start); buttons, platforms, segment_ids, exclude_segment_ids, frequency, style, image_action and trigger replace the stored value wholesale (null or [] clears the segment lists; a partial style clears the tokens it omits). Status is not patchable (use activate and pause). Editing an active message applies to subsequent device fetches only; moving a completed message's ends_at into the future (or clearing it) counts it against the plan's active-message limit again.
Authorizations
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parameters
Path Parameters
App ID
Message ID
Request Body
Responses
OK
Activate an in-app message
Moves a draft or paused message to active after re-validating its content and image and checking the plan's active-message limit. Activating an active message is a no-op.
Authorizations
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parameters
Path Parameters
App ID
Message ID
Responses
OK
Record an in-app message engagement event
Stores one impression, click or dismiss reported by a device. event_id is a client-generated UUID that makes retries idempotent per message and device: the first delivery answers 201, a repeat answers 200 with duplicate true. click requires button_id of one of the message's buttons, or image when the message has an image action; dismiss requires reason (close_button, swipe, outside_tap, or auto when the timer closed the message). occurred_at (RFC3339) is kept only within 7 days before to 5 minutes after the server time, otherwise the server time is stored. Paused, expired and deleted messages still accept events. The device proves ownership with its push token; a wrong token, an unknown device and a device of another App all answer 403. Rate limited per device. Client key only.
Authorizations
App Client key (ck_...). Device-facing calls only.
Parameters
Path Parameters
App ID
Message ID
Request Body
Responses
duplicate event_id, nothing stored
Get an in-app message's metrics
Engagement of one message over a window in the App's timezone: totals, daily series (zero-filled), per-button clicks (a row with button_id "image" comes first when the message has an image action or the image was tapped) and the top 5 platform, app version and country of devices that saw it. Rates are percentages 0-100 with one decimal and null when their denominator is 0. dismiss_rate counts devices that closed the message themselves (close button, swipe, outside tap) and never clicked; devices that only saw it close on its timer are counted in totals.auto_dismissed instead, so the two never overlap. eligible_devices is the audience the message targets right now (a point-in-time estimate) and is null when the message was deleted or the estimate failed or timed out; reach_rate is reach over eligible_devices, capped at 100. Soft-deleted, paused and ended messages stay readable. range is 7d, 14d (default), 30d, 90d or custom with from and to as YYYY-MM-DD, to inclusive; range.end is the last day of the window.
Authorizations
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parameters
Path Parameters
App ID
Message ID
Query Parameters
7d, 14d (default), 30d, 90d or custom
First day (YYYY-MM-DD), required with range=custom
Last day, inclusive (YYYY-MM-DD), required with range=custom
Responses
OK
Pause an in-app message
Stops serving an active message on the devices' next fetch and keeps its metrics.
Authorizations
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parameters
Path Parameters
App ID
Message ID
Responses
OK