updated search api docs to include pagination changes

Signed-off-by: Nathan Hsieh <hsieh.nathan@gmail.com>
please also document what `num_results`  means (confirm to the reader that its the total number found?)