# 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, carrier endorsed.
- 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: 10+ employees always underwritten; 5 to 9 case by case.
- Administrator: Elrond Health Inc, company NPN 22113786. Licensed as CA third-party administrator + producer #6018541; NY producer #1970717; DE producer #3004061616.
- Behind the plan: Companion Life (A-rated) stop-loss, 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`) and are tenant-scoped to the organization that minted them. Send as `Authorization: Bearer riv_pat_…`.

## Developer CLI

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

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

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.

## 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.

## 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`.