updating docs with more details on response formats