[docs] [api] updated to match spec