I still try think /v1 /v2 is a break, I don't trust you will keep v1 forever, otherwise you'll never introduce this execuse.

I'd like to introduce more fields or flags to control the behavior as params, not asking user to change the whole base url for single new API.

I like this pattern.

When an API commits to /v1 it doesn't mean it will deprecate /v1 when /v2 or /v3 come out, it just means we're committing to supporting older URI strategies and responses.

/v2 and /v3 give you that flexibility to improve without affecting existing customers.