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.
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
keyand, for multi-tenant apps,team) has numbered versions: 1, 2, 3, and so on. published_versionnames the version moderation runs. It is returned on Get Config asconfig.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 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.
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 firstcurl "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:
{
"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.
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, Falsecurl -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:
{
"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.
res = client.moderation().get_config_version(key="chat:messaging", version=4).data
print(res.version.published, res.config.ai_text_config)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.
res = client.moderation().publish_config_version(
key="chat:messaging",
version=4,
user_id="admin-1",
).data
print(res.config.published_version) # 4curl -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.
client.moderation().publish_config_version(key="chat:messaging", version=3)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. 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
400error (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: 0for 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 apps, every versioning call takes the same team as the policy:
- Save and publish:
teamin the request body. - List and get:
teamas 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_versionand 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 (usingbase_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, 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. |