document a few API details