finalized api with readme changes