Create a banner

POST/banners

Creates a banner of the token's organisation and returns it with a Location. title, display_from and display_until are required, and display_until must not be before display_from. type defaults to dismissible. role_ids limits the banner to users holding one of those roles of your organisation; an id that is not one returns 422 exists for that position and nothing is saved. Without roles the banner is for every user. description is HTML and is stored and shown as sent. Needs permission to change the organisation. dry_run shows the result without saving it. Emits banner.created; no email. DELETE /banners/{id} undoes it.

Query parameters

dry_runboolean#
Validate and run the call without committing it, returning what the real call would return with meta.dry_run set.

Headers

Idempotency-Keystring#
Makes a retry safe. Send a new UUID for each new request and reuse it only to retry that request; the first response is replayed for 24 hours.

Request body

application/json, required · BannerCreate

titlestringRequired#
The headline.
descriptionstring | null#
The body of the banner, as HTML. Stored as sent.
typestring#
How a reader can respond: dismissible can be closed, confirmable must be confirmed, always_shown cannot be closed.
One of: dismissible, confirmable, always_shownDefault: "dismissible"
display_fromstring (date-time)Required#
When the banner starts to show.
display_untilstring (date-time)Required#
When the banner stops showing. On or after display_from.
background_colourstring | null#
The background colour as #rrggbb.
text_colourstring | null#
The text colour as #rrggbb.
expandedboolean#
Whether the banner opens expanded.
Default: false
role_idsinteger[]#
The roles of your organisation the banner is for. Omit or send an empty list for every user. An id that is not a role of your organisation returns 422 exists.

{
  "title": "Scheduled maintenance",
  "description": "<p>The platform will be unavailable on Sunday.</p>",
  "type": "dismissible",
  "display_from": "2026-07-01T00:00:00Z",
  "display_until": "2026-07-02T00:00:00Z",
  "background_colour": "#112233",
  "text_colour": "#ffffff",
  "expanded": false,
  "role_ids": []
}

Responses

201

The banner was created.

Banner

{
  "data": {
    "id": 1,
    "title": "string",
    "description": "string",
    "type": "dismissible",
    "display_from": "2026-06-12T10:00:00+00:00",
    "display_until": "2026-06-12T10:00:00+00:00",
    "background_colour": "string",
    "text_colour": "string",
    "expanded": true,
    "role_ids": [
      1
    ],
    "created_at": "2026-06-12T10:00:00+00:00",
    "updated_at": "2026-06-12T10:00:00+00:00"
  }
}

401

Authentication failed. error.code is one of invalid_token, expired, revoked.

Error

403

Authorization failed. error.code is one of org_disabled, ip_blocked, missing_scope, scope_disabled, user_disabled.

Error

422

The request can't be processed (HTTP 422): validation_failed with one ErrorDetail per problem, or a code documented on the operation.

Error

429

Rate limit exceeded (error.code = rate_limited).

Error

Examples

curl -X POST https://your-org-domain/kong/core/api/v2/banners\
  -H "Authorization: Bearer $HELM_API_KEY"\
  -H "Content-Type: application/json"\
  -d '{
  "title": "Scheduled maintenance",
  "description": "<p>The platform will be unavailable on Sunday.</p>",
  "type": "dismissible",
  "display_from": "2026-07-01T00:00:00Z",
  "display_until": "2026-07-02T00:00:00Z",
  "background_colour": "#112233",
  "text_colour": "#ffffff",
  "expanded": false,
  "role_ids": []
}'