new doc on api is [mostly] ready