updated API outline