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.
Scopes are permissions that control which API endpoints your app can access. When a clinic installs your app, they grant the scopes your app has requested.
How Scopes Work
- When you create your app, you declare which scopes it needs
- When a clinic installs your app, they review and approve those scopes
- When you create an API key, you select which of the approved scopes it should have
- At runtime, your effective permissions are the intersection of the key’s scopes and the clinic’s installation grants, and each API endpoint checks for the required scope before returning data
If you call an endpoint without the required scope, you’ll receive a 403 Forbidden response.
Available Scopes
Read Scopes
Patient Data
| Scope | Endpoints | Description |
|---|
read:patients | GET /v3/patients | List patients with search and pagination |
| GET /v3/patients/{id} | Get a specific patient by ID |
Appointments
| Scope | Endpoints | Description |
|---|
read:appointments | GET /v3/appointments | List appointments with filters |
| GET /v3/appointments/{id} | Get a specific appointment by ID |
Providers
| Scope | Endpoints | Description |
|---|
read:providers | GET /v3/providers | List providers |
| GET /v3/providers/{id} | Get a specific provider by ID |
Facilities
| Scope | Endpoints | Description |
|---|
read:facilities | GET /v3/facilities | List facilities |
| GET /v3/facilities/{id} | Get a specific facility by ID |
Billing
| Scope | Endpoints | Description |
|---|
read:bills | GET /v3/bills | List bills with pagination |
| GET /v3/bills/{id} | Get detailed bill with line items and coding groups |
read:encounters | (legacy) | Same as read:bills |
Claims
| Scope | Endpoints | Description |
|---|
read:claims | GET /v3/claims | List claims with pagination |
| GET /v3/claims/{id} | Get detailed claim with insurance info |
Notes
| Scope | Endpoints | Description |
|---|
read:notes | GET /v3/notes | List patient visit notes |
| GET /v3/notes/{id} | Get a specific note by ID |
read:soap_notes | GET /v3/notes?includeSoapNote=true | Include SOAP note content (requires read:notes too) |
Tasks
| Scope | Endpoints | Description |
|---|
read:tasks | GET /v3/tasks | List tasks with filters (status, note, provider, patient, date range) |
| GET /v3/tasks/{id} | Get a specific task by ID |
Emails
| Scope | Endpoints | Description |
|---|
read:emails | GET /v3/emails | List emails |
| GET /v3/emails/{id} | Get a specific email by ID |
Phone Numbers
| Scope | Endpoints | Description |
|---|
read:phone_numbers | GET /v3/phone-numbers | List clinic phone numbers |
Inventory
| Scope | Endpoints | Description |
|---|
read:inventory | GET /v3/inventory/changes | List inventory changes |
| GET /v3/inventory/changes/{id} | Get a specific inventory change |
| GET /v3/inventory/changes/{id}/products | Get products for an inventory change |
| GET /v3/inventory/stock-levels | Get current stock levels |
read:products | GET /v3/inventory/products | List products in the catalog |
| GET /v3/inventory/products/{id} | Get a specific product |
Write Scopes
Notes
| Scope | Endpoints | Description |
|---|
write:notes_images | POST /v3/notes/{noteId}/images?providerId= | Upload an image to a note |
| DELETE /v3/notes/{noteId}/images/{imageId}?providerId= | Delete an image from a note |
write:soap_notes | PATCH /v3/notes/{noteId}?providerId= | Edit SOAP note fields (with EHR sync) |
| PATCH /v3/notes/{noteId}/impressions/{impressionId}?providerId= | Edit impression fields (ModMed only) |
Tasks
| Scope | Endpoints | Description |
|---|
write:tasks | POST /v3/tasks | Create a task (synchronous EHR push) |
| PATCH /v3/tasks/{id} | Update task status (complete/cancel) |
Emails
| Scope | Endpoints | Description |
|---|
write:emails | POST /v3/emails/send | Send an email |
Products
| Scope | Endpoints | Description |
|---|
write:products | POST /v3/inventory/products | Create a new product |
| PUT /v3/inventory/products/{id} | Update an existing product |
Inventory
| Scope | Endpoints | Description |
|---|
write:inventory | POST /v3/inventory/changes | Create an inventory change |
Checking Your Scopes
Use the /v3/marketplace/me endpoint to see which scopes your API key currently has. This endpoint does not require any scope — it is always available.
curl -X GET "https://api.maxcare.ai/v3/marketplace/me" \
-H "Authorization: Bearer max_prd_ak_SBA...01S" \
-H "X-Organization-Id: 7e2c8cfe-b7a9-4deb-986d-e7012589e72b"
{
"code": "success",
"data": {
"app": {
"id": "app_2b6fe6754b674990bb07fa16ece694c3",
"slug": "testapi",
"liveVersionId": "apv_89ba6db5e6644a008849299672992970"
},
"organization": {
"id": "org_7e2c8cfeb7a94deb986de7012589e72b"
},
"scopes": [
"read:patients",
"read:appointments",
"read:providers",
"read:facilities",
"read:bills",
"read:claims",
"read:notes",
"read:soap_notes",
"read:emails",
"read:phone_numbers",
"read:inventory",
"read:products",
"read:encounters",
"write:notes_images",
"write:emails",
"write:products",
"write:inventory"
]
}
}
Insufficient Scope Error
If you call an endpoint without the required scope:
{
"code": "forbidden",
"message": "Insufficient scope. Required: read:patients",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
