one more change to the api docs to my final read of the specs