API v1 spec

This is still a work-in-progress, but any feedback is more than welcome.
Is this based on something. We should really just use endpoints so we can generate the clients, unless there is a better idea.