fixed minor nuances in API logic, updated docs