api clarifications