Skip to main content
The API is agent-native. An agent can discover the contract without credentials, then call scoped tools over MCP JSON-RPC or plain REST.

​
Discover the contract

curl -s "$HEALTH_API/.well-known/health-agent.json"
The manifest includes the base URL, OTP auth endpoints, required JWT claims, available REST endpoints, MCP tools, scopes, and endpoint IDs. The OpenAPI 3.1 contract at GET /openapi.json is generated from the same schema source the MCP tools use.

​
Get a key

An agent with no credentials can mint one: the manifest’s auth.self_serve_key block lists the three calls (start email OTP, verify the user’s 8-digit code, then POST /api-keys with the session token). The walkthrough, including a ready-made MCP config, is at Connect your agent.

​
List tools (scoped to the token)

curl -s -X POST "$HEALTH_API/mcp" \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
tools/list returns only the tools allowed by both the token’s scopes and its enabled-endpoint claims, so an agent sees exactly what the user granted.

​
Call a tool

curl -s -X POST "$HEALTH_API/mcp" \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "query_health_context",
      "arguments": { "user_id": "user_123", "organization_id": "org_123", "query": "ApoB" }
    }
  }'

​
Scopes and endpoint grants

Tokens carry scopes (health:data:read, health:data:write, health:connections:write, health:labs:read) and per-endpoint grants. Issue agents the smallest set they need, for example imports.file, analyses.create, query.create, and dashboard_specs.read. Errors use RFC 9457 Problem Details for REST and structured error.data (with code, cause, fix, docs_url, request_id) for MCP.