Helios Health API and agent access
Find the Helios API specification, connect an MCP client, and request the minimum OAuth permissions.
Helios Health provides a public health endpoint, a REST API for its signed-in clients, and an OAuth-protected MCP server for agents. Personal records require authentication, account access, and permission for the requested action.
Public discovery endpoints
- Helios developer resources: Start with the REST, MCP, OAuth, and client setup links.
- OpenAPI specification: REST operations, typed parameters, response schemas, and authentication schemes.
- API health: Public availability and version information. No sign-in is needed.
- MCP resource metadata: The protected resource, authorization server, and
scopes_supported. - Authorization server metadata: Authorization, token, and client registration endpoints.
The specification uses https://api.getheliosapp.com as its server. A REST account endpoint requires the session cookie supplied by Helios sign-in. An MCP OAuth access token cannot replace that cookie. Use MCP for agent access to personal records.
Connect an agent
- Add
https://api.getheliosapp.com/mcpto a client that supports Streamable HTTP MCP and OAuth. - Use the advertised authorization server and its supported client registration method. Use authorization code with PKCE and the MCP resource URL.
- Ask the user to sign in and approve the minimum scopes needed for the task.
- Start with reads. Use
tools/listthrough the authenticated MCP client to discover the tools available to that connection. - Show proposed changes and get user approval before writes. Read the current version before a change. Supply the required request UUID and reason. Retry the same write with the same UUID and values.
See the MCP tool guide and client setup pages for task details. Tool availability also depends on account access and service settings. A scope alone does not guarantee that a write tool is enabled.
OAuth scopes
Request only the scopes needed for the task. Read scopes do not permit writes.
| Scope | Permission |
|---|---|
openid |
Identify the signed-in account. |
email |
Read the account email and verification status. |
offline_access |
Refresh access after the current access token expires. |
history:read |
Read completed workout history. |
history:write |
Correct or void completed workout records with approval. |
notes:read |
Read training notes. |
notes:write |
Create, update, or delete training notes with approval. |
nutrition:read |
Read nutrition records, targets, and saved meals. |
nutrition:write |
Save nutrition records, targets, and meals with approval. |
exercises:read |
Read the exercise library. |
exercises:write |
Create or update custom exercises with approval. |
workouts:read |
Read workout plans. |
workouts:write |
Create, update, or delete workout plans with approval. |
For example, request workouts:read to inspect workout plans. Add workouts:write only when the user needs to save a plan change. Use the resource metadata as the current machine-readable scope list.
Rate limits and retries
Public GET and HEAD requests to /health, /openapi.json, and /api/v1/openapi.json share a quota of 120 requests per 60-second window per client IP. The quota uses a shared database counter. Requests through a proxy can share the proxy's IP quota. These public REST responses include:
RateLimit-Policy: "public-api";q=120;w=60
RateLimit: "public-api";r=119;t=60
Cache-Control: private, no-store
An HTTP 429 response has zero remaining requests and includes Retry-After in seconds. Redirects count as separate HTTP requests. Read the final response after a redirect to find the remaining quota. Public discovery stays available if the quota store is unavailable; those responses omit quota fields rather than inventing a remaining count. The counter stores a keyed hash of the client IP, not the address itself.
This quota does not apply to signed-in REST account routes. Their existing access checks and separate sign-in and support limits remain in place. Browser clients can read the quota headers through CORS.
The MCP request limit is 120 requests per 60-second window for each account and OAuth client. When the limiter is configured, authenticated responses include:
RateLimit-Policy: "mcp";q=120;w=60
RateLimit: "mcp";r=119;t=60
r is the remaining request allowance. t is the number of seconds until the current window resets. An HTTP 429 response also includes Retry-After in seconds. Wait for that interval before you retry. These fields use the IETF RateLimit draft format. The public REST and MCP policies are separate; neither is a shared quota for all REST routes.
For a failed or timed-out write, keep the same request UUID and values when you retry. Do not issue a new write merely because a response was lost. Check the saved result or receipt first.
Access and testing
Public documentation and API health checks are available without an account. To connect an agent, use the client setup guide, sign in through the advertised OAuth server, and approve the requested permissions. An agent connection does not require a separate API key or a sales request. Record access still depends on the user's account and OAuth consent.
See pricing for published Free, trial, and beta information. Check the signed-in account for current eligibility before you promise access to a tool. Helios does not provide a public sandbox or self-serve API keys. Do not use a customer's records as test data without their approval.
An unauthenticated audit can verify discovery metadata. It cannot verify protected tool listing. Use an authorized MCP client for that check. There is no published official CLI package at present; use an MCP client or the public HTTP endpoints below.
curl -fsS https://www.getheliosapp.com/openapi.json
curl -fsS https://api.getheliosapp.com/health
curl -fsS https://api.getheliosapp.com/.well-known/oauth-protected-resource/mcp
curl -i -H 'Accept: text/markdown' https://www.getheliosapp.com/
Versioning and deprecation policy
The current REST API uses /api/v1. A breaking change requires a new major path, such as /api/v2. Compatible additions can add optional fields or operations within v1. Clients must accept response fields they do not use. The current v1 API has no announced deprecation or retirement date.
Before a stable REST version is retired, Helios will publish a migration guide and the affected endpoints on this page. A deprecated version will send the Deprecation response header as an RFC 9745 Structured Field Date, with a Link whose relation is deprecation and whose target is the migration guide. If a retirement date is set, the affected responses will also send Sunset as an RFC 8594 HTTP date. The migration guide will state the replacement version and the retirement date. A current version does not send these headers merely to show that a policy exists.
MCP uses its own negotiated protocol version. The REST version policy does not change MCP tool permissions or OAuth scope requirements. See RFC 9745 and RFC 8594 for the header formats.
Read the site as Markdown
Send Accept: text/markdown to the homepage or a page with a Markdown version. HTML remains available with Accept: text/html. Negotiated pages include Vary: Accept. Missing paths requested as Markdown return an HTTP 404 with a Markdown explanation and recovery links. Direct .md URLs remain available.
For setup help, email Helios Health support or use the support form.