minor api updates + adding examples