Agent access

1. Copy your hosted agent credentials

With hosted HealthSync storage selected, open Settings → Agent Access Details. Use Copy agent endpoint and Copy read-only agent token. If these controls are missing, finish creating hosted storage first. Upload some Apple Health data before expecting records in the response.

Save the token in your agent tool's private credential store. Give it only the copied endpoint and agent token. Do not give agents your ingest token, API_TOKEN, database connection string, or database service credentials. Anyone with the agent token can read the workspace's synced health data.

2. Make an authenticated request

Set AGENT_ENDPOINT to the complete endpoint copied from the app, and AGENT_TOKEN to its read-only token. Preserve the full URL, including any hosting path prefix; do not append /api/agent/health-data again.

curl --fail --get "$AGENT_ENDPOINT" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  --data-urlencode "limit=100" \
  --data-urlencode "offset=0"

Configure an HTTP-capable agent tool to send GET requests to that endpoint with the Authorization header. The endpoint returns JSON over HTTP; it is not an MCP server URL. Confirm your tool supports custom bearer-authenticated HTTP requests.

3. Read and paginate the response

• The combined endpoint returns agent_schema_version, workspace_id, range, page, catalog, metrics, workouts, syncs, metric_daily_summaries, and workout_daily_summaries.
• Raw records include timezone and local_date fields when available. Use them when interpreting a user's calendar days.
• Pagination defaults to 100 records per collection; limit accepts 1–500 and offset starts at 0. When page.has_more is true, request the next page by adding page.limit to page.offset. Continue until has_more is false.
• The combined endpoint paginates metrics, workouts, and syncs independently using the same offset. Daily summaries describe the full filtered range and repeat across pages; do not add them together across responses.
• Use from and to with timezone-aware ISO 8601 timestamps to filter a range. The type filter restricts metrics, not workouts. The range selects metrics/workouts starting at or after from and ending at or before to.

curl --fail --get "$AGENT_ENDPOINT" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  --data-urlencode "from=2026-10-01T00:00:00Z" \
  --data-urlencode "to=2026-10-08T00:00:00Z" \
  --data-urlencode "type=stepCount" \
  --data-urlencode "limit=100" \
  --data-urlencode "offset=0"

For individual collections, replace the final /health-data path segment with /metrics, /workouts, or /syncs. These return items and page. Metrics accept type, from, and to; workouts accept activity_type, from, and to; syncs accept device_id. All accept limit and offset and require the agent token.

4. Refresh or troubleshoot access

Use Refresh read-only agent token in Agent Access Details to replace the credential. Update your agent's saved token immediately; previous agent tokens for that workspace stop working. This preserves synced records. Reset Hosted Storage is a separate operation that can delete the current hosted data.

A 401 means the bearer header is missing or empty. A 403 means the token is invalid, revoked, or the wrong kind. Empty arrays can mean no uploads yet or a filter outside the available dates. Sync from the iPhone and retry with the correct endpoint and date range.

Standard self-hosted reads

A standard self-hosted installation uses API_TOKEN for GET /api/apple-health/metrics, /workouts, and /syncs under the same /api/apple-health prefix. These credentials also allow uploads, so this is not read-only agent isolation. Use them only with a trusted integration that should have that authority.

curl --fail -H "Authorization: Bearer $API_TOKEN" \
  "https://api.example.com/api/apple-health/metrics?type=stepCount&limit=100&offset=0"

Self-hosted metric and workout filters use start_at and end_at rather than from and to. Metrics also accept type; workouts accept activity_type. All three endpoints accept device_id, limit, and offset. API_TOKEN is not accepted by /api/agent/*.

Optional: operate your own workspace service

The FastAPI backend can provision isolated workspaces with separate ingest and read-only agent tokens. On your existing HTTPS deployment, set HOSTED_PUBLIC_BASE_URL to its externally reachable base URL and HOSTED_PROVISIONING_ENABLED=true, then recreate or restart the API with that environment. DATABASE_URL, API_TOKEN, and TOKEN_HASH_SECRET remain required.

Enabling provisioning exposes a workspace-creation endpoint without bearer authentication. Decide who should be able to reach it and apply appropriate access and rate controls before exposing your service. Leave provisioning disabled if you only need standard self-hosted storage.

curl --fail -X POST "https://api.example.com/api/hosted/workspaces" \
  -H "Content-Type: application/json" \
  -d '{"label":"Personal Health"}'

The response contains workspace_id, backend_url, ingest_token, agent_endpoint, and agent_token. Save the credentials securely. In the app's own-backend settings, enter backend_url and ingest_token. Give your reader only agent_endpoint and agent_token. This creates a separate workspace; it does not move existing self-hosted records into it.

For a workspace on your own service, POST /api/hosted/agent-token with Authorization: Bearer <ingest_token> returns a new agent token and revokes old agent tokens. Do this from a trusted administration tool; the app's hosted agent-refresh controls target its built-in hosted service.

Server setup prerequisites →