clarifying api documentation