openapi: 3.1.0 info: version: 1.0.23 title: mdhub API contact: name: mdhub Support email: support@mdhub.ai url: https://mdhub.ai description: | # Introduction Welcome to the mdhub API documentation. This API allows you to integrate mdhub's services into your applications, enabling seamless automation and integration with your existing workflows. # Authentication All API requests require authentication using an API key. Include your API key in the `x-api-key` header with each request: ``` x-api-key: your_api_key_here ``` To obtain an API key, please contact our [support team](mailto:support@mdhub.ai). # Rate Limiting To ensure service stability, the API applies default rate limits: - 100 requests per minute per API key - 1000 requests per hour per API key These are standard defaults. Higher, custom rate limits are available for enterprise plans and high-volume integrations — contact [support](mailto:support@mdhub.ai) to arrange them. When you exceed your rate limit, the API returns a `429 Too Many Requests` response. # Error Handling The API uses conventional HTTP response codes to indicate the success or failure of requests: - `2xx`: Success - `4xx`: Client errors - `5xx`: Server errors # Versioning The current version is v1. We maintain backward compatibility and notify users before any breaking changes. # Request Format - Content-Type: `application/json` - Character Encoding: `UTF-8` # Security We take security seriously: - All API requests must be made over HTTPS - API keys must be kept secure and not shared - Regular security audits are performed # Support If you need assistance: - Email: support@mdhub.ai - Documentation: https://docs.mdhub.ai - Status Page: https://mdhub.statuspage.io/ # Best Practices 1. Implement proper error handling 2. Cache responses when appropriate 3. Use compression for large requests 4. Follow rate limiting guidelines 5. Keep your API key secure servers: - url: https://api.mdhub.ai/v1 description: Production API Server x-tagGroups: - name: mdhub API (v1) tags: - Sessions - Questionnaires - Patients - Calls - name: FHIR R4 API tags: - FHIR Overview - Conformance - Patient - RelatedPerson - Coverage - Eligibility - Condition - Medication - AllergyIntolerance - Consent - Practitioner - Location - Schedule - Slot - Appointment - Encounter - Observation - Questionnaire - DocumentReference - ServiceRequest - Subscription tags: - name: FHIR Overview description: | # FHIR R4 API The mdhub FHIR R4 API is a standards-based, bidirectional interface that lets third-party systems read from and write to the mdhub clinical record using the [HL7 FHIR R4](https://hl7.org/fhir/R4/) specification. It runs alongside the proprietary mdhub API documented above and exposes the same underlying data through standard FHIR resources. ## Base URL ``` https://api.mdhub.ai/v1/fhir/R4 ``` All resource paths below are relative to this base URL (e.g. `GET https://api.mdhub.ai/v1/fhir/R4/Patient/{id}`). ## Authentication The FHIR API uses **OAuth 2.0** following the [SMART Backend Services](https://hl7.org/fhir/smart-app-launch/backend-services.html) (system-to-system) profile. Request an access token from the token endpoint using the `client_credentials` grant, then send it as a bearer token: ``` Authorization: Bearer ``` Token endpoint: ``` POST https://api.mdhub.ai/v1/oauth2/token grant_type=client_credentials ``` Access is scoped using SMART v2 system scopes such as `system/Patient.read` and `system/Appointment.write`. Contact [support@mdhub.ai](mailto:support@mdhub.ai) to register a client and obtain credentials. > The proprietary mdhub API (v1) continues to use the `x-api-key` header. OAuth 2.0 > applies only to the FHIR R4 endpoints. ## Content type All requests and responses use the FHIR JSON media type: ``` Content-Type: application/fhir+json Accept: application/fhir+json ``` ## Interactions Each resource supports the standard FHIR RESTful interactions: | Interaction | HTTP | Path | | --- | --- | --- | | read | `GET` | `/{Resource}/{id}` | | search | `GET` | `/{Resource}?` | | create | `POST` | `/{Resource}` | | update | `PUT` | `/{Resource}/{id}` | Search interactions return a `Bundle` of type `searchset`. Read interactions return a single resource instance. ## Search parameters Common parameters are supported across resources: `_id`, `_lastUpdated`, `_count` (page size), and `_sort`. Resource-specific parameters (for example `patient`, `date`, `status`) are listed on each operation. ## Errors Failed requests return an `OperationOutcome` resource with an `issue` array describing what went wrong, using conventional HTTP status codes (`400`, `401`, `403`, `404`, `422`, `429`, `5xx`). ## Versioning Every resource carries a `meta.versionId` and `meta.lastUpdated`. Instance-level version history is available and responses include an `ETag` header for optimistic concurrency control on updates. ## Events & webhooks Real-time notifications are delivered through the FHIR `Subscription` resource (`rest-hook` channel). Register a `Subscription` with a filter criteria and mdhub will POST notifications to your endpoint when matching resources change. ## Rate limiting The FHIR API is rate limited per client credential. Default limits match the standard mdhub API tier; higher, custom limits are available for enterprise plans and high-volume integrations. Exceeding the limit returns `429 Too Many Requests`. ## Resource coverage | Resource | Read | Write | Typical use | | --- | :---: | :---: | --- | | Patient | yes | yes | Demographics, single unified patient record | | RelatedPerson | yes | yes | Emergency / related contacts | | Coverage | yes | yes | Insurance on file | | CoverageEligibilityRequest / Response | yes | yes | BH-specific benefits, TMS/IOP session authorization | | Condition | yes | yes | ICD-10 diagnoses | | MedicationStatement / MedicationRequest | yes | yes | Medication management / psychiatry | | AllergyIntolerance | yes | yes | Allergies | | Consent | yes | yes | HIPAA consents | | Practitioner / PractitionerRole | yes | - | Providers (psychiatry, therapy, specialty) | | Location / Organization | yes | - | Clinic locations | | Schedule / Slot / Appointment | yes | yes | Patient self-scheduling, provider matching | | Encounter | yes | yes | Visits | | Observation | yes | yes | Measurement-based care scores (PHQ-9, GAD-7, MADRS) | | Questionnaire / QuestionnaireResponse | yes | yes | Intake forms, screeners | | DocumentReference | yes | yes | Session notes and transcripts | | ServiceRequest | yes | yes | Internal referrals, TMS/IOP prior authorization | | Subscription | yes | yes | Event / webhook notifications | - name: Conformance description: FHIR capability statement describing supported resources and interactions. - name: Patient description: Demographics and administrative information about a patient receiving care. - name: RelatedPerson description: A person related to the patient, such as an emergency or related contact. - name: Coverage description: Insurance or payor coverage on file for a patient. - name: Eligibility description: Behavioral-health-specific eligibility and benefits verification, including session limits and TMS/IOP authorization. - name: Condition description: Diagnoses and problems (ICD-10) recorded for a patient. - name: Medication description: Medications a patient is taking or has been prescribed. - name: AllergyIntolerance description: Allergies and intolerances recorded for a patient. - name: Consent description: HIPAA and treatment consents recorded for a patient. - name: Practitioner description: Providers (psychiatrists, NPs, PAs, therapists) and their roles. - name: Location description: Clinic locations and the organizations that operate them. - name: Schedule description: Provider and resource schedules that appointment slots belong to. - name: Slot description: Bookable time slots used for patient self-scheduling and provider matching. - name: Appointment description: Booked, pending, or cancelled appointments. - name: Encounter description: Clinical encounters / visits. - name: Observation description: Measurement-based care results and other structured observations. - name: Questionnaire description: Intake forms, screeners, and their submitted responses. - name: DocumentReference description: Clinical documents such as session notes and transcripts. - name: ServiceRequest description: Referrals and prior-authorization requests, including TMS and IOP. - name: Subscription description: Event notifications delivered via webhooks (rest-hook channel). paths: /sessions/getTranscript: post: tags: - Sessions summary: Get session transcript description: Retrieves the transcript for a specific session operationId: getSessionTranscript requestBody: required: true content: application/json: schema: type: object required: - sessionId properties: sessionId: type: string description: id of the session responses: '200': description: Transcript retrieved successfully content: application/json: schema: type: object properties: transcript: type: string description: The full transcript text example: transcript: 'Patient presents with complaints of...' '401': $ref: '#/components/responses/UnauthorizedError' '404': description: Session not found or transcript not available content: application/json: schema: type: object properties: error: type: string example: error: 'Session not found or transcript not yet generated' '429': $ref: '#/components/responses/TooManyRequests' /questionnaires/submit: post: tags: - Questionnaires summary: Submit a filled custom questionnaire for a patient description: | Creates a submitted patient-questionnaire for an existing patient. The patient must belong to the clinic that owns the API key. Use this endpoint for **custom questionnaires** you define yourself (intake forms, post-visit follow-ups, screeners, etc.). For mdhub-managed standardized questionnaires (PHQ-9, GAD-7, MADRS) use `/questionnaires/submit-mdhub` instead — it only needs raw integer scores and handles response-label mapping for you. Each schema item is validated against its `type`. Supported types: `input_title`, `input_free_text`, `input_number`, `input_single`, `input_multiple`, `input_list`, `input_likert`, `dropdown_single`, `dropdown_multiple`. `id` and `order` on each schema item are always assigned by the server (`id` via UUID, `order` via array position starting at 1) — any values sent by the client are ignored. `description` defaults to `""` and `required` defaults to `false` when omitted. Once stored, an AI summary is generated automatically. operationId: submitQuestionnaire requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubmitQuestionnaireRequest' examples: intake: summary: Custom intake form covering several input types value: patientId: abc123 questionnaire: title: New Patient Intake description: Completed before the first visit. type: questionnaire_intake questionnaireId: intake_v1 schema: - type: input_title title: Section 1 — Background - type: input_free_text title: What brings you in today? required: true response: Trouble sleeping for the past 3 weeks and low energy. - type: input_number title: Average hours of sleep per night prefix: hrs response: '5' - type: input_single title: Are you currently taking any psychiatric medication? options: - 'Yes' - 'No' response: 'No' - type: input_multiple title: Which of the following apply? options: - Anxiety - Insomnia - Low mood - Fatigue response: - Insomnia - Low mood - type: dropdown_single title: How would you rate your overall stress level? options: - Low - Moderate - High response: Moderate - type: input_likert title: Over the past 2 weeks, how often have you experienced… questions: - Difficulty falling asleep - Waking up during the night scale: label: 4-point scale frequency value: 4_point_scale_frequency items: - Not at all - Several days - More than half the days - Nearly every day response: - question: Difficulty falling asleep response: More than half the days - question: Waking up during the night response: Several days - type: input_list title: Current medications columns: - Medication - Dosage response: - col: Medication responses: - Sertraline - Trazodone - col: Dosage responses: - 50mg - 25mg minimal: summary: Minimal payload (single free-text question) value: patientId: abc123 questionnaire: title: Quick check-in schema: - type: input_free_text title: How are you feeling today? response: Better than last week — sleeping more consistently. responses: '201': description: Questionnaire submitted successfully content: application/json: schema: $ref: '#/components/schemas/SubmitQuestionnaireResponse' '400': description: Validation failed content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' example: message: Validation failed issues: - path: questionnaire.schema.0.options message: 'options must be a non-empty array of strings' - path: questionnaire.schema.2.response message: 'response "Maybe" must be one of the declared options' '401': $ref: '#/components/responses/UnauthorizedError' '403': description: Patient does not belong to this clinic content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Patient not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/InternalErrorResponse' /questionnaires/submit-mdhub: post: tags: - Questionnaires summary: Submit a standardized mdhub questionnaire (PHQ-9, GAD-7, MADRS) by raw scores description: | Submits a standardized questionnaire identified by `mdhubType` using only an array of integer scores. The server fetches the authoritative questionnaire schema from mdhub by `mdhubType` and maps each entry in `responses` to the appropriate response label (Likert scale items for PHQ-9 and GAD-7, option indexes for MADRS). **Lengths and ranges:** - `mdhub-phq-9`: 9 integers, each `0..3` - `mdhub-gad-7`: 7 integers, each `0..3` - `mdhub-madrs`: 10 integers, each `0..6` Validation runs against the actual questionnaire stored in mdhub, so wrong array length or out-of-range entries return a `400` with detailed `issues[]`. Once stored, an AI summary and a numeric score are generated automatically. operationId: submitMdhubQuestionnaire requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubmitMdhubQuestionnaireRequest' examples: gad7: summary: GAD-7 value: patientId: abc123 mdhubType: mdhub-gad-7 responses: [2, 1, 3, 2, 0, 1, 2] phq9: summary: PHQ-9 value: patientId: abc123 mdhubType: mdhub-phq-9 responses: [1, 2, 2, 1, 0, 1, 3, 2, 0] madrs: summary: MADRS value: patientId: abc123 mdhubType: mdhub-madrs responses: [2, 4, 2, 3, 2, 4, 2, 3, 2, 0] responses: '201': description: Questionnaire submitted successfully content: application/json: schema: $ref: '#/components/schemas/SubmitQuestionnaireResponse' '400': description: Validation failed (e.g. wrong array length, out-of-range score) content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' example: message: Validation failed issues: - path: responses message: 'responses length (5) must match the number of questions (7) for mdhub-gad-7' - path: responses.0 message: 'responses[0] = 1000 is out of range for mdhub-gad-7 (allowed: 0..3)' '401': $ref: '#/components/responses/UnauthorizedError' '403': description: Patient does not belong to this clinic content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Patient or mdhub questionnaire not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/InternalErrorResponse' /patients: post: tags: - Patients summary: Create a patient description: | Creates a new patient record. The clinic is determined by the provided API key. If a patient with a similar name and date of birth already exists, the existing patient is returned with a `200` status instead of creating a duplicate. **Billing info:** If `address` is provided, billing address is automatically populated from it — no need to send it separately. operationId: createPatient requestBody: required: true content: application/json: schema: type: object required: - firstName - lastName - gender - dateOfBirth properties: firstName: type: string example: Alice lastName: type: string example: Johnson middleName: type: string example: Marie gender: type: string example: Female genderIdentity: type: string example: Non-binary pronoun: type: string example: they/them dateOfBirth: type: string description: Date of birth in MM/DD/YYYY format example: 06/28/1996 raceEthnicity: type: string enum: - White - Black or African American - Asian - Hispanic or Latino - American Indian or Alaska Native - Native Hawaiian or Other Pacific Islander - Other - Prefer not to say email: type: string format: email example: patient@test.com phoneNumber: type: string example: '+12025551234' address: type: object description: Patient home address. Also auto-populates billingInfo. properties: address1: type: string example: 123 Main St address2: type: string example: Apt 4B city: type: string example: New York state: type: string example: NY zip: type: string example: '10001' externalEhrId: type: string description: Patient ID in the external EHR system example: ext_abc123 externalEhr: type: string description: Name of the external EHR system example: example-ehr diagnoses: type: array description: List of ICD-10 diagnoses associated with the patient. items: type: object required: - code properties: code: type: string example: F32.1 description: type: string example: Major depressive disorder, single episode, moderate relatedContacts: type: array description: Emergency / related contacts associated with the patient. items: type: object properties: fullName: type: string example: Jane Doe email: type: string example: jane@example.com phones: type: array items: type: string example: - '+12025551234' relationship: type: string example: Spouse hipaaConsent: type: boolean description: Defaults to false if not provided example: true insurances: type: array description: Insurance records associated with the patient. items: type: object properties: tradingPartnerName: type: string description: Insurance plan name example: Blue Cross Blue Shield memberId: type: string description: Member / subscriber ID example: XYZ123456789 groupNumber: type: string example: GRP001 company: type: string description: Insurance company name example: Anthem isPrimary: type: boolean description: Defaults to false if not provided example: true responses: '200': description: Patient already existed — returns the existing patient ID content: application/json: schema: type: object properties: patientId: type: string example: abc123 message: type: string example: Patient already existed '201': description: Patient created successfully content: application/json: schema: type: object properties: patientId: type: string example: abc123 '400': description: Invalid input content: application/json: schema: type: object properties: message: type: string '401': $ref: '#/components/responses/UnauthorizedError' '429': $ref: '#/components/responses/TooManyRequests' /patients/{patientId}: patch: tags: - Patients summary: Update a patient description: | Partially updates an existing patient. Only the fields present in the request body are modified; omitted fields are left untouched. The clinic is determined by the provided API key and must own the patient. For the array fields (`diagnoses`, `medications`, `allergies`, `insurances`, `relatedContacts`), each entry may include an optional `id`: - When `id` matches an existing entry, that entry is updated (shallow-merged). - When `id` is omitted, a new entry is appended. operationId: updatePatient parameters: - name: patientId in: path required: true description: The unique identifier of the patient to update. schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdatePatientRequest' responses: '200': description: Patient updated successfully content: application/json: schema: type: object properties: patientId: type: string example: abc123 '400': description: Invalid input content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/UnauthorizedError' '403': description: Patient does not belong to this clinic content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Patient not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/TooManyRequests' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/InternalErrorResponse' /calls/all: get: tags: - Calls summary: Get all calls for the clinic description: | Retrieves the AI-coordinator calls for the clinic determined by the provided API key. Each call includes call-level metadata (times, caller, review status, AI summary) and its full `interactions` transcript. Results are ordered most recent first and paginated with `pageSize` and `pageToken`. To page through results, pass the `nextPageToken` returned by the previous response as the `pageToken` of the next request. When `hasMore` is `false`, there are no further pages. operationId: getCalls parameters: - name: pageSize in: query required: false description: Number of results per page (max 100). Defaults to 50. schema: type: integer default: 50 - name: pageToken in: query required: false description: Token for fetching the next page (the id of the last call from the previous page). schema: type: string responses: '200': description: Calls retrieved successfully content: application/json: schema: $ref: '#/components/schemas/CallsResponse' '401': $ref: '#/components/responses/UnauthorizedError' '429': $ref: '#/components/responses/TooManyRequests' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/InternalErrorResponse' /metadata: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Conformance summary: Capability statement description: | Returns the FHIR `CapabilityStatement` describing the resources, interactions, and search parameters supported by the mdhub FHIR R4 server. operationId: getCapabilityStatement security: - oauth2: [] responses: '200': description: Capability statement content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_CapabilityStatement' '401': $ref: '#/components/responses/FHIRUnauthorized' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Patient: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Patient summary: Search patients description: >- Searches for `Patient` resources within the clinic the token belongs to. Returns a `Bundle` of type `searchset`, never a bare array. No matches is a `200` with `total: 0`, not a `404`. Every parameter narrows the result: they combine with AND, never OR. `total` counts the matches across every page, not the page returned. To walk the pages, follow the `next` link in the Bundle and send that URL unchanged. Sorting is not supported, so the order of results is stable but not meaningful. operationId: searchPatient security: - oauth2: - system/Patient.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirPage' - name: name in: query description: >- Matches the beginning of either the given or the family name, ignoring case. `Gar` finds Garcia and Garrido; `arcia` finds nothing. Accents are not yet ignored, so `Garcia` does not find García. schema: type: string - name: family in: query description: The family name, matched by prefix like `name`. schema: type: string - name: given in: query description: >- A given name, matched by prefix like `name`. Only the first given name is searched, so a middle name will not match. schema: type: string - name: birthdate in: query description: Date of birth (YYYY-MM-DD). Matched exactly. schema: type: string format: date - name: gender in: query description: One of male, female, other or unknown. Matched exactly. schema: type: string enum: - male - female - other - unknown - name: telecom in: query description: >- An email address or a phone number, matched exactly. Email ignores case; a phone number must be written exactly as it is stored, in E.164 form. schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' post: tags: - Patient summary: Create a patient description: >- Creates a new `Patient` resource and returns it as it was stored, so you can see which fields survived. An `id` in the request body is ignored; the server assigns one and returns it in the `Location` header. An `active` of `false` is ignored too, and the patient is created active. Only the first entry of `identifier` is kept. Fields the record has nowhere to store — such as `maritalStatus`, `communication` or `photo` — are accepted and dropped rather than refused. There is no deduplication: sending the same patient twice creates two records. operationId: createPatientFhir security: - oauth2: - system/Patient.write requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Patient' responses: '201': description: Patient created content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Patient' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '422': $ref: '#/components/responses/FHIRUnprocessable' /Patient/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Patient summary: Read a patient description: Retrieves a single `Patient` resource by id. operationId: readPatient security: - oauth2: - system/Patient.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: Patient resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Patient' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' put: tags: - Patient summary: Update a patient description: >- Replaces an existing `Patient`. Send the whole resource: read it, change what you need, and put it back. Anything you leave out is cleared, which is what `PUT` means in FHIR. The replacement covers only the fields FHIR models here. Diagnoses, medication, allergies, notes, session history, portal access and insurance are never touched. If the body carries an `id` it must match the one in the URL, or the request is refused with `400`. An unknown id returns `404` and creates nothing. As with create, only the first entry of `identifier` is kept and an inbound `active` is ignored. operationId: updatePatientFhir security: - oauth2: - system/Patient.write parameters: - $ref: '#/components/parameters/fhirId' requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Patient' responses: '200': description: Patient updated content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Patient' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '422': $ref: '#/components/responses/FHIRUnprocessable' /RelatedPerson: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - RelatedPerson summary: Search related persons description: Searches for `RelatedPerson` resources. Returns a `Bundle` of type `searchset`. operationId: searchRelatedPerson security: - oauth2: - system/RelatedPerson.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: patient in: query description: Reference to the patient this person is related to. schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' post: tags: - RelatedPerson summary: Create a related person operationId: createRelatedPerson security: - oauth2: - system/RelatedPerson.write requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_RelatedPerson' responses: '201': description: RelatedPerson created content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_RelatedPerson' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /RelatedPerson/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - RelatedPerson summary: Read a related person operationId: readRelatedPerson security: - oauth2: - system/RelatedPerson.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: RelatedPerson resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_RelatedPerson' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' put: tags: - RelatedPerson summary: Update a related person operationId: updateRelatedPerson security: - oauth2: - system/RelatedPerson.write parameters: - $ref: '#/components/parameters/fhirId' requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_RelatedPerson' responses: '200': description: RelatedPerson updated content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_RelatedPerson' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Coverage: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Coverage summary: Search coverages description: Searches for `Coverage` resources. Returns a `Bundle` of type `searchset`. operationId: searchCoverage security: - oauth2: - system/Coverage.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: patient in: query schema: type: string - name: status in: query schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' post: tags: - Coverage summary: Create a coverage operationId: createCoverage security: - oauth2: - system/Coverage.write requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Coverage' responses: '201': description: Coverage created content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Coverage' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Coverage/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Coverage summary: Read a coverage operationId: readCoverage security: - oauth2: - system/Coverage.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: Coverage resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Coverage' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' put: tags: - Coverage summary: Update a coverage operationId: updateCoverage security: - oauth2: - system/Coverage.write parameters: - $ref: '#/components/parameters/fhirId' requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Coverage' responses: '200': description: Coverage updated content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Coverage' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /CoverageEligibilityRequest: servers: - url: https://api.mdhub.ai/v1/fhir/R4 post: tags: - Eligibility summary: Submit an eligibility request description: | Creates a `CoverageEligibilityRequest` to verify behavioral-health-specific benefits for a patient, including session limits, cost-share detail, and TMS/IOP authorization status. The resulting `CoverageEligibilityResponse` can be retrieved from the `/CoverageEligibilityResponse` endpoint. operationId: createCoverageEligibilityRequest security: - oauth2: - system/CoverageEligibilityRequest.write requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_CoverageEligibilityRequest' responses: '201': description: Eligibility request created content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_CoverageEligibilityRequest' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /CoverageEligibilityResponse: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Eligibility summary: Search eligibility responses description: | Searches for `CoverageEligibilityResponse` resources containing the returned mental-health benefits and authorization details. operationId: searchCoverageEligibilityResponse security: - oauth2: - system/CoverageEligibilityResponse.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: patient in: query schema: type: string - name: request in: query description: Reference to the originating CoverageEligibilityRequest. schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' /CoverageEligibilityResponse/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Eligibility summary: Read an eligibility response operationId: readCoverageEligibilityResponse security: - oauth2: - system/CoverageEligibilityResponse.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: CoverageEligibilityResponse resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_CoverageEligibilityResponse' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Condition: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Condition summary: Search conditions operationId: searchCondition security: - oauth2: - system/Condition.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: patient in: query schema: type: string - name: code in: query description: ICD-10 code (system|code or code). schema: type: string - name: clinical-status in: query schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' post: tags: - Condition summary: Create a condition operationId: createCondition security: - oauth2: - system/Condition.write requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Condition' responses: '201': description: Condition created content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Condition' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Condition/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Condition summary: Read a condition operationId: readCondition security: - oauth2: - system/Condition.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: Condition resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Condition' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' put: tags: - Condition summary: Update a condition operationId: updateCondition security: - oauth2: - system/Condition.write parameters: - $ref: '#/components/parameters/fhirId' requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Condition' responses: '200': description: Condition updated content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Condition' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /MedicationStatement: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Medication summary: Search medication statements operationId: searchMedicationStatement security: - oauth2: - system/MedicationStatement.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: patient in: query schema: type: string - name: status in: query schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' post: tags: - Medication summary: Create a medication statement operationId: createMedicationStatement security: - oauth2: - system/MedicationStatement.write requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_MedicationStatement' responses: '201': description: MedicationStatement created content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_MedicationStatement' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /MedicationStatement/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Medication summary: Read a medication statement operationId: readMedicationStatement security: - oauth2: - system/MedicationStatement.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: MedicationStatement resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_MedicationStatement' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' put: tags: - Medication summary: Update a medication statement operationId: updateMedicationStatement security: - oauth2: - system/MedicationStatement.write parameters: - $ref: '#/components/parameters/fhirId' requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_MedicationStatement' responses: '200': description: MedicationStatement updated content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_MedicationStatement' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /MedicationRequest: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Medication summary: Search medication requests operationId: searchMedicationRequest security: - oauth2: - system/MedicationRequest.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: patient in: query schema: type: string - name: status in: query schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' post: tags: - Medication summary: Create a medication request operationId: createMedicationRequest security: - oauth2: - system/MedicationRequest.write requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_MedicationRequest' responses: '201': description: MedicationRequest created content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_MedicationRequest' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /MedicationRequest/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Medication summary: Read a medication request operationId: readMedicationRequest security: - oauth2: - system/MedicationRequest.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: MedicationRequest resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_MedicationRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' put: tags: - Medication summary: Update a medication request operationId: updateMedicationRequest security: - oauth2: - system/MedicationRequest.write parameters: - $ref: '#/components/parameters/fhirId' requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_MedicationRequest' responses: '200': description: MedicationRequest updated content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_MedicationRequest' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /AllergyIntolerance: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - AllergyIntolerance summary: Search allergies operationId: searchAllergyIntolerance security: - oauth2: - system/AllergyIntolerance.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: patient in: query schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' post: tags: - AllergyIntolerance summary: Create an allergy operationId: createAllergyIntolerance security: - oauth2: - system/AllergyIntolerance.write requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_AllergyIntolerance' responses: '201': description: AllergyIntolerance created content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_AllergyIntolerance' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /AllergyIntolerance/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - AllergyIntolerance summary: Read an allergy operationId: readAllergyIntolerance security: - oauth2: - system/AllergyIntolerance.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: AllergyIntolerance resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_AllergyIntolerance' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' put: tags: - AllergyIntolerance summary: Update an allergy operationId: updateAllergyIntolerance security: - oauth2: - system/AllergyIntolerance.write parameters: - $ref: '#/components/parameters/fhirId' requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_AllergyIntolerance' responses: '200': description: AllergyIntolerance updated content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_AllergyIntolerance' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Consent: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Consent summary: Search consents operationId: searchConsent security: - oauth2: - system/Consent.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: patient in: query schema: type: string - name: status in: query schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' post: tags: - Consent summary: Create a consent operationId: createConsent security: - oauth2: - system/Consent.write requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Consent' responses: '201': description: Consent created content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Consent' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Consent/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Consent summary: Read a consent operationId: readConsent security: - oauth2: - system/Consent.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: Consent resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Consent' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' put: tags: - Consent summary: Update a consent operationId: updateConsent security: - oauth2: - system/Consent.write parameters: - $ref: '#/components/parameters/fhirId' requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Consent' responses: '200': description: Consent updated content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Consent' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Practitioner: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Practitioner summary: Search practitioners operationId: searchPractitioner security: - oauth2: - system/Practitioner.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: name in: query schema: type: string - name: identifier in: query schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Practitioner/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Practitioner summary: Read a practitioner operationId: readPractitioner security: - oauth2: - system/Practitioner.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: Practitioner resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Practitioner' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' /PractitionerRole: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Practitioner summary: Search practitioner roles description: | Searches for `PractitionerRole` resources linking practitioners to locations, specialties, and services used by provider-matching logic. operationId: searchPractitionerRole security: - oauth2: - system/PractitionerRole.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: practitioner in: query schema: type: string - name: location in: query schema: type: string - name: specialty in: query schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' /PractitionerRole/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Practitioner summary: Read a practitioner role operationId: readPractitionerRole security: - oauth2: - system/PractitionerRole.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: PractitionerRole resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_PractitionerRole' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Location: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Location summary: Search locations operationId: searchLocation security: - oauth2: - system/Location.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: name in: query schema: type: string - name: address-state in: query schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Location/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Location summary: Read a location operationId: readLocation security: - oauth2: - system/Location.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: Location resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Location' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Organization: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Location summary: Search organizations operationId: searchOrganization security: - oauth2: - system/Organization.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: name in: query schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Organization/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Location summary: Read an organization operationId: readOrganization security: - oauth2: - system/Organization.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: Organization resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Organization' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Schedule: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Schedule summary: Search schedules operationId: searchSchedule security: - oauth2: - system/Schedule.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: actor in: query description: The practitioner or location the schedule belongs to. schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Schedule/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Schedule summary: Read a schedule operationId: readSchedule security: - oauth2: - system/Schedule.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: Schedule resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Schedule' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Slot: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Slot summary: Search slots description: | Searches for bookable `Slot` resources. Use `schedule`, `status=free`, and `start` to power patient self-scheduling and provider matching. operationId: searchSlot security: - oauth2: - system/Slot.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: schedule in: query schema: type: string - name: status in: query description: e.g. free, busy. schema: type: string - name: start in: query schema: type: string format: date-time responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Slot/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Slot summary: Read a slot operationId: readSlot security: - oauth2: - system/Slot.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: Slot resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Slot' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Appointment: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Appointment summary: Search appointments operationId: searchAppointment security: - oauth2: - system/Appointment.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: patient in: query schema: type: string - name: practitioner in: query schema: type: string - name: location in: query schema: type: string - name: date in: query description: Appointment date/time (supports prefixes ge, le). schema: type: string - name: status in: query schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' post: tags: - Appointment summary: Book an appointment description: Creates an `Appointment`. Booking a free `Slot` marks it as busy. operationId: createAppointment security: - oauth2: - system/Appointment.write requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Appointment' responses: '201': description: Appointment created content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Appointment' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Appointment/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Appointment summary: Read an appointment operationId: readAppointment security: - oauth2: - system/Appointment.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: Appointment resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Appointment' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' put: tags: - Appointment summary: Update or reschedule an appointment description: Updates an `Appointment`, for example to reschedule or cancel it. operationId: updateAppointment security: - oauth2: - system/Appointment.write parameters: - $ref: '#/components/parameters/fhirId' requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Appointment' responses: '200': description: Appointment updated content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Appointment' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Encounter: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Encounter summary: Search encounters operationId: searchEncounter security: - oauth2: - system/Encounter.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: patient in: query schema: type: string - name: date in: query schema: type: string - name: status in: query schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' post: tags: - Encounter summary: Create an encounter operationId: createEncounter security: - oauth2: - system/Encounter.write requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Encounter' responses: '201': description: Encounter created content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Encounter' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Encounter/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Encounter summary: Read an encounter operationId: readEncounter security: - oauth2: - system/Encounter.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: Encounter resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Encounter' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' put: tags: - Encounter summary: Update an encounter operationId: updateEncounter security: - oauth2: - system/Encounter.write parameters: - $ref: '#/components/parameters/fhirId' requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Encounter' responses: '200': description: Encounter updated content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Encounter' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Observation: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Observation summary: Search observations description: | Searches for `Observation` resources, including measurement-based care results such as PHQ-9, GAD-7, and MADRS scores stored as discrete data. operationId: searchObservation security: - oauth2: - system/Observation.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: patient in: query schema: type: string - name: category in: query description: e.g. survey. schema: type: string - name: code in: query description: LOINC code (e.g. 44249-1 for PHQ-9). schema: type: string - name: date in: query schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' post: tags: - Observation summary: Create an observation operationId: createObservation security: - oauth2: - system/Observation.write requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Observation' responses: '201': description: Observation created content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Observation' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Observation/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Observation summary: Read an observation operationId: readObservation security: - oauth2: - system/Observation.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: Observation resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Observation' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' put: tags: - Observation summary: Update an observation operationId: updateObservation security: - oauth2: - system/Observation.write parameters: - $ref: '#/components/parameters/fhirId' requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Observation' responses: '200': description: Observation updated content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Observation' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Questionnaire: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Questionnaire summary: Search questionnaires operationId: searchQuestionnaire security: - oauth2: - system/Questionnaire.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: status in: query schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' post: tags: - Questionnaire summary: Create a questionnaire operationId: createQuestionnaire security: - oauth2: - system/Questionnaire.write requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Questionnaire' responses: '201': description: Questionnaire created content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Questionnaire' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Questionnaire/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Questionnaire summary: Read a questionnaire operationId: readQuestionnaire security: - oauth2: - system/Questionnaire.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: Questionnaire resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Questionnaire' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' put: tags: - Questionnaire summary: Update a questionnaire operationId: updateQuestionnaire security: - oauth2: - system/Questionnaire.write parameters: - $ref: '#/components/parameters/fhirId' requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Questionnaire' responses: '200': description: Questionnaire updated content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Questionnaire' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /QuestionnaireResponse: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Questionnaire summary: Search questionnaire responses operationId: searchQuestionnaireResponse security: - oauth2: - system/QuestionnaireResponse.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: patient in: query schema: type: string - name: questionnaire in: query schema: type: string - name: status in: query schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' post: tags: - Questionnaire summary: Submit a questionnaire response description: | Submits a completed `QuestionnaireResponse` (intake form, screener, or follow-up). Scored instruments generate a corresponding `Observation`. operationId: createQuestionnaireResponse security: - oauth2: - system/QuestionnaireResponse.write requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_QuestionnaireResponse' responses: '201': description: QuestionnaireResponse created content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_QuestionnaireResponse' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /QuestionnaireResponse/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Questionnaire summary: Read a questionnaire response operationId: readQuestionnaireResponse security: - oauth2: - system/QuestionnaireResponse.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: QuestionnaireResponse resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_QuestionnaireResponse' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' put: tags: - Questionnaire summary: Update a questionnaire response operationId: updateQuestionnaireResponse security: - oauth2: - system/QuestionnaireResponse.write parameters: - $ref: '#/components/parameters/fhirId' requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_QuestionnaireResponse' responses: '200': description: QuestionnaireResponse updated content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_QuestionnaireResponse' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /DocumentReference: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - DocumentReference summary: Search documents description: | Searches for `DocumentReference` resources such as session notes and transcripts. operationId: searchDocumentReference security: - oauth2: - system/DocumentReference.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: patient in: query schema: type: string - name: type in: query schema: type: string - name: date in: query schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' post: tags: - DocumentReference summary: Create a document operationId: createDocumentReference security: - oauth2: - system/DocumentReference.write requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_DocumentReference' responses: '201': description: DocumentReference created content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_DocumentReference' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /DocumentReference/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - DocumentReference summary: Read a document operationId: readDocumentReference security: - oauth2: - system/DocumentReference.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: DocumentReference resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_DocumentReference' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' put: tags: - DocumentReference summary: Update a document operationId: updateDocumentReference security: - oauth2: - system/DocumentReference.write parameters: - $ref: '#/components/parameters/fhirId' requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_DocumentReference' responses: '200': description: DocumentReference updated content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_DocumentReference' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /ServiceRequest: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - ServiceRequest summary: Search service requests description: | Searches for `ServiceRequest` resources such as internal referrals and TMS/IOP prior-authorization requests. operationId: searchServiceRequest security: - oauth2: - system/ServiceRequest.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: patient in: query schema: type: string - name: status in: query schema: type: string - name: category in: query schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' post: tags: - ServiceRequest summary: Create a service request operationId: createServiceRequest security: - oauth2: - system/ServiceRequest.write requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_ServiceRequest' responses: '201': description: ServiceRequest created content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_ServiceRequest' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /ServiceRequest/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - ServiceRequest summary: Read a service request operationId: readServiceRequest security: - oauth2: - system/ServiceRequest.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: ServiceRequest resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_ServiceRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' put: tags: - ServiceRequest summary: Update a service request operationId: updateServiceRequest security: - oauth2: - system/ServiceRequest.write parameters: - $ref: '#/components/parameters/fhirId' requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_ServiceRequest' responses: '200': description: ServiceRequest updated content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_ServiceRequest' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Subscription: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Subscription summary: Search subscriptions operationId: searchSubscription security: - oauth2: - system/Subscription.read parameters: - $ref: '#/components/parameters/fhirSearchId' - $ref: '#/components/parameters/fhirLastUpdated' - $ref: '#/components/parameters/fhirCount' - $ref: '#/components/parameters/fhirSort' - name: status in: query schema: type: string responses: '200': $ref: '#/components/responses/FHIRBundle' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '429': $ref: '#/components/responses/FHIRTooManyRequests' post: tags: - Subscription summary: Create a subscription description: | Registers a `Subscription` so mdhub sends `rest-hook` webhook notifications to your endpoint when resources matching the `criteria` change. operationId: createSubscription security: - oauth2: - system/Subscription.write requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Subscription' responses: '201': description: Subscription created content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Subscription' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' /Subscription/{id}: servers: - url: https://api.mdhub.ai/v1/fhir/R4 get: tags: - Subscription summary: Read a subscription operationId: readSubscription security: - oauth2: - system/Subscription.read parameters: - $ref: '#/components/parameters/fhirId' responses: '200': description: Subscription resource content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Subscription' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '429': $ref: '#/components/responses/FHIRTooManyRequests' put: tags: - Subscription summary: Update a subscription operationId: updateSubscription security: - oauth2: - system/Subscription.write parameters: - $ref: '#/components/parameters/fhirId' requestBody: required: true content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Subscription' responses: '200': description: Subscription updated content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Subscription' '400': $ref: '#/components/responses/FHIRBadRequest' '401': $ref: '#/components/responses/FHIRUnauthorized' '403': $ref: '#/components/responses/FHIRForbidden' '404': $ref: '#/components/responses/FHIRNotFound' '422': $ref: '#/components/responses/FHIRUnprocessable' '429': $ref: '#/components/responses/FHIRTooManyRequests' components: securitySchemes: api_key: type: apiKey name: x-api-key in: header description: API key for authentication oauth2: type: oauth2 description: | OAuth 2.0 following the SMART Backend Services (system-to-system) profile. Request an access token using the `client_credentials` grant and send it as a bearer token on FHIR R4 requests. Access is controlled with SMART v2 system scopes (for example `system/Patient.read`, `system/Appointment.write`). flows: clientCredentials: tokenUrl: https://api.mdhub.ai/v1/oauth2/token scopes: system/*.read: Read access to all FHIR resources system/*.write: Write access to all FHIR resources system/Patient.read: Read Patient resources system/Patient.write: Create/update Patient resources system/RelatedPerson.read: Read RelatedPerson resources system/RelatedPerson.write: Create/update RelatedPerson resources system/Coverage.read: Read Coverage resources system/Coverage.write: Create/update Coverage resources system/CoverageEligibilityRequest.write: Submit eligibility requests system/CoverageEligibilityResponse.read: Read eligibility responses system/Condition.read: Read Condition resources system/Condition.write: Create/update Condition resources system/MedicationStatement.read: Read MedicationStatement resources system/MedicationStatement.write: Create/update MedicationStatement resources system/MedicationRequest.read: Read MedicationRequest resources system/MedicationRequest.write: Create/update MedicationRequest resources system/AllergyIntolerance.read: Read AllergyIntolerance resources system/AllergyIntolerance.write: Create/update AllergyIntolerance resources system/Consent.read: Read Consent resources system/Consent.write: Create/update Consent resources system/Practitioner.read: Read Practitioner resources system/PractitionerRole.read: Read PractitionerRole resources system/Location.read: Read Location resources system/Organization.read: Read Organization resources system/Schedule.read: Read Schedule resources system/Slot.read: Read Slot resources system/Appointment.read: Read Appointment resources system/Appointment.write: Create/update Appointment resources system/Encounter.read: Read Encounter resources system/Encounter.write: Create/update Encounter resources system/Observation.read: Read Observation resources system/Observation.write: Create/update Observation resources system/Questionnaire.read: Read Questionnaire resources system/Questionnaire.write: Create/update Questionnaire resources system/QuestionnaireResponse.read: Read QuestionnaireResponse resources system/QuestionnaireResponse.write: Create/update QuestionnaireResponse resources system/DocumentReference.read: Read DocumentReference resources system/DocumentReference.write: Create/update DocumentReference resources system/ServiceRequest.read: Read ServiceRequest resources system/ServiceRequest.write: Create/update ServiceRequest resources system/Subscription.read: Read Subscription resources system/Subscription.write: Create/update Subscription resources parameters: fhirId: name: id in: path required: true description: The logical id of the resource. schema: type: string fhirSearchId: name: _id in: query required: false description: >- The logical id of the resource to search for. Matched exactly and case-sensitively; it does not accept the system|value form. A resource belonging to another clinic returns no match rather than an error. schema: type: string fhirLastUpdated: name: _lastUpdated in: query required: false description: >- Filter by last-updated time. Accepts the prefixes ge, gt, le and lt, or no prefix at all, which matches the whole period given. A bare date such as 2026-08-01 therefore covers that entire day. schema: type: string fhirCount: name: _count in: query required: false description: >- Number of results per page. Defaults to 50 and is capped at 100: a larger value returns 100 rather than an error. schema: type: integer default: 50 maximum: 100 fhirPage: name: _page in: query required: false description: >- Pagination cursor. Do not build this value yourself — take the `next` link from the Bundle and send that URL unchanged. The cursor is opaque and its format may change. schema: type: string fhirSort: name: _sort in: query required: false description: Comma-separated list of fields to sort by (prefix with '-' for descending). schema: type: string responses: UnauthorizedError: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' TooManyRequests: description: Too Many Requests - Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' FHIRBundle: description: A searchset Bundle of matching resources. content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_Bundle' FHIRBadRequest: description: Bad request - malformed resource or parameters. content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_OperationOutcome' FHIRUnauthorized: description: Unauthorized - missing or invalid bearer token. content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_OperationOutcome' FHIRForbidden: description: Forbidden - the token lacks the required scope. content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_OperationOutcome' FHIRNotFound: description: The requested resource was not found. content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_OperationOutcome' FHIRUnprocessable: description: Unprocessable entity - the resource failed validation. content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_OperationOutcome' FHIRTooManyRequests: description: Too Many Requests - rate limit exceeded. content: application/fhir+json: schema: $ref: '#/components/schemas/FHIR_OperationOutcome' schemas: UploadQuestionnaireDataRequest: type: object required: - questionnaireData properties: patientInfo: $ref: '#/components/schemas/QuestionnairePatientInfo' questionnaireData: $ref: '#/components/schemas/QuestionnaireData' UploadQuestionnaireDataResponse: type: object required: - success properties: success: type: boolean example: true message: type: string patientQuestionnaireId: type: string description: ID of the stored questionnaire on the mdhub side. example: pq_123abc QuestionnairePatientInfo: type: object description: > Patient context supplied with the questionnaire submission. Used to map the data with the patient object on the mdhub side. properties: patientId: type: string description: Patient ID (mdhub?) example: patient_123 patientName: type: string description: Patient name. example: John Doe QuestionnaireData: type: object description: > Filled questionnaire payload shaped for questionnaire-response-handler.ts. The payload includes questionnaire metadata plus the filled schema array. required: - title - schema properties: title: type: string description: Questionnaire title. example: Intake Questionnaire description: type: string description: Questionnaire description, optional. example: Initial intake form completed before the first session. questionnaireId: type: string description: ID from the extenal user, optional. example: questionnaire_123 schema: type: array minItems: 1 description: > Ordered questionnaire inputs, including section title items and filled responses. items: $ref: '#/components/schemas/QuestionnaireSchemaItem' QuestionnaireSchemaItem: type: object description: > Questionnaire input item. Response shape varies by input type. required: - id - title - description - order - type - required properties: id: type: string description: Unique input identifier, optional. example: input_123 title: type: string description: Input title or section title. example: Current symptoms description: type: string description: Input description. example: Tell us more about your symptoms. order: type: integer description: Display order of the input in the questionnaire. example: 0 type: type: string enum: - input_free_text - input_single - input_multiple - input_list - input_title - input_number - input_likert - dropdown_single - dropdown_multiple required: type: boolean description: Whether the input is required. options: type: array description: Available options for single, multiple, and dropdown inputs. items: type: string requireComment: type: array description: Option values that should collect a follow-up comment. items: type: string comment: type: string description: Optional comment captured for the selected response. columns: type: array description: Column names for list/table inputs. items: type: string prefix: type: string description: Unit or prefix for number inputs. example: lbs questions: type: array description: Question labels for likert inputs. items: type: string scale: $ref: '#/components/schemas/QuestionnaireLikertScale' response: description: > Filled response value. String for free text, single, dropdown-single, and number inputs; array of strings for multiple and dropdown-multiple; array of list column objects for list inputs; array of question/response objects for likert inputs. Title inputs typically omit response. anyOf: - type: string - type: array items: type: string - type: array items: $ref: '#/components/schemas/QuestionnaireListResponseColumn' - type: array items: $ref: '#/components/schemas/QuestionnaireLikertResponse' QuestionnaireLikertScale: type: object description: Likert scale metadata. Some imported questionnaires may send null instead. properties: label: type: string example: 4-point scale frequency value: type: string example: 4_point_scale_frequency items: type: array items: type: string example: - Not at all - Several days - More than half the days - Nearly every day QuestionnaireLikertResponse: type: object required: - question - response properties: question: type: string example: Feeling nervous, anxious, or on edge response: type: string example: Several days QuestionnaireListResponseColumn: type: object description: > List/table column responses. `column` or `col` are both accepted. required: - responses properties: col: type: string description: Preferred column key. example: Medication column: type: string description: Legacy/alternate column key used by some questionnaire creation flows. example: Medication responses: type: array items: type: string example: - Sertraline - Bupropion SubmitQuestionnaireRequest: type: object required: - patientId - questionnaire properties: patientId: type: string description: ID of the patient (as returned by the create patient endpoint). example: abc123 questionnaire: $ref: '#/components/schemas/SubmitQuestionnaireData' SubmitQuestionnaireData: type: object description: > Filled custom-questionnaire payload accepted by `/questionnaires/submit`. Same shape as `QuestionnaireData`, but each schema item only requires `title` and `type` — `id`, `order`, `description`, and `required` are auto-filled by the server when omitted. required: - title - schema properties: title: type: string description: Questionnaire title. example: New Patient Intake description: type: string description: Questionnaire description, optional. example: Completed before the first visit. type: type: string description: Questionnaire kind, optional. Defaults to `questionnaire_follow_up`. enum: - questionnaire_intake - questionnaire_follow_up - questionnaire_screening - questionnaire_intake_agent questionnaireId: type: string description: External questionnaire identifier, optional. example: intake_v1 schema: type: array minItems: 1 description: > Ordered questionnaire inputs, including section title items and filled responses. items: $ref: '#/components/schemas/SubmitQuestionnaireSchemaItem' SubmitQuestionnaireSchemaItem: type: object description: > Questionnaire input item for `/questionnaires/submit`. Response shape varies by input type. Only `title` and `type` are required: `id` is generated server-side via UUID, `order` via array position starting at 1, `description` defaults to `""`, and `required` defaults to `false`. Any client-supplied `id` or `order` is ignored. required: - title - type properties: title: type: string example: Current symptoms description: type: string type: type: string enum: - input_free_text - input_single - input_multiple - input_list - input_title - input_number - input_likert - dropdown_single - dropdown_multiple required: type: boolean options: type: array description: Available options for single, multiple, and dropdown inputs. items: type: string requireComment: type: array description: Option values that should collect a follow-up comment. items: type: string comment: type: string description: Optional comment captured for the selected response. columns: type: array description: Column names for list/table inputs. items: type: string prefix: type: string description: Unit or prefix for number inputs. questions: type: array description: Question labels for likert inputs. items: type: string scale: $ref: '#/components/schemas/QuestionnaireLikertScale' response: description: > Filled response value. String for free text, single, dropdown-single, and number inputs; array of strings for multiple and dropdown-multiple; array of list column objects for list inputs; array of question/ response objects for likert inputs. Title inputs typically omit response. anyOf: - type: string - type: array items: type: string - type: array items: $ref: '#/components/schemas/QuestionnaireListResponseColumn' - type: array items: $ref: '#/components/schemas/QuestionnaireLikertResponse' SubmitQuestionnaireResponse: type: object required: - patientQuestionnaireId properties: patientQuestionnaireId: type: string description: ID of the stored patient-questionnaire on the mdhub side. example: pq_123abc SubmitMdhubQuestionnaireRequest: type: object required: - patientId - mdhubType - responses properties: patientId: type: string description: ID of the patient (as returned by the create patient endpoint). example: abc123 mdhubType: type: string description: | Identifier of the mdhub-managed standardized questionnaire. The server resolves this to the corresponding questionnaire schema and uses it to map each entry in `responses` to the proper response label. enum: - mdhub-phq-9 - mdhub-gad-7 - mdhub-madrs example: mdhub-gad-7 responses: type: array minItems: 1 description: | Raw integer scores in question order. - **PHQ-9 / GAD-7**: each entry is a 0–3 score on the 4-point frequency scale ("Not at all", "Several days", "More than half the days", "Nearly every day"). Length must be 9 (PHQ-9) or 7 (GAD-7). - **MADRS**: each entry is a 0–6 score against the item's options. Length must be 10. items: type: integer example: [0, 2, 1, 3, 1, 0, 2] ValidationErrorResponse: type: object description: > Returned when one or more inputs fail validation. `issues` lists every offending field at once so callers can correct them in a single round-trip. required: - message properties: message: type: string example: Validation failed issues: type: array items: type: object required: - path - message properties: path: type: string example: responses.0 message: type: string example: 'responses[0] = 1000 is out of range for mdhub-gad-7 (allowed: 0..3)' UpdatePatientRequest: type: object description: > Partial patient update payload. All fields are optional; only the fields provided are updated. For array fields, each item may carry an optional `id` for upsert (a matching id updates that entry, a missing id appends a new one). properties: firstName: type: string example: Alice lastName: type: string example: Johnson middleName: type: string example: Marie gender: type: string enum: - Male - Female - Non-binary - Prefer not to say - Other - Unknown example: Female genderIdentity: type: string example: Non-binary pronoun: type: string enum: - he/him - she/her - they/them example: they/them dateOfBirth: type: string description: Date of birth in MM/DD/YYYY format example: 06/28/1996 raceEthnicity: type: string enum: - White - Black or African American - Asian - Hispanic or Latino - American Indian or Alaska Native - Native Hawaiian or Other Pacific Islander - Other - Prefer not to say email: type: string format: email example: patient@test.com phoneNumber: type: string example: '+12025551234' address: type: object properties: address1: type: string example: 123 Main St address2: type: string example: Apt 4B city: type: string example: New York state: type: string description: 2-letter US state code example: NY zip: type: string example: '10001' diagnoses: type: array items: type: object properties: id: type: string description: Existing diagnosisId to update; omit to append a new diagnosis. example: '1718000000000' code: type: string example: F32.1 description: type: string example: Major depressive disorder, single episode, moderate relatedContacts: type: array items: type: object properties: id: type: string description: Existing emergency-contact id to update; omit to append a new contact. fullName: type: string example: Jane Doe email: type: string example: jane@example.com phones: type: array items: type: string example: - '+12025551234' relationship: type: string example: Spouse hipaaConsent: type: boolean example: true insurances: type: array items: type: object properties: id: type: string description: Existing insurance id to update; omit to append a new insurance. tradingPartnerName: type: string example: Blue Cross Blue Shield memberId: type: string example: XYZ123456789 groupNumber: type: string example: GRP001 company: type: string example: Anthem isPrimary: type: boolean example: true medications: type: array items: type: object properties: id: type: string description: Existing medicationId to update; omit to append a new medication. name: type: string example: sildenafil 25 MG Oral Tablet [Viagra] brandName: type: string example: Viagra genericName: type: string example: sildenafil strength: type: string example: 25 MG route: type: string example: by mouth form: type: string example: Oral Tablet reason: type: string example: Depression comment: type: string example: Take with food currentMedication: type: boolean example: true date: type: string example: 2026-01-15 stopDate: type: string example: 2026-06-01 dosage: type: object properties: dose: type: string example: '2' doseUnit: type: string example: tablet doseTiming: type: string example: twice a day duration: type: string example: '30' quantity: type: string example: '60' refills: type: string example: '3' asNeeded: type: boolean example: false allergies: type: array items: type: object properties: id: type: string description: Existing allergyId to update; omit to append a new allergy. name: type: string example: glutamic acid reactions: type: array items: type: string example: - asthma - rash severity: type: string example: Severe notes: type: string example: Causes severe respiratory distress CallsResponse: type: object properties: calls: type: array items: $ref: '#/components/schemas/Call' nextPageToken: type: string description: Token for fetching the next page. Null when there are no more results. example: conv_456def hasMore: type: boolean description: Whether there are more results available. example: true totalCount: type: integer description: Number of calls in the current page. example: 25 Call: type: object properties: id: type: string description: The unique identifier of the call. example: conv_123abc startedAt: type: string format: date-time description: ISO 8601 timestamp when the call started. example: 2026-01-15T14:30:00.000Z endedAt: type: string format: date-time description: ISO 8601 timestamp when the call ended. example: 2026-01-15T14:42:00.000Z callerPhoneNumber: type: string description: Phone number the call originated from. example: '+12025551234' isReviewed: type: boolean example: false hasCalledBefore: type: boolean example: true totalNumberOfPreviousCalls: type: integer example: 3 summary: type: string description: AI-generated summary of the call. example: Patient called to reschedule their appointment. interactions: type: array description: Ordered transcript of the call. items: $ref: '#/components/schemas/Interaction' Interaction: type: object properties: speaker: type: string description: Who produced the message. enum: - ai-agent - patient example: patient text: type: string description: The transcribed text of the interaction. example: I would like to move my appointment to next week. ErrorResponse: type: object properties: message: type: string example: Invalid input InternalErrorResponse: type: object properties: error: type: string example: Internal server error Patient: type: object properties: id: type: string patientName: type: string gender: type: string enum: [male, female, other] pronoun: type: string enum: ['he/him', 'she/her', 'they/them'] dob: type: string format: date patientEmail: type: string format: email age: type: integer minimum: 0 raceEthnicity: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time PatientInput: type: object required: - patientName properties: patientName: type: string gender: type: string enum: [male, female, other] pronoun: type: string enum: ['he/him', 'she/her', 'they/them'] dob: type: string format: date patientEmail: type: string format: email raceEthnicity: type: string Session: type: object properties: id: type: string patientId: type: string templateId: type: string status: type: string enum: [ 'created', 'in_progress_transcript', 'in_progress_summary', 'completed', 'failure_transcript', 'failure_summary', 'audio_too_short', 'non_medical_conversation', 'Ready for review', 'Reviewed', ] audioUrl: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time Template: type: object properties: id: type: string name: type: string content: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time sections: type: array items: type: object properties: id: type: string name: type: string order: type: integer content: type: string FHIR_Meta: type: object description: Metadata about a FHIR resource. properties: versionId: type: string example: '3' lastUpdated: type: string format: date-time example: 2026-01-15T14:30:00.000Z FHIR_Coding: type: object properties: system: type: string example: http://loinc.org code: type: string example: 44249-1 display: type: string example: PHQ-9 total score FHIR_CodeableConcept: type: object properties: coding: type: array items: $ref: '#/components/schemas/FHIR_Coding' text: type: string example: PHQ-9 total score FHIR_Identifier: type: object properties: use: type: string example: official system: type: string example: https://mdhub.ai/ids/bestnotes value: type: string example: abc123 FHIR_Reference: type: object properties: reference: type: string example: Patient/abc123 display: type: string example: Alice Johnson FHIR_Period: type: object properties: start: type: string format: date-time example: 2026-01-15T14:30:00.000Z end: type: string format: date-time example: 2026-01-15T15:00:00.000Z FHIR_HumanName: type: object properties: use: type: string example: official family: type: string example: Johnson given: type: array items: type: string example: - Alice - Marie text: type: string example: Alice Marie Johnson FHIR_ContactPoint: type: object properties: system: type: string enum: - phone - email - sms example: email value: type: string example: patient@test.com use: type: string example: home FHIR_Address: type: object properties: use: type: string example: home line: type: array items: type: string example: - 123 Main St - Apt 4B city: type: string example: New York state: type: string example: NY postalCode: type: string example: '10001' country: type: string example: US FHIR_OperationOutcome: type: object description: FHIR OperationOutcome returned for errors. required: - resourceType - issue properties: resourceType: type: string example: OperationOutcome issue: type: array items: type: object properties: severity: type: string enum: - fatal - error - warning - information example: error code: type: string example: not-found diagnostics: type: string example: Patient/abc123 was not found. example: resourceType: OperationOutcome issue: - severity: error code: not-found diagnostics: Patient/abc123 was not found. FHIR_Bundle: type: object description: A FHIR Bundle, typically of type searchset for search results. required: - resourceType - type properties: resourceType: type: string example: Bundle type: type: string example: searchset total: type: integer example: 2 link: type: array items: type: object properties: relation: type: string example: next url: type: string example: https://api.mdhub.ai/v1/fhir/R4/Patient?_count=50&_page=2 entry: type: array items: type: object properties: fullUrl: type: string example: https://api.mdhub.ai/v1/fhir/R4/Patient/abc123 resource: type: object description: A FHIR resource instance. search: type: object properties: mode: type: string example: match FHIR_CapabilityStatement: type: object description: FHIR CapabilityStatement describing supported resources and interactions. required: - resourceType - status - fhirVersion properties: resourceType: type: string example: CapabilityStatement status: type: string example: active date: type: string format: date-time example: 2026-01-01T00:00:00.000Z publisher: type: string example: mdhub kind: type: string example: instance fhirVersion: type: string example: 4.0.1 format: type: array items: type: string example: - application/fhir+json rest: type: array items: type: object properties: mode: type: string example: server security: type: object properties: service: type: array items: $ref: '#/components/schemas/FHIR_CodeableConcept' resource: type: array items: type: object properties: type: type: string example: Patient interaction: type: array items: type: object properties: code: type: string example: read example: resourceType: CapabilityStatement status: active fhirVersion: 4.0.1 format: - application/fhir+json rest: - mode: server resource: - type: Patient interaction: - code: read - code: search-type - code: create - code: update - type: Appointment interaction: - code: read - code: search-type - code: create - code: update FHIR_Patient: type: object required: - resourceType properties: resourceType: type: string example: Patient id: type: string example: abc123 meta: $ref: '#/components/schemas/FHIR_Meta' identifier: type: array items: $ref: '#/components/schemas/FHIR_Identifier' active: type: boolean example: true name: type: array items: $ref: '#/components/schemas/FHIR_HumanName' telecom: type: array items: $ref: '#/components/schemas/FHIR_ContactPoint' gender: type: string enum: - male - female - other - unknown example: female birthDate: type: string format: date example: '1996-06-28' address: type: array items: $ref: '#/components/schemas/FHIR_Address' example: resourceType: Patient id: abc123 active: true name: - use: official family: Johnson given: - Alice - Marie telecom: - system: email value: patient@test.com - system: phone value: '+12025551234' gender: female birthDate: '1996-06-28' address: - line: - 123 Main St - Apt 4B city: New York state: NY postalCode: '10001' FHIR_RelatedPerson: type: object required: - resourceType - patient properties: resourceType: type: string example: RelatedPerson id: type: string meta: $ref: '#/components/schemas/FHIR_Meta' patient: $ref: '#/components/schemas/FHIR_Reference' relationship: type: array items: $ref: '#/components/schemas/FHIR_CodeableConcept' name: type: array items: $ref: '#/components/schemas/FHIR_HumanName' telecom: type: array items: $ref: '#/components/schemas/FHIR_ContactPoint' example: resourceType: RelatedPerson patient: reference: Patient/abc123 relationship: - text: Spouse name: - text: Jane Doe telecom: - system: phone value: '+12025551234' FHIR_Coverage: type: object required: - resourceType - beneficiary properties: resourceType: type: string example: Coverage id: type: string meta: $ref: '#/components/schemas/FHIR_Meta' status: type: string example: active subscriberId: type: string example: XYZ123456789 beneficiary: $ref: '#/components/schemas/FHIR_Reference' payor: type: array items: $ref: '#/components/schemas/FHIR_Reference' class: type: array items: type: object properties: type: $ref: '#/components/schemas/FHIR_CodeableConcept' value: type: string example: GRP001 name: type: string example: Blue Cross Blue Shield order: type: integer example: 1 example: resourceType: Coverage status: active subscriberId: XYZ123456789 beneficiary: reference: Patient/abc123 payor: - display: Anthem class: - type: text: group value: GRP001 name: Blue Cross Blue Shield order: 1 FHIR_CoverageEligibilityRequest: type: object required: - resourceType - patient properties: resourceType: type: string example: CoverageEligibilityRequest id: type: string status: type: string example: active purpose: type: array items: type: string example: - benefits patient: $ref: '#/components/schemas/FHIR_Reference' insurer: $ref: '#/components/schemas/FHIR_Reference' item: type: array items: type: object properties: category: $ref: '#/components/schemas/FHIR_CodeableConcept' productOrService: $ref: '#/components/schemas/FHIR_CodeableConcept' example: resourceType: CoverageEligibilityRequest status: active purpose: - benefits patient: reference: Patient/abc123 insurer: display: Anthem item: - category: text: Behavioral health productOrService: text: TMS treatment course FHIR_CoverageEligibilityResponse: type: object required: - resourceType properties: resourceType: type: string example: CoverageEligibilityResponse id: type: string status: type: string example: active outcome: type: string example: complete patient: $ref: '#/components/schemas/FHIR_Reference' insurance: type: array items: type: object properties: coverage: $ref: '#/components/schemas/FHIR_Reference' inforce: type: boolean example: true item: type: array items: type: object properties: category: $ref: '#/components/schemas/FHIR_CodeableConcept' benefit: type: array items: type: object properties: type: $ref: '#/components/schemas/FHIR_CodeableConcept' allowedUnsignedInt: type: integer example: 20 usedUnsignedInt: type: integer example: 4 example: resourceType: CoverageEligibilityResponse status: active outcome: complete patient: reference: Patient/abc123 insurance: - inforce: true item: - category: text: Behavioral health - outpatient benefit: - type: text: Sessions approved allowedUnsignedInt: 20 usedUnsignedInt: 4 FHIR_Condition: type: object required: - resourceType - subject properties: resourceType: type: string example: Condition id: type: string clinicalStatus: $ref: '#/components/schemas/FHIR_CodeableConcept' code: $ref: '#/components/schemas/FHIR_CodeableConcept' subject: $ref: '#/components/schemas/FHIR_Reference' recordedDate: type: string format: date-time example: resourceType: Condition clinicalStatus: text: active code: coding: - system: http://hl7.org/fhir/sid/icd-10-cm code: F32.1 display: Major depressive disorder, single episode, moderate subject: reference: Patient/abc123 FHIR_MedicationStatement: type: object required: - resourceType - subject properties: resourceType: type: string example: MedicationStatement id: type: string status: type: string example: active medicationCodeableConcept: $ref: '#/components/schemas/FHIR_CodeableConcept' subject: $ref: '#/components/schemas/FHIR_Reference' effectiveDateTime: type: string format: date-time dosage: type: array items: type: object properties: text: type: string example: 2 tablets twice a day example: resourceType: MedicationStatement status: active medicationCodeableConcept: text: sildenafil 25 MG Oral Tablet [Viagra] subject: reference: Patient/abc123 dosage: - text: 2 tablets twice a day FHIR_MedicationRequest: type: object required: - resourceType - subject properties: resourceType: type: string example: MedicationRequest id: type: string status: type: string example: active intent: type: string example: order medicationCodeableConcept: $ref: '#/components/schemas/FHIR_CodeableConcept' subject: $ref: '#/components/schemas/FHIR_Reference' authoredOn: type: string format: date-time requester: $ref: '#/components/schemas/FHIR_Reference' dosageInstruction: type: array items: type: object properties: text: type: string example: Take 1 tablet by mouth at bedtime example: resourceType: MedicationRequest status: active intent: order medicationCodeableConcept: text: sertraline 50 MG Oral Tablet subject: reference: Patient/abc123 dosageInstruction: - text: Take 1 tablet by mouth daily FHIR_AllergyIntolerance: type: object required: - resourceType - patient properties: resourceType: type: string example: AllergyIntolerance id: type: string clinicalStatus: $ref: '#/components/schemas/FHIR_CodeableConcept' code: $ref: '#/components/schemas/FHIR_CodeableConcept' patient: $ref: '#/components/schemas/FHIR_Reference' criticality: type: string example: high reaction: type: array items: type: object properties: manifestation: type: array items: $ref: '#/components/schemas/FHIR_CodeableConcept' severity: type: string example: severe example: resourceType: AllergyIntolerance clinicalStatus: text: active code: text: glutamic acid patient: reference: Patient/abc123 criticality: high reaction: - manifestation: - text: asthma - text: rash severity: severe FHIR_Consent: type: object required: - resourceType - patient properties: resourceType: type: string example: Consent id: type: string status: type: string example: active scope: $ref: '#/components/schemas/FHIR_CodeableConcept' category: type: array items: $ref: '#/components/schemas/FHIR_CodeableConcept' patient: $ref: '#/components/schemas/FHIR_Reference' dateTime: type: string format: date-time example: resourceType: Consent status: active scope: text: patient-privacy category: - text: HIPAA Authorization patient: reference: Patient/abc123 dateTime: 2026-01-15T14:30:00.000Z FHIR_Practitioner: type: object required: - resourceType properties: resourceType: type: string example: Practitioner id: type: string identifier: type: array items: $ref: '#/components/schemas/FHIR_Identifier' active: type: boolean example: true name: type: array items: $ref: '#/components/schemas/FHIR_HumanName' telecom: type: array items: $ref: '#/components/schemas/FHIR_ContactPoint' example: resourceType: Practitioner active: true name: - family: Smith given: - Robert text: Dr. Robert Smith FHIR_PractitionerRole: type: object required: - resourceType properties: resourceType: type: string example: PractitionerRole id: type: string practitioner: $ref: '#/components/schemas/FHIR_Reference' organization: $ref: '#/components/schemas/FHIR_Reference' code: type: array items: $ref: '#/components/schemas/FHIR_CodeableConcept' specialty: type: array items: $ref: '#/components/schemas/FHIR_CodeableConcept' location: type: array items: $ref: '#/components/schemas/FHIR_Reference' example: resourceType: PractitionerRole practitioner: reference: Practitioner/prac123 specialty: - text: Psychiatry location: - reference: Location/loc123 FHIR_Location: type: object required: - resourceType properties: resourceType: type: string example: Location id: type: string status: type: string example: active name: type: string example: Denver Clinic telecom: type: array items: $ref: '#/components/schemas/FHIR_ContactPoint' address: $ref: '#/components/schemas/FHIR_Address' managingOrganization: $ref: '#/components/schemas/FHIR_Reference' example: resourceType: Location status: active name: Denver Clinic address: line: - 456 Broadway city: Denver state: CO postalCode: '80203' FHIR_Organization: type: object required: - resourceType properties: resourceType: type: string example: Organization id: type: string active: type: boolean example: true name: type: string example: Example Behavioral Health telecom: type: array items: $ref: '#/components/schemas/FHIR_ContactPoint' address: type: array items: $ref: '#/components/schemas/FHIR_Address' example: resourceType: Organization active: true name: Example Behavioral Health FHIR_Schedule: type: object required: - resourceType - actor properties: resourceType: type: string example: Schedule id: type: string active: type: boolean example: true serviceType: type: array items: $ref: '#/components/schemas/FHIR_CodeableConcept' actor: type: array items: $ref: '#/components/schemas/FHIR_Reference' planningHorizon: $ref: '#/components/schemas/FHIR_Period' example: resourceType: Schedule active: true serviceType: - text: Psychiatry actor: - reference: Practitioner/prac123 FHIR_Slot: type: object required: - resourceType - schedule - status - start - end properties: resourceType: type: string example: Slot id: type: string schedule: $ref: '#/components/schemas/FHIR_Reference' status: type: string enum: - free - busy - busy-tentative - busy-unavailable example: free start: type: string format: date-time example: 2026-02-01T15:00:00.000Z end: type: string format: date-time example: 2026-02-01T15:30:00.000Z example: resourceType: Slot schedule: reference: Schedule/sch123 status: free start: 2026-02-01T15:00:00.000Z end: 2026-02-01T15:30:00.000Z FHIR_Appointment: type: object required: - resourceType - status - participant properties: resourceType: type: string example: Appointment id: type: string status: type: string enum: - proposed - pending - booked - arrived - fulfilled - cancelled - noshow example: booked serviceType: type: array items: $ref: '#/components/schemas/FHIR_CodeableConcept' start: type: string format: date-time example: 2026-02-01T15:00:00.000Z end: type: string format: date-time example: 2026-02-01T15:30:00.000Z slot: type: array items: $ref: '#/components/schemas/FHIR_Reference' participant: type: array items: type: object properties: actor: $ref: '#/components/schemas/FHIR_Reference' status: type: string example: accepted example: resourceType: Appointment status: booked serviceType: - text: Psychiatry start: 2026-02-01T15:00:00.000Z end: 2026-02-01T15:30:00.000Z slot: - reference: Slot/slot123 participant: - actor: reference: Patient/abc123 status: accepted - actor: reference: Practitioner/prac123 status: accepted FHIR_Encounter: type: object required: - resourceType - status - subject properties: resourceType: type: string example: Encounter id: type: string status: type: string example: finished class: $ref: '#/components/schemas/FHIR_Coding' type: type: array items: $ref: '#/components/schemas/FHIR_CodeableConcept' subject: $ref: '#/components/schemas/FHIR_Reference' participant: type: array items: type: object properties: individual: $ref: '#/components/schemas/FHIR_Reference' period: $ref: '#/components/schemas/FHIR_Period' example: resourceType: Encounter status: finished class: code: AMB display: ambulatory type: - text: Medication management subject: reference: Patient/abc123 period: start: 2026-02-01T15:00:00.000Z end: 2026-02-01T15:30:00.000Z FHIR_Observation: type: object required: - resourceType - status - code - subject properties: resourceType: type: string example: Observation id: type: string status: type: string example: final category: type: array items: $ref: '#/components/schemas/FHIR_CodeableConcept' code: $ref: '#/components/schemas/FHIR_CodeableConcept' subject: $ref: '#/components/schemas/FHIR_Reference' effectiveDateTime: type: string format: date-time valueQuantity: type: object properties: value: type: number example: 12 unit: type: string example: '{score}' example: resourceType: Observation status: final category: - text: survey code: coding: - system: http://loinc.org code: 44249-1 display: PHQ-9 total score subject: reference: Patient/abc123 effectiveDateTime: 2026-02-01T15:30:00.000Z valueQuantity: value: 12 unit: '{score}' FHIR_Questionnaire: type: object required: - resourceType - status properties: resourceType: type: string example: Questionnaire id: type: string title: type: string example: New Patient Intake status: type: string example: active item: type: array items: type: object properties: linkId: type: string example: '1' text: type: string example: What brings you in today? type: type: string example: text example: resourceType: Questionnaire title: New Patient Intake status: active item: - linkId: '1' text: What brings you in today? type: text FHIR_QuestionnaireResponse: type: object required: - resourceType - status properties: resourceType: type: string example: QuestionnaireResponse id: type: string questionnaire: type: string example: Questionnaire/intake_v1 status: type: string example: completed subject: $ref: '#/components/schemas/FHIR_Reference' authored: type: string format: date-time item: type: array items: type: object properties: linkId: type: string example: '1' text: type: string example: What brings you in today? answer: type: array items: type: object properties: valueString: type: string example: Trouble sleeping for the past 3 weeks. example: resourceType: QuestionnaireResponse questionnaire: Questionnaire/intake_v1 status: completed subject: reference: Patient/abc123 authored: 2026-02-01T14:00:00.000Z item: - linkId: '1' text: What brings you in today? answer: - valueString: Trouble sleeping for the past 3 weeks. FHIR_DocumentReference: type: object required: - resourceType - status - content properties: resourceType: type: string example: DocumentReference id: type: string status: type: string example: current type: $ref: '#/components/schemas/FHIR_CodeableConcept' subject: $ref: '#/components/schemas/FHIR_Reference' date: type: string format: date-time content: type: array items: type: object properties: attachment: type: object properties: contentType: type: string example: text/plain url: type: string example: https://api.mdhub.ai/v1/fhir/R4/Binary/doc123 title: type: string example: Session transcript example: resourceType: DocumentReference status: current type: text: Session transcript subject: reference: Patient/abc123 date: 2026-02-01T15:30:00.000Z content: - attachment: contentType: text/plain title: Session transcript url: https://api.mdhub.ai/v1/fhir/R4/Binary/doc123 FHIR_ServiceRequest: type: object required: - resourceType - status - intent - subject properties: resourceType: type: string example: ServiceRequest id: type: string status: type: string example: active intent: type: string example: order category: type: array items: $ref: '#/components/schemas/FHIR_CodeableConcept' code: $ref: '#/components/schemas/FHIR_CodeableConcept' subject: $ref: '#/components/schemas/FHIR_Reference' requester: $ref: '#/components/schemas/FHIR_Reference' performer: type: array items: $ref: '#/components/schemas/FHIR_Reference' example: resourceType: ServiceRequest status: active intent: order category: - text: Referral code: text: TMS evaluation subject: reference: Patient/abc123 requester: reference: Practitioner/prac123 FHIR_Subscription: type: object required: - resourceType - status - criteria - channel properties: resourceType: type: string example: Subscription id: type: string status: type: string enum: - requested - active - error - 'off' example: active reason: type: string example: Notify on new appointments criteria: type: string example: Appointment?status=booked channel: type: object properties: type: type: string example: rest-hook endpoint: type: string example: https://example.com/webhooks/mdhub payload: type: string example: application/fhir+json header: type: array items: type: string example: - Authorization: Bearer secret-token example: resourceType: Subscription status: active reason: Notify on new appointments criteria: Appointment?status=booked channel: type: rest-hook endpoint: https://example.com/webhooks/mdhub payload: application/fhir+json security: - api_key: []