expand API, fix typo, and add example