What's a reasonable deprecation period for an API?

It depends on the amount of work that your customers need to do to migrate, the size of your user base, and your ability to communicate (and incentivize) the changes with them. The best option is to provide enough value that it is worth it to your users to pay the cost of migration. That’s not necessarily an easy thing to do.

Depends on your users. A company I work with has clients who sign agreements annually, so their standard deprecation period is... one year. If people are building commercial products or internal tools on your API, you've got to give them longer IMO.

Also it makes sense to phase deprecation. Start by no longer issuing new API keys. If your API has a messages or comments field in the return object, you can add a notice that it's deprecated with a link to the new API to discourage new development.

The biggest thing (IMO) is to make the transition process painless. If there's functionality that v1 has that v2 doesn't, users who like that functionality will cling to v1. If there's an endpoint in v1 with no clear equivalent in v2, that's gonna slow adoption unless there's a clear transition process documented somewhere.

The answer depends on how many customers you are willing to loss.

From a client perspective, everything is running well, you decide to change and it will cost them $X and Y (time) to match it. If there is not great value to the customer to change, then they might seek out a competitor.

Can you not make a compatibility library that lets them use the old interface on the new API?

Can you not run both systems, just not allow new customers on the old API?

What is the motivation for your users going from v1 to v2? If there is a business advantage, they will & you can deprecate old version sooner. If not, it takes more time & effort.