Started with fixing the API

Added type spec and short description. Still quite a few open questions…