API v2 spec - NOW WITH EXAMPLES