finished api as per tim's request.