Accurately describe how to use the API, provide sample code, notes, and return value type definitions.