api: add annotations

@njbartlett can you please take a look at them, check if I got them right?