API functionality

take three.... let me know your comments! @travellina @albertostg @hbrown