Build health and training intelligence into your app.

01 / Integration overview

Your experience. Connected intelligence.

Use Coach to answer training questions and prepare changes. Use Health to bring source-backed observations and insights into those decisions. Your backend connects the services to your app’s identity, consent, and entitlement rules.

1. Your appMember session, training plan, and approved context
2. Your backendVerified identity, access checks, and confidential service requests
3. KnownsetHealth insights, coaching responses, and validated proposals
4. Your appReview, confirmation, and the final product action

02 / Coach API

Turn a coaching conversation into a reviewed change.

Stream an answer, adapt a workout, and preserve the intent of the program. Coach returns a proposal your product can explain and validate. Creating a proposal does not update the member’s workout.

POST /v1/proposals

{
  "user_id": "server-resolved-demo-user",
  "session": {
    "program": "Synthetic strength session",
    "week": 1,
    "day": 1,
    "exercises": [
      {
        "name": "Back Squat",
        "sets": "3",
        "rep_range": "5",
        "reps_unit": "reps",
        "rpe_target": 7
      }
    ]
  },
  "intent": "Add a note to brace before every rep. Keep the prescription.",
  "source": "edit_surface"
}

{
  "proposal_id": "synthetic-proposal-01",
  "ops": [
    {
      "op": "add_note",
      "block_ref": "ex-0",
      "text": "Brace before every rep."
    }
  ],
  "rationale": "Keep the planned work and add the requested cue.",
  "rule_citations": [],
  "validation_report": {
    "verdict": "pass",
    "findings": []
  },
  "expires_at": "2026-08-08T12:00:00Z",
  "manifest": null
}

Coach v1 contract example. The null manifest is illustrative; an actual service response carries its execution metadata. A successful validation is not confirmation to apply.

1. Render the proposed operations and their rationale.
2. Ask the member to accept or dismiss the change.
3. Apply an accepted change through your product’s own workout logic.
4. Report the outcome to the proposal resolution route.

Keep the context with the conversation.

Send current sessions and benchmarks through POST /v1/context/{kind}, and approved observations through POST /v1/context/observations. Conversation history and member memory remain scoped to the authenticated member. Context assembly and confirmed training-record writes stay in your product.

03 / Health API

Bring health evidence into training decisions.

Read current insight cards with freshness, completeness, citations, and known limits. Connect recovery, sleep, and training demand without treating an observation as an automatic workout change.

GET /v1/health/insights?date=2026-08-07&surface=today

{
  "schema_version": "health-v1",
  "data": [
    {
      "id": "10000000-0000-4000-8000-000000000003",
      "analysis_run_id": "synthetic-analysis-01",
      "analysis_kind": "training_load",
      "card_key": "synthetic-training-load",
      "surface": "today",
      "rank": 0,
      "title": "Training load rose above the recent range.",
      "summary": "The synthetic training series shows a recent increase in session demand.",
      "direction": "up",
      "severity": "attention",
      "score": null,
      "band": "above_baseline",
      "confidence": 0.8,
      "data_completeness": 0.9,
      "freshness_through": "2026-08-07",
      "limitations": [
        "Synthetic example. Session demand does not measure injury risk."
      ],
      "action_label": null,
      "action_path": null,
      "presentation": {},
      "expires_at": null,
      "created_at": "2026-08-07T12:00:00Z",
      "citations": [
        {
          "order": 0,
          "label": "Synthetic training sessions",
          "detail": "Seven-day versus 28-day load comparison",
          "observed_at": "2026-08-07",
          "observed_on": "2026-08-07",
          "value": null,
          "unit": null
        }
      ]
    }
  ]
}

The request goes from your backend to the configured Health service using its server credentials. This complete synthetic response follows the pinned Health v1 schema.

04 / SDK and samples

Start with the path that fits your product.

TypeScript SDK · private release candidate

The browser and mobile client calls your authenticated backend. The server package maps named operations to Coach routes and keeps Knownset credentials on the server. Package access and service access are provided separately during integration setup.

SDK packages are not a public install-and-connect service. Request the integration guide for approved versions and environment setup.

Optional: run the local MCP sample

Use the four read-only tools to inspect capabilities, a health summary, insight cards, and their evidence. You need approved repository access, Node 22, Corepack, and Docker. This sample does not run coaching or apply workout changes.

