Change fields without breaking anyone
Change your data's shape without taking the live box down.
What a version is
A list's version is the shape it presents to the outside world: which fields exist and what they're called. It's the number in every search URL, /movies/1. Your movies list is still on version 1, even after a plot, a genre, a year and a poster:
What does and doesn't bump the version
A change that could break an app already reading your data creates a new version; a change that couldn't, doesn't.
| Change | Safe for existing apps? | New version? |
|---|---|---|
| Add a field | Yes, old apps just ignore it | No |
| Add or edit records | Yes | No |
| Rename a field | No, apps asking for the old name would break | Yes |
| Remove a field | No | Yes |
A breaking change, handled safely
Rename genre to category and the list moves to version 2, while version 1 keeps working exactly as before:
GET https://api.searchstack.dev/search/Demo/movies/1?query=matrix → still has "genre"
GET https://api.searchstack.dev/search/Demo/movies/2?query=matrix → now has "category"
Upgrade each app to version 2 whenever you're ready, one at a time. A group pins each list at a fixed version, so movies-and-actors carries on untouched until you choose to move it forward.
Made a mistake? Restore
Restore rolls a list's shape back to an earlier version, keeping your records — an undo for structure, with nothing to rebuild.
Go deeper: Exactly what bumps a version, pin-and-migrate, and the restore flow in the reference.