canonical: https://jentic.com/apis/mdhub.ai/mdhub

# mdhub API

The mdhub API reads from and writes to the mdhub behavioral health clinical record through two surfaces: a proprietary v1 API for patients, session transcripts, AI-coordinator calls, and questionnaires, and a standards-based HL7 FHIR R4 API for the same underlying data. The FHIR side covers Patient, Coverage, eligibility checks with TMS and IOP authorization status, Condition, medications, allergies, Consent, providers, locations, Schedule, Slot, Appointment, Encounter, Observation, questionnaires, DocumentReference, ServiceRequest, and Subscription webhooks. Standardized PHQ-9, GAD-7, and MADRS questionnaires can be submitted as raw integer scores, after which mdhub generates an AI summary and a numeric score.

## For AI agents

Create and update patients, book appointments from open slots, submit PHQ-9, GAD-7, and MADRS scores, check behavioral health insurance eligibility, and pull session transcripts and AI-coordinator call logs from an mdhub clinic.

## Scope

Does not handle claims submission, payment collection, e-prescribing to pharmacies, or video visits. Use for reading and writing mdhub behavioral health records, scheduling, and questionnaires only.

## Capabilities

- Submit a standardized PHQ-9, GAD-7, or MADRS questionnaire as raw integer scores with mdhubType, and get an AI summary and numeric score generated automatically
- Search open Slot resources by schedule, status, and start, then book an Appointment or reschedule it with an update
- Submit a CoverageEligibilityRequest to verify behavioral health benefits such as session limits and TMS or IOP authorization, then read the CoverageEligibilityResponse
- Retrieve the transcript for a session by sessionId and page through AI-coordinator calls with pageSize and pageToken
- Search and update FHIR Patient, Condition, MedicationRequest, AllergyIntolerance, and Consent records for the clinic the token belongs to
- Register a FHIR Subscription with criteria and a rest-hook channel so mdhub posts notifications when matching resources change
- Create a patient through the v1 API with firstName, lastName, gender, and dateOfBirth, optionally linking an externalEhrId

## Use cases

### Agent-assisted clinic operations through Jentic

A clinic operations agent can handle scheduling and intake through Jentic: it searches open Slot resources for a provider's schedule, books the Appointment, and after the visit submits the patient's PHQ-9 scores so mdhub produces its AI summary and score. Each FHIR call carries a scope such as system/Appointment.write, so the agent's reach matches the work it does.

Example prompt: Search Slot with schedule set to the provider's schedule id and status free, book an Appointment in the first slot for patient 123, then submit an mdhub-phq-9 questionnaire with nine integer responses for that patient

### Measurement-based care tracking

Behavioral health practices track symptom scores over time. The submit-mdhub route accepts only the integer scores for PHQ-9 (9 items, 0 to 3), GAD-7 (7 items, 0 to 3), or MADRS (10 items, 0 to 6), validates them against the stored questionnaire, and returns detailed issues on a bad length or range. Results are also readable as FHIR Observation resources for trend reporting.

Example prompt: Submit an mdhub-gad-7 questionnaire for patientId p_456 with responses [1,2,0,1,3,2,1], then search Observation for that patient to confirm the new score is recorded

### Benefits verification before TMS or IOP

Interventional treatments such as TMS and intensive outpatient programs need authorization. Creating a CoverageEligibilityRequest asks mdhub to verify behavioral health benefits, including session limits, cost-share detail, and authorization status, and the resulting CoverageEligibilityResponse can be searched by patient or request.

