Sort:  

Maybe some code usage examples could help? The descriptions are fine. The parameters are fine. Usage examples or code examples might make it crystal clear? (or a demo script, etc)

OK I will build some go and js clients for it and show them off. That may not be till 3rd jan though-- I am headed home for christmas.