Review REST API docs

[taylortom]

REST docs need a detailed review to check for completeness & readability/usability. In particular:

• Any extra descriptions needed
• Any params/body data that should be accompanied by text description