Skip to main content

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.

This guide walks you through every step from creating your Max AI developer account to making your first API call.

​
Step 1: Get a Developer Account

To access the Max AI API, you need a developer account.
  1. Sign up at app.maxcare.dev to get a developer account.
  2. Once registered, sign in at app.maxcare.dev (staging).

​
Step 2: Install the CLI

The Max AI CLI is the fastest way to create and develop apps. 
npm install -g @max-ai/cli
Authenticate with your developer account: 
max-ai auth login
This opens a browser window where you sign in with your Max AI account. The CLI stores your API key locally.
For CI or headless environments, you can pass an API key directly: max-ai auth login --api-key <key> --platform-url https://api.maxcare.dev

​
Step 3: Create Your App

Scaffold a new app with a single command: 
max-ai app init my-app
This prompts for app name, slug, and category, creates the app on the platform, scaffolds a Next.js project, and writes your client_id to max-ai.app.toml. See the CLI Reference → Creating an App for full output.
You can also create apps from the Developer Console if you prefer a web UI.

​
Step 4: Develop Locally

The tunnel requires cloudflared. Install it first:
  • macOS: brew install cloudflared
  • Linux/Windows: see the CLI Reference
Start your local development environment: 
cd my-billing-app
max-ai app dev
This command:
  • Starts your Next.js dev server
  • Creates a Cloudflare Tunnel to expose your local server via HTTPS
  • Registers your app as a draft on the platform
  • Auto-installs the app in your organization for testing
Your draft app appears in the marketplace only for your organization, marked with a “Draft” badge.

​
Seed Test Data

Coming soon — test data seeding is not yet available.

​
Step 5: Get Your API Key

Your app receives an API key when installed by an organization. For development, the CLI handles this automatically. For manual API access, generate a key from the Developer Console:
  1. Go to your app’s settings page
  2. Under API Keys, click Generate New Key
  3. Select the scopes for this key — effective permissions will never exceed the scopes granted to your app by the clinic
  4. Copy the key immediately — it is only shown once
Your API key looks like this: 
max_dev_ak_SBA...01S
Keep your API key secret. Never expose it in client-side code, public repositories, or logs. If your key is compromised, revoke it immediately and generate a new one.

​
Step 6: Make Your First Request

Every API request requires an Organization ID in the X-Organization-Id header. This identifies which clinic’s data you’re accessing. You can get the Organization ID from:
  • The App Bridge — The @max-ai/app-bridge SDK provides it automatically when your app is embedded in Max AI.
  • The API — Call /v3/marketplace/me to get your app’s identity and connected organization.
Verify your setup: 
curl -X GET "https://api.maxcare.dev/v3/marketplace/me" \
  -H "Authorization: Bearer max_dev_ak_SBA...01S" \
  -H "X-Organization-Id: 7e2c8cfe-b7a9-4deb-986d-e7012589e72b"

​
Successful Response

{
  "code": "success",
  "data": {
    "app": {
      "id": "app_2b6fe6754b674990bb07fa16ece694c3",
      "slug": "testapi",
      "liveVersionId": "apv_89ba6db5e6644a008849299672992970"
    },
    "organization": {
      "id": "org_7e2c8cfeb7a94deb986de7012589e72b"
    },
    "scopes": [
      "read:patients",
      "read:appointments",
      "read:providers",
      "read:bills",
      "read:claims",
      "read:notes",
      "read:emails"
    ]
  }
}

​
Step 7: Deploy (Beta)

App deployment via the CLI is currently in beta.
When your app is ready for production, set your hosting URL and deploy: 
max-ai app deploy
Then submit for review from the Developer Console. The Max AI team will review your app and approve or deny it with feedback.

​
Next Steps

CLI Reference

Full CLI documentation with all commands and options.

App Development

SDK packages, app lifecycle, and best practices.

Scopes

Understand which scopes grant access to which endpoints.

API Reference

Browse all available endpoints.