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

# Widget versions

> Load the latest widget, pin a major or exact version, or test the prerelease, and read the version and deprecation headers.

The `<botshield-verify>` widget is served from one host, `cdn.botshield.ai`, at several paths. The path decides which version you get. Use it to stay on a version until you are ready to move.

## Paths

| URL | Serves | Browser cache |
| - | - | - |
| `https://cdn.botshield.ai/sdk.js` | The latest stable version | 5 minutes |
| `https://cdn.botshield.ai/v/3/sdk.js` | The latest `3.x` version. You receive minor and patch releases, and never a new major version. | 5 minutes |
| `https://cdn.botshield.ai/v/3.0.0/sdk.js` | Exactly `3.0.0`. The file never changes. | 1 year, `immutable` |
| `https://cdn.botshield.ai/next/sdk.js` | The prerelease of the next version | 1 minute |

The current stable version is `3.0.0`, released with BotShield 3.0 on September 28, 2026. Version `2.0.1` stays available at `/v/2/sdk.js` and `/v/2.0.1/sdk.js`, with a deprecation header.

```html theme={null}
<!-- Latest stable -->
<script src="https://cdn.botshield.ai/sdk.js"></script>

<!-- Stay on 3.x -->
<script src="https://cdn.botshield.ai/v/3/sdk.js"></script>

<!-- Stay on 2.x (deprecated) -->
<script src="https://cdn.botshield.ai/v/2/sdk.js"></script>

<!-- Frozen at 3.0.0 -->
<script src="https://cdn.botshield.ai/v/3.0.0/sdk.js"></script>
```

Load one script per page.

## Which path to use

| You want | Use |
| - | - |
| Fixes and new features as they ship | `/sdk.js` |
| Updates within one major version | `/v/<major>/sdk.js` |
| No change until you decide | `/v/<x.y.z>/sdk.js` |
| To test the next version before release | `/next/sdk.js`, on a test page only |

The **major** version is the first number. A major pin follows the minor and patch releases of that major version and never moves to the next one. Read the [changelog](/changelog/alias-window) before you move to a new major version.

<Warning>
  Do not use `/next/sdk.js` in production. It changes without notice and can include unfinished behavior.
</Warning>

## Exact versions never change

A published exact version is immutable. A fix is released as a new patch version. It never replaces an existing file. You can use [Subresource Integrity](https://developer.mozilla.org/docs/Web/Security/Subresource_Integrity) with an exact-version URL. Do not use it with `/sdk.js`, `/v/<major>/sdk.js` or `/next/sdk.js`, because those files change when a new version is published.

## Response headers

Every response names the version it served.

| Header | Value | Sent |
| - | - | - |
| `X-BotShield-SDK-Version` | The exact version served, for example `3.0.0` | Always |
| `X-BotShield-Channel` | `next` | On `/next/sdk.js` only |
| `Cache-Control` | See [Paths](#paths) | Always |

```bash theme={null}
curl -sI https://cdn.botshield.ai/v/3/sdk.js | grep -i x-botshield
```

```text theme={null}
x-botshield-sdk-version: 3.0.0
```

## Deprecation headers

When the version you load belongs to an older major version than the latest, the response adds deprecation headers.

```http theme={null}
Deprecation: true
Link: <https://docs.botshield.ai/changelog/sdk>; rel="deprecation"
Sunset: Sat, 15 Jan 2028 00:00:00 GMT
```

| Header | Meaning |
| - | - |
| `Deprecation` | The major version you load is not the latest. |
| `Link` | Where to read about the change. |
| `Sunset` | The date the major version is retired. It is sent only after a retirement date has been set. The date above is an example. |

No version is removed without these headers being sent first.

## Unknown versions

A version that was never published returns HTTP `404`. The widget is never replaced by a different version than the one you asked for.

```json theme={null}
{ "error": "sdk_version_not_found" }
```

## The `v` query parameter

Older snippets load `https://cdn.botshield.ai/sdk.js?v=17`. The `v` query parameter is accepted and ignored. Those snippets keep working and receive the latest stable version. To choose a version, use a path from the table above.