I've been working a lot with the API recently and there's lots of good stuff there.
But there are also deficiencies. Yes I have read the API wiki. It is good for getting started but it is incomplete also.

Most of the commands concerning configuration seem to work just fine.
It is the commands that are more like "tools" that I run into trouble with more often.
I always verify that I can use the terminal CLI in winbox before trying with the API

Ping command - I can only use the ping "bandwidth" flavor. There needs to be one that reports traditional ping statistics - latency and icmp status codes

Traceroute - I sent the following to try traceroute to an internet host and just received a trap without a message
/tool/traceroute
=address=209.191.92.114

802.11 align monitor - Seems to turn on audio aiming just fine but responses that come back are empty.

802.11 snooper snoop - Get back empty responses

A wiki page with categorized API command examples and more details for particular commands when the API and CLI differ and would be greatly appreciated. Searching through forum posts and learning via trial and error isn't community friendly.

yes, the commands that require extended results (torch, ping, in previous versions interface monitoring) are not working via API or their functionality is limited for now... will be fixed in future versions, I hope =)