readme: api return values and cleanup code