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

# Versioning & support

> How the API is versioned, what counts as a breaking change, how much notice you get, how long each version is supported, and what has been removed.

These are the promises behind every notice we send you. There are three, plus
the rules that decide when one of them applies.

## API and proxy

You get **at least 90 days' notice** before a breaking change to the API or
the proxy.

### How the API is versioned

The version is in the path: every endpoint is under `/api/v1`. There is one
version, `v1`, and no version header or dated pin to set. Every request
already names its version, so nothing moves under a client that has never
chosen one.

A breaking change ships as a new endpoint or a new version, never as a change
to an existing `/api/v1` endpoint. If a `v2` ever ships, `v1` keeps working
unchanged for at least 90 days after we announce it.

### What counts as a breaking change

* Removing or renaming an endpoint, a request or response field, or an error
  code.
* Changing a field's type, or the default used when you leave a field out.
* Making an optional request field required.
* Tightening validation, so a request that used to be accepted is refused.
* Changing the status code returned for an existing condition.
* Changing what an existing field means, even if its type stays the same.

### What changes without notice

These ship whenever they are ready and are listed in the
[changelog](https://docs.promptguard.co/changelog.md):

* New endpoints.
* New optional request fields.
* New response fields and headers.
* New error codes for new conditions, and new values in fields that list
  things, such as threat types.
* Loosened validation.
* Changes to what a scan detects. Detection improves continuously; the shape
  of the request and response does not change with it.

Write clients that ignore fields they do not recognise and handle an unknown
error code as a generic failure.

### How a deprecation is signalled

A deprecated endpoint is marked as deprecated in the
[API reference](https://docs.promptguard.co/api-reference/introduction.md), and every response from it
carries a `Deprecation: true` header and a `Sunset` header with the date it
will be removed. It is listed in the table below.

A deprecated default, what a field means when you leave it out, is signalled
the same way on every response that relied on it, with the `Sunset` header
giving the date the default changes.

An endpoint nobody should start using leaves the API reference as soon as it
is deprecated, and is listed only in the table below. It still answers, with
the same headers, until its Sunset date.

The 90 days protect people who depend on an endpoint. A deprecated endpoint
that nobody has ever used, with no record it created, no authenticated
request to it in 30 days and no self-hosted install, may be removed before its
Sunset date. The table below says when that happened.

## SDKs

The SDKs use semantic versioning: anything in an SDK's public interface is
removed or renamed only in a new major version. When a new major version of an SDK ships, the **previous
major version gets security fixes for 12 months**.

Moving from 1.x to 2.0 of the [Python SDK](https://docs.promptguard.co/guides/python-sdk.md), the [Node.js SDK](https://docs.promptguard.co/guides/node-sdk.md) or the [CLI](https://docs.promptguard.co/tools/cli.md):
[Upgrade to SDK and CLI 2.0](https://docs.promptguard.co/releases/sdk-v2-upgrade.md) lists every removed
call and what to use instead.

## Self-hosted

A Release of the self-hosted platform is **supported while it is less than 90
days old**. Security fixes ship in new Releases, **never as backports** to
older ones: to get a fix, upgrade.

## Deprecations and removals

| Date | What | Status | What to use instead |
| - | - | - | - |
| 2027-02-11 | The top-level `detail` field in a `/api/v1` 422 (request validation) or a 404 for a path no endpoint serves | Deprecated on 2026-11-13. These responses now carry the standard [error envelope](https://docs.promptguard.co/production/error-handling.md#the-error-envelope), with code `invalid_request` or `not_found`, and keep `detail` beside it until this date. Until then they carry `Deprecation: true` and a `Sunset` header with this date. | `error.code`, and for a 422 the field list in `error.details`. See [Invalid request](https://docs.promptguard.co/production/error-handling.md#invalid-request-422). |
| 2027-02-11 | `POST /api/v1/guard` with `agreement` left out counting how many detectors agree | Deprecated on 2026-11-13. From this date, leaving `agreement` out means `false`: the scan stops at its first detection, and `detectors_agreeing` counts only the detectors that had found the threat when the scan decided. Decisions, threat types and deciding rules are unchanged. Until then such a response carries `Deprecation: true` and a `Sunset` header with this date. Shadow AI devices always count agreement and are unaffected. | Send `"agreement": true` to keep counting, or `"agreement": false` to opt in to the early stop now. See [Detector agreement](https://docs.promptguard.co/api-reference/guard.md#detector-agreement). |
| 2027-02-06 | `POST /api/v1/api-keys` with `permissions` omitted or empty creating a full-access key | Deprecated on 2026-11-06. From this date, such a key gets `scan` + `proxy`, as a key created in the dashboard does. Until then the response carries `Deprecation: true` and a `Sunset` header with this date. Keys created before it keep their access. | Send `permissions` explicitly: `["*"]` for full access, or the scopes the key needs. See [No permissions](https://docs.promptguard.co/api-reference/api-keys.md#no-permissions). |
| 2026-11-14 | The MCP server's Docker Hub image, `abhijoysarkar/promptguard-mcp-server` | Removed. It was published under a personal account and had not been updated since the image moved to the GitHub container registry on 2026-11-01. | `ghcr.io/promptguardhq/promptguard-mcp-server`, the same server. See [Other ways to launch the local server](https://docs.promptguard.co/tools/mcp.md#other-ways-to-launch-the-local-server). |
| 2026-11-09 | `POST /api/v1/agent/register` and `POST /api/v1/agent/{agent_id}/rotate-credential` | Removed. Deprecated on 2026-11-01 with a Sunset date of 2027-02-15, and removed early because nobody had used them: no agent credential had ever been issued. They issued `pgag_` agent credentials that no PromptGuard request checked, so a credential from them proved nothing. | Nothing. To tell agents apart, send your own `agent_id` on tool-call requests, as you do today; an agent's tool policy is keyed by that ID and is unaffected. |
| 2026-12-09 | `DELETE /api/v1/agent/{agent_id}/session/{session_id}` | Deprecated on 2026-08-10, to be removed on this date. It has always been a no-op: session state is not kept between requests. | Nothing. Stop calling it. |
| - | `active_sessions` in the response of `GET /api/v1/agent/{agent_id}/stats` | Deprecated on 2026-08-10. It is always `0`. No removal date: it stays until a new API version. | Nothing. |
| 2026-08-26 | Node.js SDK 2.0.0: `pg.completions`, `pg.embeddings`, `pg.scrape`, `pg.redteam.runAutonomous()` and `pg.redteam.intelligenceStats()`, and their exported types | Removed. They called endpoints the API does not serve, so they never worked. | Delete the import. For chat traffic, `pg.chat.completions.create(...)`. |
| 2026-08-26 | Python SDK 2.0.0: `completions`, `embeddings`, `scrape`, `redteam.run_autonomous()` and `redteam.intelligence_stats()`, on both clients | Removed, for the same reason. | For chat traffic, `client.chat.completions.create(...)`. For the rest, nothing: delete the call. See [Upgrade to SDK and CLI 2.0](https://docs.promptguard.co/releases/sdk-v2-upgrade.md#python-sdk). |
| 2026-08-26 | CLI 2.0.0: `promptguard logs`, `promptguard events`, `promptguard redteam --autonomous` and the intelligence-stats output | Removed, for the same reason. | Security events are in the dashboard. |
| 2026-08-24 | `GET /api/v1/api-keys/{key_id}/reveal` | Removed. API keys are stored as a one-way digest and cannot be shown again. | A key is shown once, when it is created. To get a new one, create a key with `POST /api/v1/api-keys` or rotate it in the dashboard. |
| 2026-04-06 | The Python MCP server package, `promptguard-mcp-server` | Removed. | [`promptguard mcp`](https://docs.promptguard.co/tools/mcp), built into the CLI. |

## Where you hear about it

* **A change that needs you to act** comes as an email to the owners and
  admins of each affected organization and to the technical contact on each
  self-host licence, whatever your marketing email preferences, and is also
  listed in the [changelog](https://docs.promptguard.co/changelog.md).
* **What changed for you** is in the [changelog](https://docs.promptguard.co/changelog.md), dated by the
  release that delivered it. It has an RSS feed. Filter it by the product you
  use, or show only [breaking changes](https://docs.promptguard.co/changelog.md?tags=Breaking) and
  [deprecations](https://docs.promptguard.co/changelog.md?tags=Deprecation). An entry that needs you to act
  is marked **Breaking change** or **Deprecation** and says what to do.
* **What changed in one release of an SDK, the CLI or the editor extension**
  is in that repository's `CHANGELOG.md`, one section per version, and on its
  GitHub Releases page. The changelog here describes what you notice, not each
  package version. Report a bug in a package in its repository's Issues:

  | Package | Release notes | Report a bug |
  | - | - | - |
  | Python SDK (`promptguard-sdk` on PyPI) | [CHANGELOG.md](https://github.com/promptguardhq/promptguard-python/blob/main/CHANGELOG.md) | [Issues](https://github.com/promptguardhq/promptguard-python/issues) |
  | Node.js SDK (`promptguard-sdk` on npm) | [CHANGELOG.md](https://github.com/promptguardhq/promptguard-node/blob/main/CHANGELOG.md) | [Issues](https://github.com/promptguardhq/promptguard-node/issues) |
  | CLI and local MCP server | [CHANGELOG.md](https://github.com/promptguardhq/promptguard-cli/blob/main/CHANGELOG.md) | [Issues](https://github.com/promptguardhq/promptguard-cli/issues) |
  | VS Code extension | [CHANGELOG.md](https://github.com/promptguardhq/promptguard-vscode/blob/main/CHANGELOG.md) | [Issues](https://github.com/promptguardhq/promptguard-vscode/issues) |
  | Agent plugin | [CHANGELOG.md](https://github.com/promptguardhq/promptguard-plugin/blob/main/CHANGELOG.md) | [Issues](https://github.com/promptguardhq/promptguard-plugin/issues) |

  For anything else, email [support@promptguard.co](mailto:support@promptguard.co);
  report a vulnerability as the [disclosure policy](https://promptguard.co/security#reporting-a-vulnerability) says.
* **What to do when you upgrade** a self-hosted deployment or roll out the
  [desktop agent](https://docs.promptguard.co/shadow-ai/desktop-agent.md) is on [Platform upgrade notes](https://docs.promptguard.co/releases/platform.md) and
  [Shadow AI desktop agent upgrade notes](https://docs.promptguard.co/releases/desktop-agent.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.