---
title: "List active site notices"
method: GET
path: "/v1/notices"
tags: ["Content"]
---

# List active site notices

`GET /v1/notices`

## Request

- Base URL: `https://api.gunspec.io`
- URL: `https://api.gunspec.io/v1/notices`
- Auth: one of:
  - none
  - API key in header `X-API-Key`
  - HTTP bearer

Returns the operator-authored banners the website is currently showing, best first. Only published notices inside their display window appear, so an empty array is the normal state.

No API key required.

## Response `200`

List active site notices

- object
  - `success` boolean, required: Always true on a successful response. Every error carries `false` and an `error` object instead.
  - `data` object, required: The response payload.
    - `notices` SiteNotice[]: Published notices inside their display window, best first: highest priority, then newest.
      - `id` string, required: Row id of the notice. The website keys its dismissal on this, so a new notice is seen even by a reader who dismissed the last one.
      - `label` string, required: Short label shown before the message.
      - `highlight` string, required: The sentence shown in the banner.
      - `detail` string: A second line, shown under the highlight where one is set.
      - `variant` 'info' | 'warning' | 'critical', required: How prominently a site notice is shown.
      - `ctaLabel` string, nullable: Text of the call to action, or null when the banner has none.
      - `ctaUrl` string, nullable: Where the call to action goes.
      - `priority` integer: Higher sorts first. Ties break on newest.
      - `startsAt` string, nullable: When the notice becomes visible. Null means immediately.
      - `endsAt` string, nullable: When it stops being shown. This is why notices are rows rather than copy: an end date is the only version of "take this down later" that does not rely on somebody remembering.

## Other responses

- `400`: Validation error
- `429`: A limit was reached. `RATE_LIMITED` is the per-minute limit: wait `Retry-After` seconds (a minute) and retry. `DAILY_CAP_EXCEEDED` is the plan's daily limit, per key: nothing will be served until the counters return to zero at midnight UTC. `MONTHLY_CAP_EXCEEDED` is the plan's monthly allowance, for the whole account: nothing will be served until midnight UTC on the first of next month, or until the plan changes. For both, `Retry-After` is the seconds until then and `error.resetsAt` says when as an instant. Calls made after a refusal are refused too and do not spend the month, and a free key that keeps calling is paused, so stop at the first one and resume at the reset.
- `500`: Internal server error

---

[API](https://skmtc.dev/gunspec/apis/gunspec-io-api.md) · [All operations](https://skmtc.dev/gunspec/apis/gunspec-io-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gunspec/apis/gunspec-io-api/revisions/f2e974d8b05c?raw)