~ api function signature