# Rivendell

> Rivendell One is HSA-qualified, open-access health insurance for startups. The plan is live and binding. People: start with the plan facts and site links below. Agents: read `/plan.json` for plan facts and readiness, then `/api/capabilities` for the API contract.

## Plan facts (Rivendell One)

- Plan status: live and binding. Actuarially certified, carrier approved.
- Plan type: HSA-qualified, open-access, level-funded. No network or referrals.
- Deductible: $1,700 individual / $3,400 family (the 2026 statutory minimum). Employers fund 100% into each employee's HSA by default, so the net deductible is $0 and deposited money belongs to the employee.
- Out-of-pocket max: $5,000 individual / $10,000 family. Net of default HSA funding: $3,300 / $6,600.
- Coinsurance after the deductible: fixed 20% for covered care. Care navigation does not change the member percentage.
- Always $0: Virtual primary care through One Medical, 24/7; Telehealth and virtual urgent care, 24/7; Virtual therapy and psychiatry sessions; Preventive care; Everyday chronic meds: SSRIs, statins, insulin, inhalers.
- Coverage: all 50 states, any licensed provider. A California company location is required to sign up.
- Hold-harmless: members never pay above the out-of-pocket max, with any provider, in any state. This is in the plan contract.
- Insurance: from $757.33 per member per month.
- HSA contribution: $141.67 per employee per month by default; this is employee-owned money, not insurance premium.
- Default core employer outlay: $899 per employee per month (about $900), before optional add-ons.
- Founding cohort: $657.33 insurance plus $141.67 HSA, for $799 per employee per month. A $100 per employee per month credit against the standard rate card, for the first 10 groups, applied in the first plan year. Renewals are rated on the group's own experience. Founding pricing is set by Rivendell, in the binding quote.
- Pricing basis: California baseline. Rates vary by employee location; final terms are set in the binding quote. San Francisco is the pricing anchor (factor 1.00); other metros price lower (for example New York City 0.98, unlisted locations 0.86), applied per employee to the risk portion of the rate. Coverage tiers: spouse 2x, child 1.8x, family 3x the employee-only rate.
- Rate basis: the 2026 rate card prices coverage start dates through 2026-12-31; later start dates use the next rate card.
- Add-ons per member per month: Dental & Vision $100 (self-funded, works exactly like the base plan, same card; not part of the base plan). Carrot fertility $12.50 (pass-through). Wellness pack (Function Health labs 2x/year + wearable) $30. Lifestyle perk $100 via payroll.
- Group size: minimum 15 enrolling employees, firm. Every group is underwritten. Smaller teams are a better fit for an ICHRA or a marketplace plan.
- Administrator: Elrond Health Inc, company NPN 22113786. Licensed as CA third-party administrator + producer #6018541; NY producer #1970717; DE producer #3004061616.
- Behind the plan: Stop-loss is carried by a licensed carrier, named in your binding quote. Claims run-out protection, and 100% of claims-fund surplus returned to the employer.
- Renewals: rated on the group's own experience. Rivendell does not promise a group renewal-rate cap.
- Machine-readable version: https://rivendell.health/plan.json

## Site & Content

