Fill out `api.yaml`

[dj2]

The API docs are being generated from api.json but it's mostly empty. This needs to get filled out with all the bits of the API (which should resolve all the warnings from the generation script).