Example prompt: Read the patient's Coverage, submit a CoverageEligibilityRequest for that patient and insurer, then search CoverageEligibilityResponse by request and report the session limits returned

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/questionnaires/submit-mdhub` | Submit a standardized PHQ-9, GAD-7, or MADRS questionnaire |
| POST | `/sessions/getTranscript` | Get a session transcript |
| GET | `/calls/all` | List AI-coordinator calls |
| GET | `/Patient` | Search FHIR patients |
| GET | `/Slot` | Search bookable slots |
| POST | `/Appointment` | Book an appointment |
| POST | `/CoverageEligibilityRequest` | Submit an eligibility request |
| POST | `/Subscription` | Register a change notification |

## Key resources

- **Patients** — Create and update patients through v1, or search, read, create, and update FHIR Patient resources.
- **Sessions and calls** — Retrieve session transcripts and paginated AI-coordinator call logs.
- **Questionnaires** — Submit custom or standardized PHQ-9, GAD-7, and MADRS questionnaires, and manage FHIR Questionnaire and QuestionnaireResponse resources.
- **Scheduling** — Search Schedule and Slot resources and book or update Appointment resources.
- **Coverage and eligibility** — Manage Coverage and submit and read eligibility requests and responses.
- **Clinical records** — Condition, MedicationStatement, MedicationRequest, AllergyIntolerance, Consent, Encounter, Observation, DocumentReference, and ServiceRequest resources.
- **Subscriptions** — Register rest-hook Subscription resources for change notifications.

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 69 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 93 / 100
  - Developer Experience & Jentic Compatibility: 70 / 100
  - AI-Readiness & Agent Experience: 52 / 100
  - Agent Usability: 88 / 100
  - Security: 68 / 100
  - AI Discoverability: 70 / 100
- **View full report:** https://jentic.com/apis/mdhub.ai/mdhub/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring mdhub by hand means juggling two credentials: an x-api-key for the v1 routes and a short-lived OAuth client_credentials token for FHIR R4 that must carry the right SMART scopes. Through Jentic you install once, import mdhub from the API Directory, store both credentials once, and your agent calls it.
- **Permission scoping:** mdhub's FHIR routes put the resource type in the URL path (/Patient, /Appointment, /DocumentReference) and the record id on reads and updates (`/Patient/{id}`), so a rule can bound your agent to the resource types and operations you pick. You choose the operations it may call, so sensitive ones like reading session transcripts or updating medication requests are not included unless you add them.
- **Credential handling:** Your mdhub API key and OAuth client secret are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'book a patient appointment' or 'submit a PHQ-9 score', and Jentic returns the matching mdhub operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **DrChrono API** — General ambulatory EHR with scheduling, clinical notes, and billing.
- **athenahealth API** — Large practice management and EHR platform with broad clinical and billing coverage.
- **Oystehr** — FHIR-based healthcare platform for building your own clinical apps.
- **Heidi Health** — AI medical scribe that drafts clinical notes from consultations.

## FAQ

### What authentication does the mdhub API use?

Per its OpenAPI spec, the mdhub API uses two schemes. The proprietary v1 routes, such as patients, session transcripts, calls, and questionnaire submission, take an API key in the x-api-key header. The FHIR R4 routes use OAuth 2.0 client credentials under the SMART Backend Services profile, with SMART v2 system scopes such as system/Patient.read, and access tokens last 5 minutes. Through Jentic both credentials are stored encrypted on your own instance and injected at call time.

### Is there an mdhub MCP server?

You don't need an MCP server to give your agent mdhub. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent calls it. Operations are discovered on demand, so the agent's context is not loaded with another server's tool definitions.

### Can I limit what my agent is allowed to do with the mdhub API?

Yes. For a scheduling agent, write a rule that allows only GET /Slot, GET /Schedule, and POST /Appointment, so it can find open slots and book visits but cannot read clinical documents, medications, or session transcripts. You can also register the OAuth client with only the scopes it needs, such as system/Appointment.write. Every call the agent makes is logged.

### What are the rate limits for the mdhub API?

The spec states default limits of 100 requests per minute and 1000 requests per hour per API key, with higher custom limits on enterprise plans. The FHIR API is limited per client credential at the same default tier. Exceeding a limit returns Too Many Requests.

### Can I submit PHQ-9 or GAD-7 scores with the mdhub API?

Yes. POST `/questionnaires/submit-mdhub` takes a patientId, an mdhubType such as mdhub-phq-9, mdhub-gad-7, or mdhub-madrs, and a responses array of integer scores. mdhub validates the length and range against the stored questionnaire, maps each score to its label, and generates an AI summary and numeric score. Custom intake forms go through POST `/questionnaires/submit` instead.

### How do I book an appointment in mdhub through Jentic?

Search Jentic for an intent like 'book a patient appointment in mdhub', import the mdhub API, and store your OAuth client credentials once. Your agent then calls GET /Slot to find a free slot and POST /Appointment with the slot and participants. To run it on your own infrastructure, install Jentic One from its GitHub repo.