update public api to match docs