update API to match the Haskell and Python versions