1. Install the workspace with its pinned pnpm version.
2. Start the local synthetic platform.
3. Approve the sample data with explicit --yes consent for the fixed demo member.
4. Run the client to discover four tools and follow an insight to its evidence.

corepack pnpm install
corepack pnpm local:up
corepack pnpm --filter @knownset/mcp example:activate-local-demo -- --yes
corepack pnpm --filter @knownset/mcp example:local

MCP 2026-07-28. Capabilities uses knownset:capabilities:read; the three Health reads use knownset:health:read. Examples below show structured results from the local stdio fixture.

{
  "name": "knownset_get_capabilities",
  "arguments": {}
}

{
  "schemaVersion": "knownset-mcp-capabilities-v1",
  "mode": "local-synthetic",
  "watermark": "SYNTHETIC DEMO DATA",
  "surfaces": {
    "healthInsights": true,
    "coach": false,
    "actionProposals": false,
    "dataExports": false
  },
  "boundary": "Read-only synthetic data over local stdio. Remote HTTP and OAuth are not active."
}

{
  "name": "knownset_get_health_summary",
  "arguments": {
    "date": "2026-08-07"
  }
}

{
  "schemaVersion": "knownset-mcp-health-summary-v1",
  "requestedDate": "2026-08-07",
  "effectiveDate": "2026-08-07",
  "watermark": "SYNTHETIC DEMO DATA",
  "recordCount": 58,
  "insightCount": 6,
  "summary": "The synthetic fixture shows a recent training-load rise, later sleep timing, and recovery signals below their established range. Fueling context remains incomplete.",
  "limitations": [
    "This fixture is not medical advice and does not represent a real person.",
    "No live provider, genetics, lab, model, or database connection is active."
  ]
}

{
  "name": "knownset_list_health_insights",
  "arguments": {
    "date": "2026-08-07",
    "surface": "today",
    "limit": 1,
    "cursor": "ks1:2",
    "response_format": "json"
  }
}

{
  "schemaVersion": "knownset-mcp-health-insights-v1",
  "requestedDate": "2026-08-07",
  "effectiveDate": "2026-08-07",
  "surface": "today",
  "watermark": "SYNTHETIC DEMO DATA",
  "insights": [
    {
      "id": "10000000-0000-4000-8000-000000000003",
      "kind": "training_load",
      "title": "Training load rose faster than the established baseline.",
      "summary": "Recent synthetic session demand increased while the longer comparison window remained stable.",
      "confidence": "high",
      "limitations": [
        "Session demand is not a measure of injury risk."
      ],
      "citations": [
        {
          "source": "Synthetic training sessions",
          "window": "Jul 25–Aug 7",
          "method": "Seven-day versus 28-day load comparison"
        }
      ]
    }
  ],
  "nextCursor": "ks1:3"
}

{
  "name": "knownset_get_insight_evidence",
  "arguments": {
    "insight_id": "10000000-0000-4000-8000-000000000003",
    "response_format": "json"
  }
}

{
  "schemaVersion": "knownset-mcp-insight-evidence-v1",
  "watermark": "SYNTHETIC DEMO DATA",
  "insightId": "10000000-0000-4000-8000-000000000003",
  "title": "Training load rose faster than the established baseline.",
  "limitations": [
    "Session demand is not a measure of injury risk."
  ],
  "citations": [
    {
      "source": "Synthetic training sessions",
      "window": "Jul 25–Aug 7",
      "method": "Seven-day versus 28-day load comparison"
    }
  ]
}

05 / Security and reliability

Make the boundary explicit.

1. Authenticate in your app

   Your backend verifies the existing app session and resolves the member and organization. Browser and mobile clients never select a Knownset tenant or service user.

2. Keep credentials on your server

   Your backend supplies the tenant credential and scoped user token. Model credentials, signing secrets, and provider credentials stay out of the client.

3. Send approved context

   Your integration checks consent and entitlements before sending the health observations, training records, and current session needed for the request.

4. Review before applying

   A proposal contains operations and validation findings. Your app requests confirmation, applies the approved change, and reports its outcome.

06 / Get started

Bring coaching into your product.

Choose a plan, then work through service access, identity mapping, and the first member workflow. Checkout does not place service credentials in your app; integration setup establishes the server connection.

For beta access or an integration guide, use the application path on the pricing page. The SDK and local sample require approved access.