finalise new directory API code per #10