Banners

List banners

GET/banners
banners:readlist_bannersRead-only

Lists banners, newest first. A user who can change their organisation sees every live banner of the organisation, whatever its display window; narrow with filter[active], true for banners showing now and false for the rest. Any other reader sees only the banners showing now (both display dates set and the current time inside them) that are for every user or for one of the reader's roles; an Opportunity Provider with no such banner of its own sees those of the organisation that provides for it. Changes nothing. Use POST /banners to add one.

Query parameters

  • limitinteger#

    Page size (1–100). Defaults to 25; values are clamped to the range.

    Default: 25
  • cursorstring#

    Opaque pagination cursor taken from a prior response's meta.next_cursor.

  • fieldsstring#

    Comma-separated top-level fields to return. id is always returned.

  • sortstring#

    Comma-separated fields to sort by: created_at, display_from, display_until or title. Prefix a field with - for descending. Defaults to -created_at. The banner id is always the final tiebreak.

  • filter[active]boolean#

    true lists banners whose display window contains the current time; false lists the rest, including banners with no window.

Responses

200

The banners.

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"
    }
  ],
  "meta": {
    "limit": 1,
    "next_cursor": "string",
    "prev_cursor": "string"
  }
}
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 https://your-org-domain/kong/core/api/v2/banners\
  -H "Authorization: Bearer $HELM_API_KEY"\
  -H "Content-Type: application/json"