Ended up answering my own question after a lot of aimless clicking around; the documentation for creating Calculated Metrics in v1.4 of the API is subordinate to the documentation for Segments:
there are a few docs to start with. i started with building the metrics in analytics and had a look in the api explorer (to see how i need to weite the JSON).
when i made my first steps i had both the explorer and analytics opened at the same time to see what i do in API by watching the results in Adobe Analytics.