API v1 spec

This is still a work-in-progress, but any feedback is more than welcome.
```
s/appropriate  Content-Type/appropriate `Content-Type`/
```