narrowed type definitions for all API calls