fleshing out the api and docs