Docs: API specs updates

**Still needs work**!!!

Created PR basically for getting reviews prior to merge.