[WIP] more work on the external API

looks almost good now ...