writing Speare API functions [no testing yet]