Improve API docs

[ozgrakkurt]

It might make things more organized if we create something like Open API spec for this so It is more streamlined.

Something like Open API might be too much but we might still be able to imrove API docs. There are no indication of when there will be an error returned for some endpoints for example.

[pedromtcosta]

Nice idea creating this issue!
Personally I also think we could (should?) refactor a bit so the API docs make more sense:

• define which endpoints are actually in use. Maybe @vsubhuman can help with that;
• refactor the way the handlers are registered in the router: currently we register everything at index.ts, but some routes have handlers coming from index itself, and some are coming from dedicated files;
• change the endpoints to not simply throw on errors, but rather return proper error codes depending on what went wrong;
• normalize the endpoints. Some are v2, some aren't and it's not clear if what is not v2 is deprecated;

I was thinking of creating a /v0/ for the API and moving everything that is still in use there.