Updated API docs to match JSON schemas and incorporate feedback from latest discussions with Antranig and the RD2 committee.