initial API and implementation. needs testing