clarify working docs, distinguish sub apis, add first "post" api fn