> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userkit.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Write a banner
> Requires `engagement:manage`.
`kind` is `text` or `image` and **cannot be changed afterwards**: the two kinds fill different columns, so turning one into the other would discard what somebody wrote with no way back. Create the other kind instead — which also keeps the dismissal count attached to the thing people actually saw.
`slot` is where it renders, matched by string against the `slot` prop your own developer wrote: ``. Lowercase letters, digits, hyphens and underscores — a name is refused rather than normalised, because this string is typed twice in two different places and case is how that goes wrong invisibly. Nothing here checks that your app renders that slot; we cannot see your code.
`active` defaults to **false**: a banner exists while its copy is being written, and creating one never puts anything in front of anybody. This is the module that draws itself on your production pages, so the off switch is one call and takes effect on the next poll.
`starts_at` and `ends_at` are the window it is true in, both optional, both RFC 3339 with an offset. They are separate from `active` because they answer different questions — `active` is "is this approved", the window is "when is it true" — and a maintenance notice written on Monday for Saturday needs to be switched on and not yet showing. `ends_at` is also what takes the Black Friday strip down on Monday without anybody remembering.
`segment_id` is who it is for, or `null` for everybody, and it must name a segment of the same environment — the audience your flags, surveys and changelog posts already use, never a filter of its own.
`priority` decides which banner wins when a slot has more than one candidate: higher first, ties broken by newest. **Only one banner is ever returned per slot**, decided in the database, so the answer is the same for the React component, a mobile shell and a preview.
`dismissible` defaults to **true**: a strip somebody cannot get rid of is an ad, and these go in front of your own customers. `false` is for the notices that are a state of the product rather than news — "this account is read-only until you confirm your email" — where hiding it would hide the explanation for what the person is about to run into.
## OpenAPI
````yaml /api-reference/openapi.json post /v1/organization/banners
openapi: 3.1.0
info:
title: UserKit API
version: 1.0.0
description: >-
The HTTP surface of UserKit.
Two planes share one API. The **staff plane** is what a human uses in the
panel: users, organizations, roles, members, keys. The **customer plane** is
what a developer's own product uses: contacts, identities, the federated
boot and the two proofs of an address.
Every error answers the same envelope — `{"error": {"code", "message"}}`.
The `code` is a stable contract to branch on; the `message` is for a person
and may change.
servers:
- url: '{baseUrl}'
description: The API host.
variables:
baseUrl:
default: https://api.userkit.dev
description: Base URL of the API, no trailing slash.
security:
- sessionToken: []
tags:
- name: Gamification
description: >-
Points, levels and badges: the acts your product wants repeated, written
down as rules, and what each of your own users has accumulated by doing
them. A rule pays when the fact it names lands — there is no endpoint your
users can call that moves a balance, and there is not going to be one.
- name: Authentication
description: >-
Public sign-up, sign-in, two-factor and password recovery for staff
accounts.
- name: Session
description: >-
The active session: who the caller is, which organization they are in, and
signing out.
- name: Account
description: The caller's own account — profile, password, sessions, avatar.
- name: Two-factor
description: >-
TOTP setup, activation and recovery codes. Returns 501 when two-factor is
unavailable on the server.
- name: Organizations
description: The organizations a user belongs to, and the active one.
- name: Environments
description: >-
The live and test environments seeded with every organization, and their
identity settings.
- name: Members
description: Memberships and invitations.
- name: Roles
description: Roles and the permission catalogue they draw from.
- name: Audit log
description: >-
What staff did inside an organization. Append-only, and read behind its
own permission.
- name: API keys
description: Secret keys (`uk_sk_…`) and publishable keys (`uk_pk_…`).
- name: Contacts (staff session)
description: >-
The staff view of the customer plane, opened by a staff session. Reads
take `?environment=` as an explicit view parameter.
- name: Contacts (API key)
description: >-
The machine surface, authenticated by an API key. The environment is the
key's environment and cannot be named by the caller.
- name: Customer plane
description: >-
Called from the developer's own pages with a publishable key: boot, the
two proofs of an address (magic link, email code), and the contact's own
session.
- name: Customer teams
description: >-
A customer is a team. Its roster, its invitations and the roles held
inside it, administered by the contact's own session. `owner` and `member`
always exist; the rest of the vocabulary is the organization's own — see
Customer roles. The active customer travels in `X-Customer-Id`.
- name: Customer roles
description: >-
The vocabulary of roles inside your customers, defined per environment. A
customer used to be two shapes — the person who administers it and
everybody else — which is what `owner` and `member` are, and they are
still seeded into every environment and cannot be deleted. Beyond them you
define your own: a school has a director, a secretary, a teacher and a
student, and none of that fits a boolean.
A role carries permissions from **two vocabularies in one list**.
Permissions beginning with `$` are UserKit's own and are the only ones we
evaluate — `$team.manage` administers the roster, `$billing.manage` the
money, `$keys.manage` the team's API keys. Everything else is yours: we
store it, we hand it back on the contact's session and in the
`customer_permissions` claim of their JWT, and we never read it. That is
the point — your backend gates `grades:write` offline, and adding a role
never means editing your gate.
Reading is `customers:read`, writing `customers:write`.
- name: Webhooks
description: >-
Outbound webhooks: endpoints, the published event catalogue, the delivery
log, replay and test sends. Never gated by a plan — webhooks are a
developer primitive.
- name: Catalogue
description: >-
The plans, prices and features **you** sell to your own customers. Per
environment, a price per currency, and `recurring` or `one_time`. Distinct
from the plan you are on with UserKit, which is `GET
/v1/organization/entitlements`.
- name: Subscriptions
description: >-
What one of **your** customers is paying you, mirrored from the gateway
that charges them. The gateway is the truth about money — it holds the
schedule, runs the retries and decides what a proration is worth — so
these routes ask it to change something and answer with what it then said.
`provider_synced_at` is how stale the copy admits to being.
- name: Provider webhooks
description: >-
Where a payment provider delivers to. Not a surface you call — it is a URL
you paste into the provider's dashboard, which is why it sits outside
`/v1`: a version bump must never mean editing a setting in somebody else's
product. Signed with the secret of the connection named in the path, and
safe to retry.
- name: Entitlements
description: >-
What one of **your** customers may do, resolved: the plan their
subscription carries, plus the overrides you promised them on top. This is
the read your own gate calls, so it is cached and answers in one round
trip. It is a different question from `GET /v1/organization/entitlements`,
which is the plan **you** are on with UserKit — two catalogues, same word,
different money.
- name: Credits
description: >-
How much of a `credit` feature one of **your** customers still holds. The
balance is an append-only ledger folded on demand — grants arrive from
paid invoices, usage spends against it (`POST /v1/usage`, fail closed),
unused credits expire oldest-first, and a support correction is a new
signed line rather than an edit. Whether a balance may go below zero, and
how far, is the plan's `overdraft_limit`.
- name: Customer API keys
description: >-
Keys **your customers** issue (`uk_ck_live_…` / `uk_ck_test_…`) so your
own metered surface can be called per key. An owner of a customer team
mints them from their session; your backend treats the string as data and
resolves it with `POST /v1/customer-keys/verify` (or passes it as
`customer_key` to `POST /v1/usage`). A customer key never authenticates
against this API.
- name: Customer webhooks
description: >-
Webhook endpoints **your customers** register from the portal, hearing the
events *you* tracked about their team — `POST /v1/track` lines carrying
their `customer_id`, delivered under your own event names. Administered
under `$webhooks.manage` (the seeded `owner` role holds it), signed and
retried exactly like your own endpoints, and gated by your plan:
registering answers `webhooks_not_available` on a plan without the
capability, and a downgrade stops deliveries without deleting anything.
- name: Pricing
description: >-
The public read of what you sell: live plans and prices, addressed by
publishable key, cacheable like JWKS. What a `` renders,
and the offer the customer's own checkout sells from.
- name: Customer billing
description: >-
The customer's **own** view of what their team pays, from their session:
the subscription, the invoices, and the self-serve acts — checkout, plan
change, cancel, resume, the gateway's portal. Reads are for every member;
the money acts are owner-only, because spending the team's money is
administering the team.
- name: Support
description: >-
The support inbox. A conversation is opened by **your customer** — from
the chat widget, or by an inbound email — and staff receive it: there is
deliberately no staff-side create. Conversations live in an environment
(their subject is a contact); tags and saved replies are the
organization's own vocabulary and take no environment. `support:read` and
`support:write` gate the staff surface, and every seeded role holds both —
the support agent is the archetypal member seat.
- name: Help center
description: >-
The articles you publish so a conversation does not have to happen.
Organization-scoped — the product does not differ between live and test
the way its contacts do — and versioned append-only: saving creates the
next version, publishing points the public page at one of them, and
restoring is publishing an old one. The editor rides the support
permissions; the published side is public, addressed by your publishable
key, and cacheable.
- name: Segments
description: >-
Audiences, defined declaratively over contact attributes, plan, events and
activity. One definition compiles into two evaluators that must agree — a
query over the environment and an in-process match for one contact — so
the count on a screen and the decision made about one person come from the
same sentence. Reading is `customers:read` (a segment is a filtered list
of contacts); writing is `segments:manage`, because one definition decides
who is mailed, surveyed and shown an unreleased feature at once.
- name: Feature flags
description: >-
Release switches the tenant's own product reads. A flag is aimed at a
**segment** and never at a filter of its own, so the audience a rollout
uses is the audience a survey and a changelog post can use. Two reads
serve it: `POST /v1/boot` decides every flag for the person in the round
trip the session already cost, and `GET /v1/flags/{publishable_key}` is a
public, cacheable document that carries only the switch — polled on a
fifteen-second clock and applied over whatever the page booted with. Staff
CRUD is `flags:manage`.
- name: Onboarding
description: >-
Checklists the widget renders for your own users, and the funnel behind
them. A step is satisfied by a **fact having happened** or by an
**entitlement being held** — there is no endpoint that marks one done, by
construction, because a checklist whose completion is a button is a
measure of who pressed the button. Event steps are written by a bus
consumer and are what the funnel counts; entitlement steps are decided on
the read against the team the request names, and nothing is stored for
them. Staff CRUD and the funnel are `engagement:manage`, the permission
the changelog and surveys share.
- name: Surveys
description: >-
NPS and one-question surveys, asked in-app. A survey is aimed at a
**segment** or at everybody, fires on a trigger (a fact you named,
entering that audience, or N days after somebody signed up) and is held
back by a **per-contact cooldown** — the window is per person rather than
per survey, which is what makes "nobody is surveyed twice a week" true
across every survey you run. Delivery is in-app: `GET
/v1/contact/surveys/pending` is what the widget reads and `POST
/v1/contact/surveys/{id}/response` is the answer, which announces
`survey.response_recorded` to your webhooks. Staff CRUD and the results
are `engagement:manage`, the permission onboarding and the changelog
share.
- name: Changelog
description: >-
What you shipped, said once. A post is written as a draft, aimed at a
**segment** or at everybody, and published by an act of its own —
publishing is what puts it in a cacheable public document and announces
`changelog_post.published` to your webhooks, so it is a call you make on
purpose rather than a field on an edit. Two reads serve it: `GET
/v1/changelog/{publishable_key}` is the public release page and carries
the posts aimed at nobody in particular; `GET /v1/contact/changelog` is
the same list for one signed-in person, with the targeting honoured and
their read state on it. Staff CRUD is `engagement:manage`, the permission
onboarding and surveys share.
- name: Banners
description: >-
Messages you put on your own users' screens — a strip at the top of the
dashboard, a notice in the billing settings, a picture you designed. A
banner names a **slot**, which is a place your own developer left room for
with ``; nothing is injected into your
layout, because the only place a third party may draw is one the page
owner declared. It is aimed at a **segment** or at everybody, bounded by
an optional window, and only **one banner per slot** is ever returned —
highest priority wins, decided in the database so every client gets the
same answer. Two kinds: `text` (title, body, icon, tone, button), drawn by
the widget in your palette, and `image`, a picture you made and optionally
a link. `GET /v1/contact/banners` is what the widget reads and `POST
/v1/contact/banners/{id}/dismiss` is the close button. Staff CRUD is
`engagement:manage`, the permission onboarding, the changelog and surveys
share.
- name: Legal
description: >-
The terms your own customers agree to — terms of service, a privacy
policy, a code of conduct — and the record of who agreed to which words. A
**document** is a name, an address (`slug`) and a rule about whether
agreeing is required; a **version** is the text, and it is frozen the
moment it is published, because an acceptance that pointed at an editable
body would prove nothing. Publishing may be dated ahead, which is what a
thirty-day notice is: the version before it stays in force until then. A
new version asks everybody again only when it says `requires_reacceptance`
— a corrected typo does not, a new arbitration clause does. `GET
/v1/legal/{publishable_key}` is public and cacheable, because a sign-up
form has to render the link before there is any session. `required`
refuses nothing — there is no sign-up door of UserKit's for it to refuse
at — and is reported as `blocking` wherever outstanding agreements are
read; what an outstanding agreement does is your product's decision. It
never refuses an ordinary API call, and `POST /v1/contact/token` in
particular — publishing new terms must mean "everybody is asked", never
"everybody is logged out". Staff CRUD is `legal:manage`.
- name: Feedback
description: >-
A feedback board and a public roadmap. Your users ask for things, vote on
each other's requests and read what you answered; you triage, merge the
duplicates and move a post to `planned`, `shipped` or `declined`. The part
a separate feedback tool cannot do is the ranking: `GET
/v1/organization/feedback?currency=BRL` weights every post by the
**revenue of the distinct customers behind its voters**, so a team of five
is worth its revenue once rather than five votes. That number exists on
the staff read and nowhere else — the public board says how many people
asked, never who pays. Reading is `feedback:read` (owner, admin **and**
member, because triage is support work); answering is `feedback:write`.
- name: Notifications
description: >-
Consent for the mail this platform sends your own users, and the
unsubscribe link that changes it.
Three categories — `marketing`, `product_news` and `surveys` — and every
one of them is something a person can switch off. **Transactional mail is
not one of them, and there is no value that names it.** A receipt, a
dunning notice, a verification link and a password reset keep arriving
after somebody unsubscribes from everything, because the absence of the
category is what guarantees no screen and no bulk update can produce a
person who cannot reset their own password.
Consent is honoured at the **send funnel** rather than by whoever composes
the message, in the same statement that records the delivery — so a
message this person switched off is a message that is never composed, not
one that is filtered afterwards. Every non-transactional message carries
the unsubscribe link in its footer and the `List-Unsubscribe` /
`List-Unsubscribe-Post` header pair on its envelope; no transactional
message carries either.
- name: Messaging
description: >-
The message templates outbound campaigns send: a subject, a body, a
channel and the **category** the recipient can switch off.
The subject and the body are Go `text/template`, compiled **when you
save** — a template naming a field the message context does not carry is
refused with the field named, never stored to fail per recipient in a job
at three in the morning. The context is closed on purpose: `Contact`,
`Customer`, `Plan` and `Entitlements`, and nothing else. Whatever a
template can reach is reachable by whoever can write one.
The category lives on the template rather than on whatever sends it,
because a category is a statement about what a message *says*, and the
template is the only object here that knows what it says. A campaign
inherits it. `messaging:manage` covers the whole surface, reads included —
an unsent price change is not something a wider permission should be able
to read.
- name: Campaigns
description: >-
The object that reaches out: an audience, a trigger, a sequence and a cap.
The audience is always a **segment** — there is no filter of a campaign's
own, because an audience defined twice can be previewed one way and mailed
another. The words are a **message template**, and the campaign inherits
the template's category rather than choosing one. The trigger is one of
four: a one-shot to whoever is in the audience now, a fact of a named
type, entering the audience, or N days from a timestamp on the contact.
Two limits hold at once and they are different promises.
`frequency_cap_days` is how long **this** campaign waits before reaching
the same person again; a 24-hour cooldown across **every** campaign of the
environment sits behind it, so somebody who trips three rules in one hour
receives one message. Neither applies to the later steps of a sequence
already begun — a cooldown that broke a sequence in half would be a setup
that works in test and truncates in production.
A contact who has switched the template's category off is recorded as
**suppressed with the reason**, which is what lets support answer "why
didn't they get it". Writing a campaign is free; **arming** one is what a
plan gates.
- name: In-app notifications
description: >-
The message that lands inside your product rather than in an inbox: "your
export is ready", "the invoice failed", "someone mentioned you".
Your backend posts one over `uk_sk_…` and the person reads it from their
own session. It is **transactional by construction** — the request carries
no category and there is no field that could carry one, so an in-app
notification is not something anybody can unsubscribe from, in the same
way a receipt is not. That is not a policy this endpoint applies; it is
the only value the write can produce.
The write inherits the machine surface's two promises by living on it: an
`Idempotency-Key` replays the first response rather than telling somebody
the same thing twice, and the per-key rate limit counts the call. The
recipient is named by `contact_id` or by your own `external_id` — one of
the two, never both, because a request naming two people is a request we
would have to guess about.
- name: MCP
description: >-
One endpoint an AI agent's client connects to, so "how many people signed
up this week" is answered where the question is asked. Authenticated with
an API key, which is also what fixes the environment — no tool takes one
as an argument. Every tool is a READ: nothing here creates, changes or
deletes anything, and nothing answers with a credential or with the staff
audit log. Outside `/v1` because the URL lives in a configuration file
rather than in your code.
- name: Analytics
description: >-
The staff read of what happened inside your product: the event explorer,
daily counts, saved queries and funnels. Everything here sits behind
`analytics:read` — owner and admin by default, because Phase 4's
dashboards put revenue on the same screens as event counts. The write path
is `POST /v1/events` and the platform's own auth facts; no staff session
reaches it.
- name: Alerts
description: >-
Where your organization's bad news gets delivered: Slack, Discord or
email. Everything else here is pull — you open a screen and the number is
there — and this is the push half, for the five facts nobody opens a
screen to discover: the contact meter at 80% and 100%, an environment out
of its email allowance, a webhook endpoint turned off after sustained
failure, a payment gateway that stopped answering, and a customer's
payment being declined.
The five are **fixed**. There is no rule to configure and no threshold to
set — what fires is decided by the code that publishes each fact, and a
second place to re-decide it would be a place that disagrees. What you
configure is the destination.
The destination is stored encrypted and is never read back: a Slack
incoming webhook is a credential, and whoever holds it writes into that
channel. Responses carry `destination_hint` — the host for a chat hook,
the address for an email. Gated by `alerts:manage`, which only `owner`
holds by default.
- name: Referrals
description: >-
Your own users bringing you other users, and what you owe them for it. A
code carries its terms (a share in basis points, or a flat bounty),
`?ref=CODE` is captured by the SDK as first-touch attribution and recorded
at the referred person's first identification, and a paid invoice appends
a commission line. First touch is immutable — whoever referred somebody
referred them, and a later link cannot take the commission — and a refund
appends a negative line rather than erasing the positive one. Payouts are
manual: this surface says what is owed and nothing here transfers money.
paths:
/v1/organization/banners:
post:
tags:
- Banners
summary: Write a banner
description: >-
Requires `engagement:manage`.
`kind` is `text` or `image` and **cannot be changed afterwards**: the
two kinds fill different columns, so turning one into the other would
discard what somebody wrote with no way back. Create the other kind
instead — which also keeps the dismissal count attached to the thing
people actually saw.
`slot` is where it renders, matched by string against the `slot` prop
your own developer wrote: ``. Lowercase
letters, digits, hyphens and underscores — a name is refused rather than
normalised, because this string is typed twice in two different places
and case is how that goes wrong invisibly. Nothing here checks that your
app renders that slot; we cannot see your code.
`active` defaults to **false**: a banner exists while its copy is being
written, and creating one never puts anything in front of anybody. This
is the module that draws itself on your production pages, so the off
switch is one call and takes effect on the next poll.
`starts_at` and `ends_at` are the window it is true in, both optional,
both RFC 3339 with an offset. They are separate from `active` because
they answer different questions — `active` is "is this approved", the
window is "when is it true" — and a maintenance notice written on Monday
for Saturday needs to be switched on and not yet showing. `ends_at` is
also what takes the Black Friday strip down on Monday without anybody
remembering.
`segment_id` is who it is for, or `null` for everybody, and it must name
a segment of the same environment — the audience your flags, surveys and
changelog posts already use, never a filter of its own.
`priority` decides which banner wins when a slot has more than one
candidate: higher first, ties broken by newest. **Only one banner is
ever returned per slot**, decided in the database, so the answer is the
same for the React component, a mobile shell and a preview.
`dismissible` defaults to **true**: a strip somebody cannot get rid of
is an ad, and these go in front of your own customers. `false` is for
the notices that are a state of the product rather than news — "this
account is read-only until you confirm your email" — where hiding it
would hide the explanation for what the person is about to run into.
operationId: createBanner
parameters:
- $ref: '#/components/parameters/OrganizationHeader'
- $ref: '#/components/parameters/EnvironmentQuery'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BannerInput'
responses:
'201':
description: The banner.
content:
application/json:
schema:
type: object
properties:
banner:
$ref: '#/components/schemas/Banner'
'400':
description: >-
`invalid_request`. `invalid_slot` — the slot is not a slug.
`unknown_icon` — a glyph the widget cannot draw. `unknown_segment` /
`segment_environment_mismatch` — the audience.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'422':
description: >-
`cta_needs_url` — a button with no destination does nothing when it
is clicked. `invalid_window` — `ends_at` is not after `starts_at`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
parameters:
OrganizationHeader:
name: X-Organization-Id
in: header
required: false
schema:
type: string
description: >-
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.
EnvironmentQuery:
name: environment
in: query
required: false
schema:
type: string
enum:
- live
- test
default: live
description: >-
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.
schemas:
BannerInput:
type: object
description: >-
A banner on the way in. `kind` and `slot` are required on create and
`kind` is refused on update. The fields of the kind you are not writing
are ignored and stored empty — a row carrying both kinds' content is one
whose appearance would depend on which branch of the widget read it
first.
properties:
kind:
type: string
enum:
- text
- image
description: Required on create, immutable afterwards.
slot:
type: string
maxLength: 60
description: >-
Lowercase letters, digits, hyphens, underscores. Matched by string
against the `slot` prop in your app.
active:
type: boolean
default: false
starts_at:
type: string
format: date-time
nullable: true
description: RFC 3339 with an offset. `null` clears the lower bound.
ends_at:
type: string
format: date-time
nullable: true
description: RFC 3339 with an offset. `null` means it never stops.
priority:
type: integer
minimum: -1000
maximum: 1000
default: 0
dismissible:
type: boolean
default: true
title:
type: string
maxLength: 120
description: Required for `text`.
body:
type: string
maxLength: 500
icon:
type: string
description: One of the names in `icons`, or empty.
tone:
type: string
enum:
- info
- success
- warning
- danger
default: info
cta_label:
type: string
maxLength: 40
description: >-
Needs `cta_url` alongside it — a button with no destination does
nothing when it is clicked.
cta_url:
type: string
description: >-
Both kinds: the button's destination, or the whole picture's link.
Empty means it goes nowhere.
A path rooted at `/` (`/plans`) or an absolute `http`/`https` URL —
the same two shapes an in-app notification's `url` takes, and for
the same reason. A path is if anything the more natural half here,
since a banner is drawn inside your own product. Anything else is a
`400`, `javascript:` and the protocol-relative `//host/path`
included: this value ends up in an `href` on your own page.
image_url:
type: string
description: Required for `image`. An absolute http(s) URL.
image_alt:
type: string
maxLength: 300
segment_id:
type: string
format: uuid
nullable: true
description: >-
The audience, or `null` for everybody. Must belong to the same
environment.
Banner:
type: object
description: >-
A message on your users' screens, in a slot your own developer left room
for. `kind` decides which fields carry the content — `text` is drawn by
the widget in your palette, `image` is a picture you made and the widget
only frames — and it cannot change, because the two fill different
columns and turning one into the other would discard what somebody
wrote.
properties:
id:
type: string
format: uuid
environment_id:
type: string
format: uuid
kind:
type: string
enum:
- text
- image
slot:
type: string
description: Where it renders, matched against the `slot` prop in your app.
active:
type: boolean
description: >-
Whether it is on the screen at all. The off switch, and it takes
effect on the widget's next poll.
starts_at:
type: string
format: date-time
nullable: true
description: '`null` means no lower bound — it is showing already.'
ends_at:
type: string
format: date-time
nullable: true
description: '`null` means it never stops on its own.'
priority:
type: integer
description: >-
Which one wins when a slot has more than one candidate. Higher
first, ties broken by newest.
dismissible:
type: boolean
description: Whether the reader may close it, and whether that closing sticks.
title:
type: string
description: '`text` only.'
body:
type: string
description: >-
`text` only. Plain text, not markdown — a banner that needs
formatting links to a changelog post.
icon:
type: string
description: >-
`text` only. A name from `icons`, or empty. The widget draws the
glyph; it is never markup or a URL.
tone:
type: string
enum:
- info
- success
- warning
- danger
description: >-
`text` only. What it MEANS — the widget maps it onto your palette,
so rebranding does not mean re-opening thirty banners.
cta_label:
type: string
description: '`text` only. What the button says.'
cta_url:
type: string
description: >-
Both kinds: the button's destination, or the whole picture's link.
Empty means it goes nowhere.
A path rooted at `/` (`/plans`) or an absolute `http`/`https` URL —
the same two shapes an in-app notification's `url` takes, and for
the same reason. A path is if anything the more natural half here,
since a banner is drawn inside your own product. Anything else is a
`400`, `javascript:` and the protocol-relative `//host/path`
included: this value ends up in an `href` on your own page.
image_url:
type: string
description: '`image` only. An absolute http(s) URL.'
image_alt:
type: string
description: >-
`image` only. What a screen reader says instead. Empty is legitimate
for a decorative image.
segment_id:
type: string
format: uuid
nullable: true
description: The audience, or `null` for everybody.
dismissals:
type: integer
description: How many people closed it. Present on the list read.
views:
type: integer
nullable: true
description: >-
Impressions over the window named in `engagement`. Present on the
list read.
An impression is the strip CROSSING the fold, not the component
rendering — a banner below the fold is drawn on every page load and
seen by nobody. It comes from the `banner.shown` analytics events
the widget writes, so it is `null` (never `0`) when analytics could
not be read: zero would say the banner reached nobody.
viewers:
type: integer
nullable: true
description: >-
The people behind those impressions. A dashboard somebody opens
eleven times a day is eleven `views` and one viewer — quote this one
as reach.
Every distinct contact, anonymous visitors included: a banner is
drawn for them too, and a reach figure that dropped everyone who has
not signed in would be missing exactly the audience an announcement
is usually aimed at.
clicks:
type: integer
nullable: true
description: >-
Click-throughs on the call to action over the same window, from
`banner.clicked`. Always 0 for a banner with no `cta_url` — there is
nothing to click.
clickers:
type: integer
nullable: true
description: The people behind those clicks.
created_by:
type: string
format: uuid
nullable: true
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
Error:
type: object
description: Every error in this API answers this envelope.
properties:
error:
type: object
properties:
code:
type: string
description: Stable. Branch on this.
message:
type: string
description: For a person. May change.
required:
- code
- message
required:
- error
example:
error:
code: forbidden
message: your role does not allow this action
responses:
Unauthorized:
description: >-
`unauthorized` — missing, malformed, expired or revoked credential, and
nothing else: it says the credential is gone, so a client is right to
discard it and sign in again. A well-formed credential from the wrong
family says so: "this endpoint expects a staff session token, not an
organization API key". A LIVE staff session aimed at an organization it
is not a member of is `not_a_member` (403), never this.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: >-
`forbidden` — your role does not allow this action. On any route taking
a staff session, `not_a_member` is the other 403: the session is valid
and the organization named in `X-Organization-Id` is not one you belong
to. Same answer for an organization that does not exist and for a code
that is not even shaped like one — the refusal is not a directory.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
sessionToken:
type: http
scheme: bearer
description: >-
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.
````