improved api spec