Flags API reference

Flags API · History

post/v1/workspaces/{workspace_id}/changes/{change_id}/revertAuth

Restore a version

Writes the change's `before` back as a new change (`reverts_change_id` points to this one), through the same checks as an edit: validation, the protected-environment and note rules, and publishing. Supported for `setting_value.updated`, `segment.updated` and `setting.updated`. Send the entity's current `version` (the value or segment); a setting is restored only while it is still as this change left it. Needs `flags.value.update` plus what the original edit needed (`flags.value.update` on the environment and setting, or `flags.update`; `flags.protected.update` in protected environments).

Path parameters

change_id*string · uuid

Id of the change.

workspace_id*string · uuid

Id of the workspace.

Headers

Idempotency-Keystring

Idempotency key (1-256 characters, `[A-Za-z0-9._:-]`). A retry with the same key and body returns the first response for 24 h.

Request body

versioninteger

The current `version` of the entity (the setting value or the segment) you are restoring over; 409 `VERSION_CONFLICT` when it moved. Settings have no version: for `setting.updated` it is ignored and the restore is refused with 409 when the setting no longer matches the change's `after`.

Example: 4

notestring

A change note (at most 500 characters), saved on the new history entry. Environments with `require_note` refuse value writes without one.

Example: "Roll back FLAG-142"

Response · 201 The new change (the restore).

id*string · uuid

Id of the change.

project_id*string · uuid

The project.

config_id*string · uuid

The config, for changes of a config, its settings, values or SDK keys.

environment_id*string · uuid

The environment, for value writes and SDK key changes.

entity_type*string

What changed: `project`, `environment`, `config`, `setting`, `setting_value`, `segment` or `sdk_key` (open: more may come).

Example: "setting_value"

entity_id*string · uuid

Id of the entity (for `setting_value`, the setting).

Example: "5b1f0c2e-8d4a-4e6b-9f3a-1c2d3e4f5a6b"

entity_key*string

The key of the entity at the time (an environment key for SDK keys).

Example: "new_checkout"

action*string

`<entity>.<verb>`, e.g. `setting_value.updated`, `setting.created`, `segment.deleted`, `sdk_key.rotated`, `confidential.revealed` (open: more may come).

Example: "setting_value.updated"

actor*object

Who made the change.

note*string

The note sent with the write.

Example: "Ticket FLAG-142"

revisions*array

Config revisions the change published (empty when it changed nothing SDKs download).

reverts_change_id*string · uuid

The change this one restored (`POST …/changes/{id}/revert`).

summary*array

Human-readable lines, e.g. "Production: value false → true" or "rule 2 percentage 10 → 25". Confidential lists show as counts ("+3 / −1 values"), never values. Empty when the change is too large to summarise (`diff_too_large`).

Example: ["Production: value false → true"]

diff_too_large*boolean

Whether `before` and `after` together exceed 64 KB: then there is no diff and no summary; compare the two revisions instead.

size_bytes*integer

Bytes `before` and `after` take up in history storage (they count toward the 200 MiB per project).

created_at*string · date-time

When the change was made.

before*object

The entity before the change (null for a create). Confidential lists show as `{hashed, count, list_id, editable}`, never values. Null when `diff_too_large`: read the revisions instead.

after*object

The entity after the change (null for a delete), in the same form as `before`. Null when `diff_too_large`.

diff*array

JSON Patch (RFC 6902) from `before` to `after`. Null when `diff_too_large`.

Example

Request

POST https://api.flags.productcraft.co/v1/workspaces/{workspace_id}/changes/{change_id}/revert
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "version": 4,
  "note": "Roll back FLAG-142"
}

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "project_id": "00000000-0000-0000-0000-000000000000",
  "config_id": "00000000-0000-0000-0000-000000000000",
  "environment_id": "00000000-0000-0000-0000-000000000000",
  "entity_type": "setting_value",
  "entity_id": "5b1f0c2e-8d4a-4e6b-9f3a-1c2d3e4f5a6b",
  "entity_key": "new_checkout",
  "action": "setting_value.updated",
  "actor": {},
  "note": "Ticket FLAG-142",
  "revisions": [
    {
      "config_id": "00000000-0000-0000-0000-000000000000",
      "environment_id": "00000000-0000-0000-0000-000000000000",
      "revision": 7,
      "url": "https://api.flags.productcraft.co/v1/workspaces/9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b/configs/1f0c…/environments/7a2e…/revisions/7",
      "previous_url": "string"
    }
  ],
  "reverts_change_id": "00000000-0000-0000-0000-000000000000",
  "summary": [
    "Production: value false → true"
  ],
  "diff_too_large": false,
  "size_bytes": 0,
  "created_at": "2026-01-01T00:00:00.000Z",
  "before": {},
  "after": {},
  "diff": [
    {
      "op": {},
      "path": "/rules/1/percentages/0/percentage",
      "value": 25
    }
  ]
}