update API and increase/clarify specs