Change fields without breaking anyone
Your search box is live, which means something now depends on it. One day you'll need to change your data's shape. This is what lets you do that without taking the 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.
Notice your movies list is still on version 1, even though you added a plot, a genre, a year and a poster along the way:
What does and doesn't bump the version
The rule is simple: 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 |
That's why all your field additions kept the list on version 1: every one was safe.
A breaking change, handled safely
Say you rename genre to category. That's breaking, so the list moves to version 2, but version 1 keeps working exactly as before.
An app still calling version 1 sees genre; an app on version 2 sees category. Nothing goes down.
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"
You upgrade each app to version 2 whenever you're ready, one at a time. And because a group pins each list at a fixed version, your movies-and-actors group carries on untouched until you choose to move it forward — which means the search box you just shipped keeps working while you change the data underneath it.
Made a mistake? Restore
If a change wasn't what you wanted, you don't have to rebuild the list. You can restore it to an earlier version: roll the shape back to how it was, keeping your records. It's an undo for your list's structure.
Go deeper: Exactly what bumps a version, pin-and-migrate, and the restore flow in the reference.