added API endpoints and updated docs with example response