clarify the purpose of the api spec
add possible IDENTITY_NOT_FOUND error to post/create
add plugin docs and introduce required field for plugin input definition