Versioning
Your search box is live. Now real apps depend on it — and one day you'll need to change your data's shape. Versioning is what lets you do that without breaking anything already using your search.
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.
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.
That's the safety net that lets you change a live search with confidence. Next: let a teammate help you manage it.
Exactly what bumps a version, pin-and-migrate, and the restore flow are covered in the Versioning reference.