improved documentation and change on parameters on two api calls