this API definition is inclomplete; you must add all expected parameters types and defaults, and describe what we will return