docs: Document the API

This is a first pass, which should already be pretty good, but we'll
make it better with user feedback.

It's in Markdown, so that we can reuse it as it is on the website, with
as few changes as possible.