added more api details, including answers to @cdeil's questions