How do you integrate a coaching API into a fitness app?

There is no cloud to read your users’ health data from.

This is the single fact that decides your architecture, and it surprises most teams once. Health Connect stores data on the device, encrypted, not against a Google account, and Google publishes no server-side API for it: an Android app must read locally and upload. HealthKit is the same story on iOS, where the documented path is an observer query plus background delivery in your own app, then an upload to your own endpoint. There is no token you can present to Apple or Google from a server to fetch a user’s history.

So you own a sync endpoint whether you wanted to or not. The good news: once that exists, adding coaching is one authenticated call from code you already run, against data already in your database. The bad news for anyone hoping to skip the backend: there is no client-only version of this, with or without us.

Four steps, in the order that de-risks fastest.

1. Get a key without a meeting. Self-serve signup returns a test key once, stored on our side only as a hash, with 300 free credits a month and no card. Put it in your server secret store, not in your mobile bundle and not in a client-side environment variable.
2. Prove one endpoint against your real data shapes. Start with the readiness brief at 3 credits or coach chat at 2 credits per message: cheap, interactive, and the two your users notice. Send a real athlete’s context, not a fixture. The whole point of a sandbox is finding out that your sleep field is a string before launch week.
3. Wire metering into your own ledger on day one. Persist X-Request-Id and X-Credits-Charged next to your own event row. Retrofitting this after a surprising invoice is miserable; doing it during the first integration costs one column.
4. Handle the failure table before you ship, not after. Every error in the API shares one envelope, so this is a single handler and a single test, not a per-endpoint chore. The table is below.

Sequencing matters more than speed. Teams that do step 3 last are the ones who spend a Friday reconciling. The quickstart with copy-paste requests for every endpoint lives in the docs, and the whole reference is available as one file for a coding agent if you would rather have your assistant write the client.

Send context per call. Do not build a sync.

There is no onboarding handshake, no account linking and no copy of your user table on our side. Each call carries the context that call needs, in the request body, and the response comes back structured enough to render directly. That keeps three things true at once: your data stays in your database, your privacy story stays yours to tell, and you can change what you send without a migration on either side.

Practically, the athlete context worth sending is the context a human coach would ask for: the last few sessions, the current program, the stated goal, and whatever recovery signal you actually have. Missing signals degrade the answer, they do not break the call, which matters a lot when a user denied a health permission. If you have nothing but a workout log, start there and add signals as your sync improves.

Rate limits are per tier, and per minute.

Interactive endpoints are the ones that need headroom; scheduled ones do not. 10 requests per minute on the sandbox is enough to build against and not enough to launch on. Launch gives you 60 and Growth gives you 300. If your weekly reports all fire at the same Sunday timestamp, queue them and spread them: a batch job racing an interactive chat endpoint for the same per-minute budget is the most common self-inflicted 429 we see. Exact per-tier numbers and overage rates are on the pricing table, and the calculator reads the same config the billing engine does.

One error envelope. Seven things that can go wrong.

Every failure returns {"error": {"type", "code", "message", "request_id"}}, so you write the handler once. Log request_id on every branch; it is the only thing either side needs to find a specific call.

Two of these are worth a product decision rather than a code path. A 402 is your feature going dark for a paying user, so decide now whether that degrades to a cached brief, a generic message or a hidden tab. And free_tier_paused exists because the free sandbox runs on a shared monthly budget: it is a build-time convenience, never a launch plan.

Before you open an editor.

Where the platform claims come from.

The on-device constraint is the load-bearing claim on this page, so here is where to check it rather than taking our word: Google’s Health Connect developer documentation for the client-only data model, and Apple’s HealthKit documentation for the on-device store and the observer-query plus background-delivery sync path. Checked September 2026. Credit weights, rate limits and error types on this page are generated from the same configuration the gateway bills from, and the contract itself is published as OpenAPI 3.1.

Integration is the easy half of the decision.

Now that the shape is clear, the harder questions are whether to buy this at all and what it costs. For the build case, honestly argued, CoachLayer vs building it yourself. For list prices across the whole landscape, how much a fitness coaching API costs. For rep counting and form checks in the camera, CoachLayer vs camera SDKs. And for the quality side of the trade, measured on production traffic with the weaknesses published, the benchmark.