> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipstar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Live Banner

> Get the announcement banner currently live for a project

Returns the announcement banner currently live for a project — the one-line bar (badge, headline, one-sentence body, call-to-action) that the [embed widget](/guides/website-integration#announcement-banner) shows at the top of a site. **Exactly one banner is live per project**: publishing a new one replaces it.

With an API token the response is your project's banner. Without a token it is Shipstar's own (what [shipstar.ai](https://shipstar.ai) renders above its nav). A `404` means no banner is live — never published, replaced, or past its take-down time — and is the normal empty state, not an error: render nothing.

Send `X-Shipstar-Page-Url` with the page you render it on so your dashboard's "Published" status links there.

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.shipstar.ai/api/v1/banner" \
    -H "Authorization: Bearer $SHIPSTAR_API_TOKEN" \
    -H "X-Shipstar-Page-Url: https://your-site.com/"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.shipstar.ai/api/v1/banner', {
    headers: {
      Authorization: `Bearer ${process.env.SHIPSTAR_API_TOKEN}`,
      'X-Shipstar-Page-Url': 'https://your-site.com/',
    },
    next: { revalidate: 300 },
  });
  const banner = response.status === 404 ? null : await response.json();
  ```

  ```python Python theme={null}
  import os, requests

  response = requests.get(
      'https://api.shipstar.ai/api/v1/banner',
      headers={
          'Authorization': f"Bearer {os.environ['SHIPSTAR_API_TOKEN']}",
          'X-Shipstar-Page-Url': 'https://your-site.com/',
      },
  )
  banner = None if response.status_code == 404 else response.json()
  ```
</CodeGroup>

## Response

<ResponseField name="slug" type="string">
  The stable embed key (`data-shipstar-key`). It does not change when a new banner replaces the old one.
</ResponseField>

<ResponseField name="headline" type="string">
  At most 80 characters.
</ResponseField>

<ResponseField name="body" type="string">
  One sentence on the benefit, at most 160 characters. The widget hides it on narrow screens.
</ResponseField>

<ResponseField name="cta_label" type="string">
  Call-to-action label, at most 24 characters.
</ResponseField>

<ResponseField name="badge" type="string">
  Short tag to show before the headline, at most 16 characters — `"New"` unless the banner re-worded it. An empty string means the banner has no badge: render nothing.
</ResponseField>

<ResponseField name="link_url" type="string | null">
  Where the call-to-action points. `null` means the banner has no link — omit the button.
</ResponseField>

<ResponseField name="period_start / period_end" type="string | null">
  The commit window the banner was generated from (`YYYY-MM-DD`).
</ResponseField>

<ResponseField name="published_at" type="string | null">
  ISO-8601. Changes with every publish; use it as a cache key or a "seen" marker.
</ResponseField>

<ResponseField name="expires_at" type="string | null">
  When the banner stops being served, if a take-down was set on the schedule. The API already stops serving it then; respect it if you cache longer.
</ResponseField>

<ResponseField name="commit_count" type="integer | null">
  Provenance: how many commits the banner was generated from.
</ResponseField>

### Example Response

```json 200 theme={null}
{
  "slug": "acme-banner",
  "headline": "Scheduled X threads now post themselves",
  "body": "Approve once; Shipstar posts the thread at the scheduled time.",
  "cta_label": "See what's new",
  "badge": "New",
  "link_url": "https://acme.com/changelog",
  "period_start": "2026-08-31",
  "period_end": "2026-09-07",
  "published_at": "2026-09-07T09:02:11+00:00",
  "expires_at": null,
  "commit_count": 14
}
```

## Errors

| Status | Description                                      |
| ------ | ------------------------------------------------ |
| 404    | No banner is live for the project                |
| 429    | Rate limit exceeded — wait `Retry-After` seconds |