fleshed out api spec, tweaks and clarifications pending