various updates to API 3 draft