revise API endpoint documentation

review and amend api_endpoints.md:

• review /bg (GET), /bg (POST), /clear
• add /clear/all
• handle todos in file
• write short section introductions