A valid request URL is required to generate request examples{
"banners": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "text",
"slot": "<string>",
"active": true,
"starts_at": "2023-11-07T05:31:56Z",
"ends_at": "2023-11-07T05:31:56Z",
"priority": 123,
"dismissible": true,
"title": "<string>",
"body": "<string>",
"icon": "<string>",
"tone": "info",
"cta_label": "<string>",
"cta_url": "<string>",
"image_url": "<string>",
"image_alt": "<string>",
"segment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"dismissals": 123,
"views": 123,
"viewers": 123,
"clicks": 123,
"clickers": 123,
"created_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
],
"slots": [
{
"slot": "<string>",
"banners": 123
}
],
"tones": [
"<string>"
],
"icons": [
"<string>"
],
"engagement": {
"days": 123,
"available": true
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}List banners
Requires engagement:manage — reads included, like the changelog, onboarding and surveys. What you say to your own users is your own copy, and no wider permission shows any of it.
Inactive and expired banners are listed and marked: one still being written is what this screen is opened to finish, and last month’s notice is what somebody copies to write this month’s. Every banner carries dismissals, how many people closed it — the one number this module has about a banner’s reception, and there is deliberately no impression or click count beside it (an impression would be a write on every page load of your product, from a browser).
slots is the slots this environment already uses, most-used first. It comes from your own banners rather than from your code — this API cannot see whether <Banner slot="…" /> is still rendered anywhere, and a warning based on a guess would be worse than no warning.
tones and icons are the vocabularies a text banner may name. They travel on the read rather than being hard-coded in a screen, so a screen cannot go on offering a glyph the widget stopped drawing.
A valid request URL is required to generate request examples{
"banners": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "text",
"slot": "<string>",
"active": true,
"starts_at": "2023-11-07T05:31:56Z",
"ends_at": "2023-11-07T05:31:56Z",
"priority": 123,
"dismissible": true,
"title": "<string>",
"body": "<string>",
"icon": "<string>",
"tone": "info",
"cta_label": "<string>",
"cta_url": "<string>",
"image_url": "<string>",
"image_alt": "<string>",
"segment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"dismissals": 123,
"views": 123,
"viewers": 123,
"clicks": 123,
"clickers": 123,
"created_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
],
"slots": [
{
"slot": "<string>",
"banners": 123
}
],
"tones": [
"<string>"
],
"icons": [
"<string>"
],
"engagement": {
"days": 123,
"available": true
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Authorizations
A staff session token, uk_st_…. Minted by sign-up, sign-in or the two-factor exchange. Only a 401 means it is spent; not_a_member (403) is about the organization named in X-Organization-Id and leaves the token good for the others.
Headers
The organization the caller is acting on — the org_… code that appears in the panel URL. It identifies; the membership JOIN is what authorizes, so a forged code reads nothing: the answer is not_a_member (403), which does not mean the session is over. Absent, the session's default organization answers, or — if that membership was revoked while the session was open — any other one the caller still holds.
Query Parameters
Which environment to act in. A view parameter, valid only on the staff surface — a machine credential never chooses its environment, it is resolved from the key.
live, test Response
The banners, newest first.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
What views, viewers, clicks and clickers are OF. Declared rather than assumed, because the counts come from the analytics module and that module can be unavailable without this screen being wrong.
Show child attributes
Show child attributes