You know, it’s surprisingly vague even in the official documentation.

You just described literally all of Lemmy’s documentation.

I had to read the source code for Lemmy to find out what API endpoint to hit, how it worked, and what to expect on return for a script that I was writing. You need to do that for some documented API endpoints as well. Calling it “vague” is a nice way to put it.