added API docs with possible solution to #2