# Max AI Developer Docs

## Docs

- [Get appointment by ID](https://docs.maxcare.ai/api-reference/v4/appointments/get-appointment-by-id.md): Returns a single appointment by ID. Requires read:appointments scope.
- [List appointments](https://docs.maxcare.ai/api-reference/v4/appointments/list-appointments.md): Returns a paginated list of appointments. Requires read:appointments scope.
- [Get bill by ID](https://docs.maxcare.ai/api-reference/v4/bills/get-bill-by-id.md): Returns a single bill with full detail. Requires read:bills scope.
- [List bills](https://docs.maxcare.ai/api-reference/v4/bills/list-bills.md): Returns a paginated list of bills. Requires read:bills scope.
- [Get claim by ID](https://docs.maxcare.ai/api-reference/v4/claims/get-claim-by-id.md): Returns a single claim with full detail including insurance info. Requires read:claims scope.
- [List claims](https://docs.maxcare.ai/api-reference/v4/claims/list-claims.md): Returns a paginated list of claims. Requires read:claims scope.
- [Get email by ID](https://docs.maxcare.ai/api-reference/v4/emails/get-email-by-id.md): Returns a single email send record by ID (only if sent by this application).
- [List sent emails](https://docs.maxcare.ai/api-reference/v4/emails/list-sent-emails.md): Returns a paginated list of emails sent by this application.
- [Send emails](https://docs.maxcare.ai/api-reference/v4/emails/send-emails.md): Send emails to patients and/or staff users by their IDs. Returns sent records and any errors.
- [Get facility by ID](https://docs.maxcare.ai/api-reference/v4/facilities/get-facility-by-id.md): Returns a single facility by ID. Requires read:facilities scope.
- [List facilities](https://docs.maxcare.ai/api-reference/v4/facilities/list-facilities.md): Returns a paginated list of facilities. Requires read:facilities scope.
- [Get inventory change by ID](https://docs.maxcare.ai/api-reference/v4/inventory/get-inventory-change-by-id.md): Returns a single inventory change. Requires read:inventory scope.
- [Get product by ID](https://docs.maxcare.ai/api-reference/v4/inventory/get-product-by-id.md): Returns a single product. Requires read:products scope.
- [Get stock levels](https://docs.maxcare.ai/api-reference/v4/inventory/get-stock-levels.md): Returns current stock levels for a facility. Requires read:inventory scope.
- [List inventory changes](https://docs.maxcare.ai/api-reference/v4/inventory/list-inventory-changes.md): Returns inventory changes for a facility. Requires read:inventory scope.
- [List products](https://docs.maxcare.ai/api-reference/v4/inventory/list-products.md): Returns a list of products. Requires read:products scope.
- [List products in an inventory change](https://docs.maxcare.ai/api-reference/v4/inventory/list-products-in-an-inventory-change.md): Returns products associated with an inventory change. Requires read:inventory scope.
- [Get current app context](https://docs.maxcare.ai/api-reference/v4/marketplace/get-current-app-context.md): Returns the authenticated app's context. Use this to verify API key validity and inspect resolved identity.
- [Delete image from note](https://docs.maxcare.ai/api-reference/v4/notes/delete-image-from-note.md): Deletes an image from the EHR synchronously and archives the local record.
- [Edit impression fields](https://docs.maxcare.ai/api-reference/v4/notes/edit-impression-fields.md): Updates diagnosis complexity and/or status on a specific impression and synchronously pushes to the EHR. ModMed only. The impressionId is found in the SOAP note response at soapNote.impressionsPlans[].impressionId. Requires write:soap_notes scope.
- [Edit SOAP note fields](https://docs.maxcare.ai/api-reference/v4/notes/edit-soap-note-fields.md): Updates one or more SOAP note text fields and synchronously pushes changes to the EHR. Only provided fields are updated. Returns the updated note with SOAP content. Requires write:soap_notes scope.
- [Get note by ID](https://docs.maxcare.ai/api-reference/v4/notes/get-note-by-id.md): Returns a single patient note by ID. Set includeSoapNote=true to include SOAP note content (requires read:soap_notes scope).
- [Get signed URL for a note image](https://docs.maxcare.ai/api-reference/v4/notes/get-signed-url-for-a-note-image.md): Returns a presigned S3 URL for the image file. The URL expires after 1 hour.
- [List patient notes](https://docs.maxcare.ai/api-reference/v4/notes/list-patient-notes.md): Returns a paginated list of patient notes. Only current versions are returned (no historical versions). Set includeSoapNote=true to include SOAP note content (requires read:soap_notes scope).
- [Upload image to note](https://docs.maxcare.ai/api-reference/v4/notes/upload-image-to-note.md): Uploads an image file to a patient note. The image is stored in S3 and synchronously pushed to the EHR. Requires providerId query parameter. Returns 502 if the EHR upload fails. Use GET /notes/:noteId/images/:imageId/url to get a signed URL.
- [Exchange authorization code for user info](https://docs.maxcare.ai/api-reference/v4/oauth/exchange-authorization-code-for-user-info.md): Exchanges an OAuth 2.0 authorization code for an OIDC id_token and user context. Authenticate with your app's API key in the Authorization header. No X-Organization-Id header required. Errors follow OAuth 2.0 spec format (RFC 6749).
- [Get patient by ID](https://docs.maxcare.ai/api-reference/v4/patients/get-patient-by-id.md): Returns a single patient by ID. Requires read:patients scope.
- [List patients](https://docs.maxcare.ai/api-reference/v4/patients/list-patients.md): Returns a paginated list of patients. Requires read:patients scope.
- [List organization phone numbers](https://docs.maxcare.ai/api-reference/v4/phone-numbers/list-organization-phone-numbers.md): Returns the phone numbers assigned to the organization. Supports filtering by type (payers, patients, unassigned). Requires read:phone_numbers scope.
- [Get provider by ID](https://docs.maxcare.ai/api-reference/v4/providers/get-provider-by-id.md): Returns a single provider by ID. Requires read:providers scope.
- [List providers](https://docs.maxcare.ai/api-reference/v4/providers/list-providers.md): Returns a paginated list of providers. Requires read:providers scope.
- [Create a task](https://docs.maxcare.ai/api-reference/v4/tasks/create-a-task.md): Creates a new task and pushes it to the EHR synchronously. Returns the task with syncStatus 'synced' on success, or 502 if the EHR push fails. Requires a providerId to authenticate with the EHR.
- [Get task by ID](https://docs.maxcare.ai/api-reference/v4/tasks/get-task-by-id.md): Returns a single task by ID.
- [List tasks](https://docs.maxcare.ai/api-reference/v4/tasks/list-tasks.md): Returns a paginated list of tasks. Filter by status, note, or date range.
- [Update task status](https://docs.maxcare.ai/api-reference/v4/tasks/update-task-status.md): Updates a task's status to 'completed' or 'cancelled'. If the task has been synced to the EHR, the status change is pushed synchronously. Returns 502 if the EHR push fails.
- [App Development](https://docs.maxcare.ai/guides/app-development.md): Build your Max AI marketplace app with the template, SDK, and best practices
- [How It Works](https://docs.maxcare.ai/guides/architecture.md): Understand how your app integrates with Max AI — embedded or standalone
- [Authentication](https://docs.maxcare.ai/guides/authentication.md): API key authentication, required headers, and security best practices.
- [CLI Reference](https://docs.maxcare.ai/guides/cli.md): Create, develop, and deploy Max AI apps from the command line
- [Error Handling](https://docs.maxcare.ai/guides/errors.md): Understanding API error responses and how to handle them
- [Getting Started](https://docs.maxcare.ai/guides/getting-started.md): Create your developer account, scaffold your app with the CLI, and make your first API call.
- [Max AI Developer Docs](https://docs.maxcare.ai/guides/index.md): Build healthcare integrations with the Max AI Public API
- [OAuth Authorization](https://docs.maxcare.ai/guides/oauth.md): Authenticate Max AI users in your standalone app using OAuth 2.0 Authorization Code flow
- [Pagination](https://docs.maxcare.ai/guides/pagination.md): How to navigate paginated list endpoints
- [Rate Limits](https://docs.maxcare.ai/guides/rate-limits.md): API rate limiting and throttling policies
- [Scopes](https://docs.maxcare.ai/guides/scopes.md): Permission scopes that control which API endpoints your app can access

## OpenAPI Specs

- [openapi-v4](https://docs.maxcare.ai/openapi-v4.json)
- [openapi-v3](https://docs.maxcare.ai/openapi-v3.json)
- [openapi-v2](https://docs.maxcare.ai/openapi-v2.json)
- [openapi-v1](https://docs.maxcare.ai/openapi-v1.json)
- [openapi](https://docs.maxcare.ai/api-reference/openapi.json)