Version control

Every time you save an item, a new version is created. You can view a previous version of an item at any time, or you can revert to a previous version.

You don't need to set the version number manually, although you can if you want to. By default, the version number will be automatically incremented each time you save an item.

Examples

The version number increment logic is fairly basic. First, we find the last numeric substring (treating . as a separator). We parse this substring as a number, increment it, then substitute it back into the original version string.

"" (empty string) will be incremented to "1".
1 will be incremented to 2.
0.12 will be incremented to 0.13.
0.19 will be incremented to 0.20.
0.1.0 will be incremented to 0.1.1.
0.1.0b will be incremented to 0.1.1b.
4test123 will be incremented to 4test124.

View an item's history

We can view the history of an item in the dashboard by clicking on the button at the top of the item details page.

This will show a list of all previous versions of the item. We can also compare versions to see exactly what changed in each version.

To view an item's history via the API, we can use the Fetch item events endpoint:

curl https://api.jsonpad.io/lists/sample-list/items/ebba6c9b-2a2b-41eb-b2a3-128e49661cb7/events \
  -H "x-api-token: <YOUR TOKEN>"

Note that each event returned in the response will have a version field.

Event snapshots are not returned by default, since they contain a full copy of the item and would make the response very large. To fetch the item data for each version, add includeSnapshot=true to the request.

View a specific item version

When fetching an item or an item's data, we can specify which version we want to view. If we don't specify a version, the latest version will be fetched.

curl https://api.jsonpad.io/lists/sample-list/items/ebba6c9b-2a2b-41eb-b2a3-128e49661cb7?version=1 \
  -H "x-api-token: <YOUR TOKEN>"

Restore an item

Items can be restored to a previous version in the dashboard by clicking on the button next to a version in the item's history page.

To restore an item via the API, we can use the Restore an item endpoint with the id of the event we want to restore the item from:

123

curl https://api.jsonpad.io/lists/sample-list/items/ebba6c9b-2a2b-41eb-b2a3-128e49661cb7/events/6a51f69c-16d4-4f3f-bc9f-b8d02250ffb4/restore \
  -X POST \
  -H "x-api-token: <YOUR TOKEN>"

When an item is restored, the data, description, readonly and activated fields will be restored to the values they had when the specified version was created.

A new version will be created containing the restored state, and the version number will be incremented.

When fetching an item's events, we can add restorable=true to only return events that the item can be restored from.

Restore a deleted item

When an item is deleted, its history is kept. We can still fetch the events for a deleted item (as long as we refer to the item by its id, since alias values are removed when an item is deleted), and we can restore the item from any of those events using the same Restore an item endpoint.

The restored item will have the same id as the deleted item. Restoring a deleted item counts towards the maximum number of items allowed in a list.

When using the API, restoring items requires the restore (or restore-with-identity) token permission.

2026-09-12