How It Works

Documentation Index

Fetch the complete documentation index at: https://docs.maxcare.ai/llms.txt

Use this file to discover all available pages before exploring further.

Max AI supports two types of marketplace apps:

1. Embedded apps — Run inside the Max AI dashboard as an iframe. Users interact with your app without leaving Max AI.
2. External apps — Run on your own domain as a standalone web app. Users authenticate via OAuth to share their Max AI identity with your app.

Most apps are embedded. Use an external app when you have your own portal, mobile app, or need to run outside the Max AI dashboard.

​

Embedded Apps

Your embedded app runs as an iframe directly inside the Max AI platform. When a clinic installs your app, it appears in their sidebar under Apps — and clicking it loads your app’s URL in an iframe within the Max AI dashboard.

​

Architecture Overview

Your app communicates with two systems:

1. App Bridge (@max-ai/app-bridge) — A client-side SDK that connects your iframe to the Max AI platform. It provides context about the current user and organization, and enables UI interactions with the host application.
2. Public API (api.maxcare.ai) — A REST API your backend calls to read and write clinic data (patients, appointments, bills, claims, notes, emails, phone numbers, inventory). Authenticated with API keys and scoped permissions.

​

Key Building Blocks

​

App Bridge

The @max-ai/app-bridge SDK runs in your frontend and provides:

• Organization context — The Organization ID of the clinic using your app, so your backend knows which clinic to query data for
• User context — Information about the current logged-in user
• Platform communication — Navigate, notify, and interact with the Max AI host

​

Component Library

The @max-ai/components package provides pre-built UI components styled to match the Max AI platform, so your app looks native.

​

Public API

The REST API at api.maxcare.ai gives your backend access to clinic data:

• Patients — Demographics, contact info, MRN
• Appointments — Schedule, status, provider assignments
• Bills — Charges, coding groups, diagnoses, line items
• Claims — Submission status, insurance, amounts
• Notes — Patient visit notes, SOAP notes, image upload and deletion
• Tasks — Create and manage EHR tasks/todos assigned to providers
• Emails — Send emails and track delivery status
• Phone Numbers — Clinic phone number directory
• Inventory — Stock levels, products, receiving sessions
• Providers & Facilities — Clinic staff and locations

Every API call requires your API key (Bearer token) and the Organization ID (from the App Bridge or /v3/marketplace/me).

​

Data Flow

1. A clinic installs your app from the Max AI Marketplace
2. They grant your app the scopes it requested (e.g., read:patients, read:appointments)
3. When a user opens your app, the App Bridge provides the Organization ID
4. Your frontend sends that Organization ID to your backend
5. Your backend calls api.maxcare.ai with your API key and the Organization ID
6. Max AI returns the clinic’s data, filtered to only the scopes your app was granted

​

External Apps

External apps run on your own domain. Instead of the App Bridge, they use OAuth 2.0 to authenticate Max AI users:

1. Your app redirects the user to app.maxcare.ai/oauth/authorize
2. The user logs in and selects which organizations to share
3. Max AI redirects back to your app with an authorization code
4. Your backend exchanges the code for user info using your API key

External apps still use the same Public API for data access — the only difference is how they identify the user.

​

Next Steps