Thanks for trying out the API. You're right our docs need some improvement here, we write these from the backend and generate them using our own custom swagger parser. We'll fix these asap! We've started adding provider specific docs like this here, https://docs.tryvital.io/wearables/providers/Guides/Freestyl... we'll be adding the rest as soon as possible.
This is why aggregating and standardising the data is hard, some API's are not public and in some cases we use credentials to generate access tokens which we then use to query the API, since we are aiding people in accessing their own data, we take a stance that people have a right to their own health data.
If the internal API does change there is some risk of breakage, we have built a tonne of monitoring around this to ensure that we stay up to date with this and react accordingly.
As one piece of feedback, the docs could be better. For example, at https://docs.tryvital.io/api-reference/data/workouts/#stream, I see "Get Daily Activity for user_id", but the endpoint seems to actually return time series data for a single workout. I see a bunch of oversights of this flavor.
Similarly, I'm not sure how pagination works or should work. In one list query, I see a result set of size 100. I'm not sure whether this is because only 100 items were pulled from the provider, or whether I can see more using pagination. Maybe this is in the docs, but I haven't seen it.
It would be good to have some provider-specific documentation to answer questions are set expectations around things like 1) how much historical data is available 2) details about the integration and its stability. For example, I assume with Peloton you are logging in with my credentials and using their internal API. Is this against their terms of service? Is there a risk of this breaking if they change their internal API, which obviously doesn't have the same governance considerations a public API would?
Nice work overall!