Building on Lithos, Part 1: the four integration patterns

One API, four doors

Underneath every pattern is the same set of objects: a patient with your consent timestamp on the record, an encounter — initial or follow_up — that carries your intake to a licensed physician, the prescriptions and pharmacy orders an approval produces, and webhooks that report each state change. The patterns differ in who renders the patient screens and who initiates the calls. What they share is everything behind the API — the physician network, AI-prepared consultations, prescribing and pharmacy routing, state-by-state compliance — plus a hosted ops dashboard for your own team.

1 · Headless: your product, our clinic

The headless pattern is for teams who consider the patient experience their product. You design intake, the dashboard, messaging, and check-ins in your own stack and call the API at the clinical moments: create the patient, open the care plan, submit the encounter, react to the decision. Nothing about the interface is dictated. The medicine — physician network, AI-prepared consultations, e-prescribing, pharmacy routing, state rules — stays on the other side of the API.

# 1 · token (client credentials; tokens are short-lived)
curl https://api.sandbox.lithoshealth.com/v1/oauth2/token -X POST \
  -d grant_type=client_credentials -d client_id=$CLIENT_ID -d client_secret=$CLIENT_SECRET

# 2 · patient (external_id is your own user id)
curl https://api.sandbox.lithoshealth.com/v1/patients -X POST -H "Authorization: Bearer $TOKEN" -d '{
  "external_id": "usr_1042", "first_name": "Maya", "last_name": "Rivera",
  "date_of_birth": "1992-04-18", "sex": "female",
  "address": { "line1": "90 Rainey St", "city": "Austin", "state": "TX", "postal_code": "78701" },
  "email": "[email protected]", "phone": "+15125550143",
  "telehealth_consented_at": "2026-09-15T14:02:00Z"
}'

# 3 · encounter (intake_data keys are configured for your organization at onboarding)
curl https://api.sandbox.lithoshealth.com/v1/encounters -X POST -H "Authorization: Bearer $TOKEN" -d '{
  "patient_id": "pat_test_…", "encounter_type": "initial",
  "intake_data": { "height_inches": 66, "weight_lbs": 212, "allergies": "none", … }
}'

Pick this when you have a product team and a point of view about the experience. It is the pattern with the most engineering — screens, state, notifications — and the most control. The glossary entry covers the trade-offs.

2 · Portal template: a working patient surface you fork

Not every team wants to design a patient portal from zero. The Lithos patient portal is an open-source template that partners fork and customize: account creation, intake, async messaging, prescription tracking, refill requests, and billing history, already wired to the API. The base template is free and open source; Lithos engineering builds custom branding, workflows, and integrations as paid engagements, and design-partner cohort members receive a capped amount of that engineering complimentary at onboarding.

It fits clinics adding prescribing, brands testing a new category before committing design and engineering, and anyone whose bottleneck is time. It is also not a dead end: the template creates the same patients and encounters the API exposes, so a team that later wants its own screens replaces the interface without migrating anything. An early preview is available to design-partner cohort members now; general availability is planned for Q3 2026.

3 · Embedded care: adding treatment to a product that already has users

A fitness app, a supplement brand, a longevity platform, a women’s-health community: products with an audience that would value real treatment but were never built to be a clinic. Embedded care adds a module to the existing product. Your user becomes a Lithos patient — matched by your external ID, consent and identity captured inside your app — and the care flow lives alongside the features they already use.

The integration is the headless API scoped to one surface, and the design work is mostly about boundaries: disclosures that make clear a licensed physician is deciding, pricing that separates care from your product and runs through your own Stripe account, marketing that respects health-privacy rules, and a data line that keeps protected health information on Lithos while your app holds only what it needs. Part 2 of this series is a full walkthrough: adding prescriptions to an existing app.

4 · Agents: care as a tool an assistant can call

The newest door. A consumer assistant whose user says “I’m almost out of finasteride — refill it” needs to register or match the patient, submit a refill encounter, and report the outcome. Those are API calls, and increasingly they are discoverable tools: the Lithos MCP server (early access) describes patients, encounters, orders, and prescriptions so any compatible assistant can use them without bespoke code.

What does not change is the physician loop. The assistant submits a follow-up encounter with the check-in as intake; AI prepares it; a licensed physician reviews where the state requires it and makes the clinical decision; webhooks or status tools tell the assistant what happened. We wrote about the boundary in where AI stops and the model in what is agentic healthcare. The same pattern serves your own operations: the AI Care Coordinator add-on runs adherence check-ins, side-effect questions, titration guidance, and refill coordination for chronic-care programs, escalating to a physician when clinically needed, and the Lead-to-Purchase Agent recovers abandoned intakes and answers pre-purchase clinical questions over text.

Every door includes the ops dashboard

Whichever pattern renders the patient side, your clinical and operations team gets a hosted, real-time operations view — encounters, decisions, orders, prior authorizations — branded for you at onboarding. It is the back office for teams that do not want to build one, and it sits alongside the API rather than replacing it. The same webhooks that drive the dashboard feed your own tools; Part 3 of this series is about designing around those events: event-driven telehealth.

Choosing

• No engineers, or none to spare this quarter: the portal template.
• A product team and a point of view about the experience: headless.
• An existing app with users who want treatment: embedded care.
• An assistant, or an ops team drowning in refills: agents, plus the AI Care Coordinator.
• Not sure: start from the template, keep the API open, and let the product tell you when to go deeper.

Frequently asked questions