at this point the codebase is in daily flux, it really comes down to RTFS. the transition from websockets to http seems to be mostly in-place, so there may be some opportunity to begin normalizing the docs.
totally agreed on the need for more complete and accurate documentation, but without an auto-documenting sourcecode framework, I would expect API documentation to lag. in the meantime we just live life on the edge - it will improve over time.
edit: word
because, sometimes, having your program vomit all over your console is the best way to remain focused on the problem.