# Policy Versions

## Overview

Every moderation policy keeps a history of **versions**. A version is a complete, immutable copy of the policy's configuration. One of them is the **published version**: the one moderation actually runs.

Versions let you:

- Prepare a change to a policy without affecting live moderation.
- Review exactly what a policy looked like at any retained point in time.
- Revert to an earlier configuration in a single call.

>
> **Info:** Policy versioning is in beta. The endpoints are available in the Node, Python and Go server SDKs, and as REST endpoints for every other language.
>

## How versioning works

- Each policy (identified by `key` and, for multi-tenant apps, `team`) has numbered versions: 1, 2, 3, and so on.
- `published_version` names the version moderation runs. It is returned on [Get Config](https://getstream.io/moderation/docs/python/configuration/policies/) as `config.published_version`.
- **Saving a version** stores a new version without making it live.
- **Publishing a version** makes it live. Publishing an older version is how you revert. No new version is created; the published pointer just moves.
- [Upsert Config](https://getstream.io/moderation/docs/python/configuration/policies/) keeps working as before: it saves a new version **and** publishes it in the same request, so the change is live immediately.

| Endpoint                                                          | What it does                                            |
| ----------------------------------------------------------------- | ------------------------------------------------------- |
| `POST /api/v2/moderation/config`                                  | Upsert Config. Saves a new version and publishes it.    |
| `POST /api/v2/moderation/config/versions`                         | Saves a new version without publishing it.              |
| `GET /api/v2/moderation/config/{key}/versions`                    | Lists the retained versions and which one is published. |
| `GET /api/v2/moderation/config/{key}/versions/{version}`          | Returns the full configuration stored in one version.   |
| `POST /api/v2/moderation/config/{key}/versions/{version}/publish` | Publishes a version (or reverts to it).                 |

## Tutorial: change a policy safely

This walkthrough uses a policy with the key `chat:messaging`. The same steps apply to any key.

### Step 1: Check the current state

Get the policy and note `config.published_version`. Then list its versions to find the **latest** version number: you need it to save a new version.

```python label="Python"
config = client.moderation().get_config("chat:messaging").data.config
print(config.published_version)  # e.g. 3

res = client.moderation().list_config_versions(key="chat:messaging").data
latest = res.versions[0].version  # newest first
```

```bash label="cURL"
curl "https://chat.stream-io-api.com/api/v2/moderation/config/chat:messaging/versions?api_key=$API_KEY" \
  -H "Authorization: $SERVER_TOKEN" \
  -H "Stream-Auth-Type: jwt"
```

Example response:

```json
{
  "published_version": 3,
  "versions": [
    {
      "version": 3,
      "created_at": "2026-11-10T09:12:00Z",
      "created_by": "admin-1",
      "published": true
    },
    {
      "version": 2,
      "created_at": "2026-11-03T14:40:00Z",
      "created_by": "admin-1",
      "published": false
    },
    {
      "version": 1,
      "created_at": "2026-10-28T08:05:00Z",
      "created_by": "",
      "published": false
    }
  ],
  "duration": "4.21ms"
}
```

### Step 2: Save a new version without publishing it

Send the complete policy, exactly as you would to Upsert Config, plus `base_version`: the latest version you read in step 1. The new version is stored but moderation keeps running the published one.

```python label="Python"
res = client.moderation().save_config_version(
    key="chat:messaging",
    base_version=latest,
    ai_text_config=AITextConfig(
        rules=[
            AITextRule(label="SPAM", action="flag"),
            AITextRule(label="HARASSMENT", action="remove"),
        ],
    ),
    block_list_config=BlockListConfig(
        rules=[BlockListRule(name="profanity_en", action="remove")],
    ),
).data
print(res.version.version, res.version.published)  # 4, False
```

```bash label="cURL"
curl -X POST "https://chat.stream-io-api.com/api/v2/moderation/config/versions?api_key=$API_KEY" \
  -H "Authorization: $SERVER_TOKEN" \
  -H "Stream-Auth-Type: jwt" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "chat:messaging",
    "base_version": 3,
    "ai_text_config": {
      "rules": [
        { "label": "SPAM", "action": "flag" },
        { "label": "HARASSMENT", "action": "remove" }
      ]
    },
    "block_list_config": {
      "rules": [{ "name": "profanity_en", "action": "remove" }]
    }
  }'
```

Example response:

```json
{
  "version": {
    "version": 4,
    "created_at": "2026-11-17T10:00:00Z",
    "created_by": "",
    "published": false
  },
  "published_version": 3,
  "duration": "12.40ms"
}
```

### Step 3: Review a version

Fetch the full configuration stored in any retained version, published or not. The response has the version's metadata and its `config`, in the same shape Get Config returns.

```python label="Python"
res = client.moderation().get_config_version(key="chat:messaging", version=4).data
print(res.version.published, res.config.ai_text_config)
```

```bash label="cURL"
curl "https://chat.stream-io-api.com/api/v2/moderation/config/chat:messaging/versions/4?api_key=$API_KEY" \
  -H "Authorization: $SERVER_TOKEN" \
  -H "Stream-Auth-Type: jwt"
```

### Step 4: Publish the version

Publishing makes the version live. Moderation starts using it right away. The response returns the configuration now in effect, with `published_version` set to the version you published.

Pass `user_id` to record who published the change in the moderation audit log.

```python label="Python"
res = client.moderation().publish_config_version(
    key="chat:messaging",
    version=4,
    user_id="admin-1",
).data
print(res.config.published_version)  # 4
```

```bash label="cURL"
curl -X POST "https://chat.stream-io-api.com/api/v2/moderation/config/chat:messaging/versions/4/publish?api_key=$API_KEY" \
  -H "Authorization: $SERVER_TOKEN" \
  -H "Stream-Auth-Type: jwt" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "admin-1" }'
```

### Step 5: Revert if needed

To roll back, publish the earlier version. In this example version 3 becomes live again, and version 4 stays in the history so you can publish it again later.

```python label="Python"
client.moderation().publish_config_version(key="chat:messaging", version=3)
```

```bash label="cURL"
curl -X POST "https://chat.stream-io-api.com/api/v2/moderation/config/chat:messaging/versions/3/publish?api_key=$API_KEY" \
  -H "Authorization: $SERVER_TOKEN" \
  -H "Stream-Auth-Type: jwt" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Publishing the version that is already published changes nothing.

## Save and publish in one step

If you don't need a review step, keep using [Upsert Config](https://getstream.io/moderation/docs/python/configuration/policies/). It saves a new version and publishes it in the same request. The response's `config.published_version` is the version it created.

Upsert Config and saved versions share one history. If you save version 4 without publishing it, and then call Upsert Config, the upsert creates version 5 and publishes it. Version 4 stays unpublished in the history.

## Concurrent edits and `base_version`

`base_version` protects you from overwriting someone else's change. It must equal the latest version of the policy at the time you save:

- If another version was saved after the one you read, the save is rejected with a `400` error (`moderation config "chat:messaging" has a newer version than base_version 3, reload it and save again`) and nothing is stored. Reload the latest version, reapply your change and save again.
- Use `base_version: 0` for a policy that has no versions yet. That covers a key that doesn't exist (the save creates the policy and publishes it as version 1, so it is usable right away) and a policy created before versioning was available.

Upsert Config doesn't take `base_version`. It always saves on top of the latest version.

## Teams

For [multi-tenant](https://getstream.io/moderation/docs/python/configuration/multitenancy/) apps, every versioning call takes the same `team` as the policy:

- Save and publish: `team` in the request body.
- List and get: `team` as a query parameter.

Versions are numbered separately for each `key` and `team` pair.

## Retention

Stream keeps the **10 most recent versions** of each policy. Older versions are deleted automatically, except the published version, which is always kept. A policy therefore has at most 11 versions: the 10 newest plus a published one older than them.

Getting or publishing a version that was deleted returns `404`.

## Things to know

- **Each version is a complete policy.** Saving a version replaces the whole configuration, just like Upsert Config. Send every engine config the policy should have, not only the part you changed.
- **Policies created before versioning** have no `published_version` and an empty version list. The first write turns the current configuration into version 1. With Upsert Config, your change becomes version 2 and is published. With a saved version (using `base_version: 0`), your change becomes version 2 and version 1 stays published.
- **Publishing checks blocklists.** If a version references a blocklist that has since been deleted, publishing it fails with `400` (`Blocklist not found`). Save a new version without that blocklist instead.
- **Deleting a policy deletes its versions.** If you create the same key again, numbering starts over at version 1.
- **Query Configs returns published configurations only.** Unpublished versions only appear through the version endpoints.

## Request parameters

### Save Config Version

`POST /api/v2/moderation/config/versions`

Takes every field of [Upsert Config](https://getstream.io/moderation/docs/python/configuration/policies/), plus:

| key          | required | type    | description                                                                                                     |
| ------------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| base_version | true     | integer | The latest version the change is based on. `0` for a policy without versions. Rejected when a newer one exists. |

Response:

| key               | type    | description                                                            |
| ----------------- | ------- | ---------------------------------------------------------------------- |
| version           | object  | The saved version: `version`, `created_at`, `created_by`, `published`. |
| published_version | integer | The version moderation currently runs.                                 |

### List Config Versions

`GET /api/v2/moderation/config/{key}/versions`

| key  | required | type   | description                 |
| ---- | -------- | ------ | --------------------------- |
| key  | true     | string | Key of the policy.          |
| team | false    | string | Team the policy belongs to. |

Response:

| key               | type    | description                                                                                                                   |
| ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| published_version | integer | The version moderation currently runs. Omitted for a policy not written since versioning launched.                            |
| versions          | array   | Retained versions, newest first, including the published one. Each has `version`, `created_at`, `created_by` and `published`. |

### Get Config Version

`GET /api/v2/moderation/config/{key}/versions/{version}`

| key     | required | type    | description                 |
| ------- | -------- | ------- | --------------------------- |
| key     | true     | string  | Key of the policy.          |
| version | true     | integer | Version to retrieve.        |
| team    | false    | string  | Team the policy belongs to. |

Response:

| key     | type   | description                                                                  |
| ------- | ------ | ---------------------------------------------------------------------------- |
| version | object | Metadata of the version: `version`, `created_at`, `created_by`, `published`. |
| config  | object | The full configuration stored in this version.                               |

### Publish Config Version

`POST /api/v2/moderation/config/{key}/versions/{version}/publish`

| key     | required | type    | description                                                |
| ------- | -------- | ------- | ---------------------------------------------------------- |
| key     | true     | string  | Key of the policy.                                         |
| version | true     | integer | Version to publish. Publishing an older one reverts to it. |
| team    | false    | string  | Team the policy belongs to.                                |
| user_id | false    | string  | User to record as the actor in the moderation audit log.   |

Response:

| key    | type   | description                                                    |
| ------ | ------ | -------------------------------------------------------------- |
| config | object | The configuration now in effect, with its `published_version`. |

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/python/configuration/policy-versions/](https://getstream.io/moderation/docs/python/configuration/policy-versions/).