#566 - document new API function