API v1 spec

This is still a work-in-progress, but any feedback is more than welcome.
Sure. I'd like to spec things out even if we don't implement everything immediately.