big API update to implement as per current docs