fleshing out the API, still more to do...