- [Rivendell](https://rivendell.health/): the Rivendell One plan, with insurance and employee-owned HSA funding shown separately.
- [About](https://rivendell.health/about): Heiki Riesenkampf's background, why he built Rivendell, where the name comes from, and the licensing behind the plan. [LinkedIn](https://www.linkedin.com/in/heikir/) · [X](https://twitter.com/heikirk).
- [Plan facts](https://rivendell.health/plan): every plan design number and its readiness state on one page. Machine version at [/plan.json](https://rivendell.health/plan.json).
- [How it works & FAQ](https://rivendell.health/faq): coverage, the funded HSA, concierge, joining, ongoing conditions, renewals, and how Rivendell compares to PEOs.
- [For brokers & payroll partners](https://rivendell.health/broker): evaluate the plan design, submit a census, and review the disclosed funding ledger and broker FAQ.
- [Blog](https://rivendell.health/blog): guides and analysis on startup health insurance.
- [Why your tech startup pays 30% more for health insurance](https://rivendell.health/blog/why-your-tech-startup-pays-way-more-for-health-insurance)
- [How to choose a health insurance plan for your startup](https://rivendell.health/blog/how-to-choose-health-insurance)
- [The Health 401(k): a free-market cure for American healthcare](https://rivendell.health/blog/the-health-401k)
- [Your health plan is designed to make you avoid care](https://rivendell.health/blog/health-plan-designed-to-avoid-care)
- [The best tax hack in the US requires the worst health insurance](https://rivendell.health/blog/the-best-tax-hack-in-the-us-requires)
- [Five healthcare predictions for 2026](https://rivendell.health/blog/five-healthcare-predictions-for-2026)

## Discovery

- [Plan facts JSON](https://rivendell.health/plan.json): machine-readable plan summary; read this to evaluate the insurance product.
- [Capabilities](https://rivendell.health/api/capabilities): machine-readable API capability descriptor; read this first for API work.
- [OpenAPI spec](https://rivendell.health/openapi.json): full REST schema.
- [Short LLM index](https://rivendell.health/llms.txt): this file.
- [Full LLM reference](https://rivendell.health/llms-full.txt): every endpoint, generated from the OpenAPI spec.
- [MCP server](https://rivendell.health/mcp): Model Context Protocol endpoint.
- [REST API base](https://rivendell.health/api): base path for REST calls.

## Authentication

- Production REST: `Authorization: Bearer <token>` or a Rivendell session cookie.
- MCP: OAuth or the same authenticated Rivendell bearer/session context exposed by the connector.
- Sandbox REST: `Authorization: Bearer sk_sandbox_PUBLIC` under `/api/sandbox/**` only. The sandbox key is intentionally public and is rejected everywhere else.
- Developer CLI / SDK: long-lived org-scoped Personal Access Tokens (`riv_pat_<43 chars>`) created at `/developers/api-tokens` or via `rivendell login`. Tokens carry server-defined scopes (`org:read`, `members:read`, `members:write`, `claims:read`, `claims:write`, `webhooks:read`, `webhooks:write`, `wearables:read`) and are tenant-scoped to the organization that minted them. Send as `Authorization: Bearer riv_pat_…`.

## MCP Connector

Rivendell runs a remote MCP server at `https://rivendell.health/mcp`. Connected, an assistant can read the member's plan and balances, claims, medications, provider options and appointments, and their own Oura and WHOOP data.

```bash
claude mcp add --transport http rivendell https://rivendell.health/mcp
```

Claude desktop and web, ChatGPT, Cursor and other MCP clients take the same URL as a custom connector. Auth is OAuth 2.1 with PKCE against the member's existing Rivendell account, plus dynamic client registration: there is no key to copy.

Scopes, approved once in the browser: `plan:read`, `account:read`, `account:write`, `claims:read`, `claims:write`, `medications:read`, `care:read`, `appointments:read`, `appointments:write`, `pricing:quote`, `employer:quote`, `wearables:read`. `wearables:read` is outside the default grant and must be requested explicitly, because consent is all-or-nothing per registration.

Full install steps, the tool list with what each tool is for, and example prompts: [/docs/mcp/connectors](https://rivendell.health/docs/mcp/connectors), or as raw markdown at [/docs/mcp.md](https://rivendell.health/docs/mcp.md). Wearables setup for members: [/wearables](https://rivendell.health/wearables).

## Developer CLI

`rivendell` is the official CLI for AI coding agents and developer integrations. Install:

```bash
brew install rivendell-health/cli/rivendell
# or
curl -fsSL https://rivendell.health/cli/install.sh | sh
export RIVENDELL_TOKEN=riv_pat_…
rivendell whoami
```

Signing in mints an org-scoped token, and only an organization's owners and admins may mint one. A member who is not an admin should use the MCP connector instead; it authenticates them as themselves and reaches the same wearable data.

`rivendell wearables` reads the caller's own devices: `status`, `connect`, `sleep`, `recovery`, `activity`, `workouts`, each taking `--days` or `--start-date`/`--end-date`, and `--provider oura|whoop`.

The CLI ships an `api` raw escape hatch matching `gh api`:

```bash
rivendell api GET  /api/cli/whoami
rivendell api POST /api/cli/foo --data '{"x":1}'
```

For real-time API call audit, `rivendell logs tail` streams events for the active organization via SSE (filters: `--surface`, `--status`, `--since`; auto-reconnects with `Last-Event-Id`; bodies never leave the server).

Same auth contract as the REST API. Auto-detects TTY for output: pretty JSON when interactive, raw bytes when piped. Exit codes: 0 success, 3 reauth required, 4 other 4xx, 5 5xx.

Raw markdown for this section: [/docs/cli.md](https://rivendell.health/docs/cli.md). Both documents together: [/docs/agents.md](https://rivendell.health/docs/agents.md).

## IDs

Rivendell-owned IDs are prefixed typed IDs: `^{prefix}_[A-Za-z0-9]{24,32}$`. New IDs use body `[a-z2-7]{24}`. Provider-owned IDs such as Stripe, Increase, Google, OAuth, device, and external IDs keep their native format. Malformed owned IDs return `400 validation_error` with `recovery_hint: CHECK_INPUT`.

## Lists

List endpoints use one envelope: `object="list"`, `data=[...]`, `has_more`, `url`, and optional `next_cursor`.

## Errors

Errors use an RFC 9457-style JSON envelope with `type`, `title`, string `status`, nullable `detail`, optional `param`, optional `code`, optional `doc_url`, and `recovery_hint`.

## Idempotency

Send `Idempotency-Key: <unique opaque key>` on POST, PATCH, DELETE JSON mutations. Matching retries replay for 24 hours and include `Idempotent-Replayed: true`. Same key with changed method, path, query, or body returns `409 idempotency_key_already_used_error`. Do not use this header for multipart, form, or binary uploads. Sandbox idempotency is public and globally scoped, so generate a fresh key for each new sandbox mutation to avoid collisions with other agents.

## Timestamps

Canonical resource base field `created` is Unix seconds. Some legacy fields such as `created_at`, `updated_at`, `service_date`, or route-specific compatibility fields may still be ISO 8601 strings when documented by that operation.

## Resources

- claims: Reimbursement and card-transaction claim status, substantiation, and adjudication workflows. Endpoints: /api/claims, /api/claims/{id}, /api/claims/reimbursement. Sandbox: /api/sandbox/claims.
- benefits: Current plan year deductible, out-of-pocket, stipend, and coverage information. Endpoints: /api/plan, /api/benefits/assistant. Sandbox: /api/sandbox/benefits.
- cards: Member card listing, card details, card status, Apple Pay provisioning, and card activity. Endpoints: /api/cards, /api/cards/{cardId}, /api/cards/{cardId}/status, /api/card-activity.
- medications: Medication catalog search with Cost Plus Drugs handoff information. Endpoints: /api/medications/search. Sandbox: /api/sandbox/medications/search.
- providers: Provider search, care options, cash-pay estimates, and provider details. Endpoints: /api/doctors/search, /api/doctors/suggest.
- appointments: Appointment request creation, listing, cancellation, and booking workflow status. Endpoints: /api/doctors/appointments, /api/doctors/schedule.
- wearables: The caller's own Oura and WHOOP data, normalized to shared units: nightly sleep, daily recovery and readiness, daily activity and training load, individual workouts, body metrics, and which devices are linked. Read-only, member-scoped, and gated on the wearables:read scope. Endpoints: /api/wearables/connections, /api/wearables/sleep, /api/wearables/recovery, /api/wearables/activity, /api/wearables/workouts, /api/wearables/profile.

## Safe Sandbox Claim Example

```http
POST /api/sandbox/claims
Authorization: Bearer sk_sandbox_PUBLIC
Content-Type: application/json
Idempotency-Key: 7d6f6dc3-6d91-4c1a-b332-4e94f0c74b8a

{
  "member_id": "mem_test_001",
  "service_category": "VISION",
  "submitted_amount": 4250,
  "service_date": "2026-04-01",
  "merchant_name": "Sandbox Vision",
  "description": "Eye exam simulation",
  "metadata": { "source": "agent_smoke_test" }
}
```

Expected success: `201`, `object: "claim"`, `livemode: false`, and an ID beginning `claim_`. Retry the identical request with the same idempotency key to observe replay. Retry with the same key and changed amount to observe `409 idempotency_key_already_used_error`.

## Smoke Test Prompt

Read `/llms.txt`, discover sandbox auth, create a sandbox claim with an `Idempotency-Key`, retry the same request and explain replay, then retry the same key with a changed amount and explain `idempotency_key_already_used_error`.