documented api methods