@healthcloudai/hc-sdk 3.6.1 → 3.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/dist/index.cjs +44 -0
  2. package/dist/index.d.cts +905 -30
  3. package/dist/index.d.ts +905 -30
  4. package/dist/index.js +44 -0
  5. package/docs/clients/OpenAIClient.md +1 -1
  6. package/docs/clients/ProviderClient.md +7 -0
  7. package/docs/docs-manifest.json +23 -4
  8. package/docs/examples/index.md +8 -1
  9. package/docs/index.md +8 -1
  10. package/docs/models/GetScanUploadUrlRequest.md +1 -1
  11. package/docs/models/OpenAIChatJsonRequest.md +1 -0
  12. package/docs/models/ProviderAppointment.md +24 -0
  13. package/docs/models/ProviderAppointmentResponse.md +17 -0
  14. package/docs/models/ProviderAppointmentsResponse.md +18 -0
  15. package/docs/models/ProviderEncounterListResponse.md +18 -0
  16. package/docs/models/ProviderEncounterResponse.md +17 -0
  17. package/docs/models/ProviderPatientAddress.md +22 -0
  18. package/docs/models/ProviderPatientPhone.md +19 -0
  19. package/docs/models/ProviderPatientRecordResponse.md +24 -0
  20. package/docs/models/ProviderPatientSummary.md +27 -0
  21. package/docs/models/UpdateEncounterClinicalNoteRequest.md +24 -0
  22. package/docs/models/UpdateEncounterClinicalNoteResponse.md +19 -0
  23. package/docs/models/UpdateEncounterStatusRequest.md +21 -0
  24. package/docs/models/UpdateEncounterStatusResponse.md +19 -0
  25. package/docs/models/index.md +13 -1
  26. package/docs/operations/connectors.athenaSearchAllergens.md +2 -2
  27. package/docs/operations/connectors.openaiChatJson.md +2 -2
  28. package/docs/operations/diagnostics.getScanUploadUrl.md +27 -11
  29. package/docs/operations/provider.getAppointment.md +148 -0
  30. package/docs/operations/provider.getEncounter.md +120 -0
  31. package/docs/operations/provider.getPatientRecord.md +122 -0
  32. package/docs/operations/provider.listAppointments.md +176 -0
  33. package/docs/operations/provider.listEncounters.md +123 -0
  34. package/docs/operations/provider.updateEncounterClinicalNote.md +154 -0
  35. package/docs/operations/provider.updateEncounterStatus.md +152 -0
  36. package/package.json +1 -1
  37. package/docs/models/AthenaSearchAllergensResponse.md +0 -15
@@ -2,7 +2,7 @@
2
2
 
3
3
  Operation ID: `diagnostics.getScanUploadUrl`
4
4
 
5
- Return a presigned URL for uploading a photo/scan of a rapid test result, associated with an existing test_id. Call diagnostics.createRapidTest first to obtain a test_id — this endpoint 404s if test_id does not resolve to an existing test for the patient.
5
+ Return a presigned URL for uploading a photo/scan of a rapid test result, associated with an existing test_id. The scanned kit's gtin is required — it resolves the same admin-managed test profile as diagnostics.lookupGS1, and the pending Observation's LOINC coding and display name come from that profile (no hardcoded product default). Unrecognized GTINs get a 404.
6
6
 
7
7
  ## Public method
8
8
 
@@ -49,10 +49,10 @@ Request model: [`GetScanUploadUrlRequest`](../models/GetScanUploadUrlRequest.md)
49
49
  ```json
50
50
  {
51
51
  "content_type": "image/jpeg",
52
- "encounter_id": "string",
53
- "filename": "scan.jpg",
54
- "gtin": "string",
55
- "test_id": "00000000-0000-0000-0000-000000000000"
52
+ "encounter_id": "encounter-example-001",
53
+ "filename": "test-scan.jpg",
54
+ "gtin": "01234567890123",
55
+ "test_id": "00000000-0000-4000-8000-000000000001"
56
56
  }
57
57
  ```
58
58
 
@@ -79,7 +79,7 @@ Request model: [`GetScanUploadUrlRequest`](../models/GetScanUploadUrlRequest.md)
79
79
 
80
80
  | Status | Shape | Content type | Description |
81
81
  |---|---|---|---|
82
- | `400` | [`diagnostics.ErrorResponse`](../models/diagnostics.ErrorResponse.md) | application/json | test_id was missing or not a valid UUID |
82
+ | `400` | [`diagnostics.ErrorResponse`](../models/diagnostics.ErrorResponse.md) | application/json | test_id was missing or not a valid UUID, or gtin was missing or not a valid GTIN |
83
83
  | `401` | [`diagnostics.ErrorResponse`](../models/diagnostics.ErrorResponse.md) | application/json | Authorization required — missing or invalid Bearer JWT |
84
84
  | `403` | [`diagnostics.ErrorResponse`](../models/diagnostics.ErrorResponse.md) | application/json | A PATIENT-pool caller attempted to access another patient's data |
85
85
  | `404` | [`diagnostics.ErrorResponse`](../models/diagnostics.ErrorResponse.md) | application/json | The PATIENT-pool caller's own FHIR Patient record could not be resolved |
@@ -87,6 +87,14 @@ Request model: [`GetScanUploadUrlRequest`](../models/GetScanUploadUrlRequest.md)
87
87
 
88
88
  ## Error examples
89
89
 
90
+ ### 400 — gtin is not 8, 12, 13, or 14 digits
91
+
92
+ ```json
93
+ {
94
+ "error": "GTIN must contain 8, 12, 13, or 14 digits"
95
+ }
96
+ ```
97
+
90
98
  ### 400 — test_id is missing or not a valid UUID
91
99
 
92
100
  ```json
@@ -95,6 +103,14 @@ Request model: [`GetScanUploadUrlRequest`](../models/GetScanUploadUrlRequest.md)
95
103
  }
96
104
  ```
97
105
 
106
+ ### 400 — gtin is missing from the request body
107
+
108
+ ```json
109
+ {
110
+ "error": "gtin is required"
111
+ }
112
+ ```
113
+
98
114
  ### 401 — Missing or invalid access token
99
115
 
100
116
  ```json
@@ -138,10 +154,10 @@ const patientId = "<PATIENT_ID>";
138
154
 
139
155
  const request = {
140
156
  "content_type": "image/jpeg",
141
- "encounter_id": "string",
142
- "filename": "scan.jpg",
143
- "gtin": "string",
144
- "test_id": "00000000-0000-0000-0000-000000000000"
157
+ "encounter_id": "encounter-example-001",
158
+ "filename": "test-scan.jpg",
159
+ "gtin": "01234567890123",
160
+ "test_id": "00000000-0000-4000-8000-000000000001"
145
161
  };
146
162
 
147
163
  const result = await diagnostics.getScanUploadUrl(patientId, request);
@@ -153,7 +169,7 @@ const result = await diagnostics.getScanUploadUrl(patientId, request);
153
169
  curl -X POST \
154
170
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
155
171
  -H 'Content-Type: application/json' \
156
- -d '{"content_type":"image/jpeg","encounter_id":"string","filename":"scan.jpg","gtin":"string","test_id":"00000000-0000-0000-0000-000000000000"}' \
172
+ -d '{"content_type":"image/jpeg","encounter_id":"encounter-example-001","filename":"test-scan.jpg","gtin":"01234567890123","test_id":"00000000-0000-4000-8000-000000000001"}' \
157
173
  'https://dev-api-diagnostics.health.cloud/patients/%3CPATIENT_ID%3E/diagnostics/scan-upload-url'
158
174
  ```
159
175
 
@@ -0,0 +1,148 @@
1
+ # Get one appointment with patient demographics
2
+
3
+ Operation ID: `provider.getAppointment`
4
+
5
+ Get one appointment scoped to the authenticated provider's tenant, including a demographic summary of the appointment's patient under the 'patient' key. Athena-authoritative tenants resolve the native appointment and reverse-map its patient through the tenant's FHIR identifiers, mirroring the list flow; FHIR-only tenants read the appointment directly from their FHIR store.
6
+
7
+ ## Public method
8
+
9
+ `getAppointment`
10
+
11
+ Signature: `provider.getAppointment(appointmentId)`
12
+
13
+ Return type: `Promise<ProviderAppointmentResponse>`
14
+
15
+ ## Authentication
16
+
17
+ Classification: **AUTHENTICATED**
18
+
19
+ Schemes: `bearerAuth`
20
+
21
+ ## Prerequisites
22
+
23
+ None documented.
24
+
25
+ ## HTTP
26
+
27
+ `GET /appointments/{appointment_id}`
28
+
29
+ ## Path parameters
30
+
31
+ | Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
32
+ |---|---|---:|---|---|---|---:|---|
33
+ | `appointment_id` | `string` | Yes | | | | No | |
34
+
35
+ ## Query parameters
36
+
37
+ None.
38
+
39
+ ## Body parameters
40
+
41
+ None.
42
+
43
+ Request model: None.
44
+
45
+ ## Request example
46
+
47
+ None declared in canonical OpenAPI.
48
+
49
+ ## Success responses
50
+
51
+ | Status | Shape | Content type | Description |
52
+ |---|---|---|---|
53
+ | `200` | [`ProviderAppointmentResponse`](../models/ProviderAppointmentResponse.md) | application/json | Appointment with patient demographics |
54
+
55
+ ## Success response examples
56
+
57
+ ### 200
58
+
59
+ ```json
60
+ {
61
+ "appointment": {
62
+ "appointment_id": "string",
63
+ "end": "string",
64
+ "patient": {
65
+ "address": {
66
+ "city": "string",
67
+ "country": "string",
68
+ "state": "string",
69
+ "street1": "string",
70
+ "street2": "string",
71
+ "zip_code": "string"
72
+ },
73
+ "date_of_birth": "string",
74
+ "first_name": "string",
75
+ "gender": "string",
76
+ "last_name": "string",
77
+ "patient_id": "string",
78
+ "phone": {
79
+ "extension": "string",
80
+ "number": "string",
81
+ "type": "string"
82
+ }
83
+ },
84
+ "patient_id": "string",
85
+ "provider_id": "string",
86
+ "start": "string",
87
+ "status": "scheduled",
88
+ "telehealth_link": "string"
89
+ }
90
+ }
91
+ ```
92
+
93
+ ## Common errors
94
+
95
+ | Status | Shape | Content type | Description |
96
+ |---|---|---|---|
97
+ | `401` | [`provider.ErrorResponse`](../models/provider.ErrorResponse.md) | application/json | Provider Bearer authentication is required |
98
+ | `404` | [`provider.ErrorResponse`](../models/provider.ErrorResponse.md) | application/json | No appointment exists for the id in the caller's tenant |
99
+
100
+ ## Error examples
101
+
102
+ ### 401 — No provider JWT
103
+
104
+ ```json
105
+ {
106
+ "error": "Provider authorization required"
107
+ }
108
+ ```
109
+
110
+ ### 404 — Unknown appointment
111
+
112
+ ```json
113
+ {
114
+ "error": "Appointment not found in this tenant"
115
+ }
116
+ ```
117
+
118
+ ## NodeJS / TypeScript implementation
119
+
120
+ ```ts
121
+ import { HCSDK } from "@healthcloudai/hc-sdk";
122
+ ```
123
+
124
+ ```ts
125
+ const appointmentId = "<APPOINTMENT_ID>";
126
+
127
+ const result = await provider.getAppointment(appointmentId);
128
+ ```
129
+
130
+ ## cURL
131
+
132
+ ```bash
133
+ curl -X GET \
134
+ -H 'Authorization: Bearer <ACCESS_TOKEN>' \
135
+ 'https://dev-api-provider.health.cloud/appointments/%3CAPPOINTMENT_ID%3E'
136
+ ```
137
+
138
+ ## Notes
139
+
140
+ None.
141
+
142
+ ## Prepared Test Console scenario
143
+
144
+ No canonical scenario is currently associated.
145
+
146
+ ## Real response
147
+
148
+ No approved real integration response is currently published. Unapproved candidates are never rendered as examples.
@@ -0,0 +1,120 @@
1
+ # Get one encounter with patient demographics
2
+
3
+ Operation ID: `provider.getEncounter`
4
+
5
+ Get one encounter scoped to the authenticated provider's tenant, including a demographic summary (first/last name, gender, date of birth, primary address, primary phone) of the encounter's patient under the 'patient' key. A summary is omitted (not an error) when the patient record cannot be read.
6
+
7
+ ## Public method
8
+
9
+ `getEncounter`
10
+
11
+ Signature: `provider.getEncounter(encounterId)`
12
+
13
+ Return type: `Promise<ProviderEncounterResponse>`
14
+
15
+ ## Authentication
16
+
17
+ Classification: **AUTHENTICATED**
18
+
19
+ Schemes: `bearerAuth`
20
+
21
+ ## Prerequisites
22
+
23
+ None documented.
24
+
25
+ ## HTTP
26
+
27
+ `GET /encounters/{encounter_id}`
28
+
29
+ ## Path parameters
30
+
31
+ | Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
32
+ |---|---|---:|---|---|---|---:|---|
33
+ | `encounter_id` | `string` | Yes | | | | No | |
34
+
35
+ ## Query parameters
36
+
37
+ None.
38
+
39
+ ## Body parameters
40
+
41
+ None.
42
+
43
+ Request model: None.
44
+
45
+ ## Request example
46
+
47
+ None declared in canonical OpenAPI.
48
+
49
+ ## Success responses
50
+
51
+ | Status | Shape | Content type | Description |
52
+ |---|---|---|---|
53
+ | `200` | [`ProviderEncounterResponse`](../models/ProviderEncounterResponse.md) | application/json | Encounter with patient demographics |
54
+
55
+ ## Success response examples
56
+
57
+ ### 200
58
+
59
+ ```json
60
+ {
61
+ "encounter": {}
62
+ }
63
+ ```
64
+
65
+ ## Common errors
66
+
67
+ | Status | Shape | Content type | Description |
68
+ |---|---|---|---|
69
+ | `401` | [`provider.ErrorResponse`](../models/provider.ErrorResponse.md) | application/json | Provider Bearer authentication is required |
70
+ | `404` | [`provider.ErrorResponse`](../models/provider.ErrorResponse.md) | application/json | No encounter exists for the id in the caller's tenant |
71
+
72
+ ## Error examples
73
+
74
+ ### 401 — No provider JWT
75
+
76
+ ```json
77
+ {
78
+ "error": "Provider authorization required"
79
+ }
80
+ ```
81
+
82
+ ### 404 — Unknown encounter
83
+
84
+ ```json
85
+ {
86
+ "error": "Encounter not found in this tenant"
87
+ }
88
+ ```
89
+
90
+ ## NodeJS / TypeScript implementation
91
+
92
+ ```ts
93
+ import { HCSDK } from "@healthcloudai/hc-sdk";
94
+ ```
95
+
96
+ ```ts
97
+ const encounterId = "<ENCOUNTER_ID>";
98
+
99
+ const result = await provider.getEncounter(encounterId);
100
+ ```
101
+
102
+ ## cURL
103
+
104
+ ```bash
105
+ curl -X GET \
106
+ -H 'Authorization: Bearer <ACCESS_TOKEN>' \
107
+ 'https://dev-api-provider.health.cloud/encounters/%3CENCOUNTER_ID%3E'
108
+ ```
109
+
110
+ ## Notes
111
+
112
+ None.
113
+
114
+ ## Prepared Test Console scenario
115
+
116
+ No canonical scenario is currently associated.
117
+
118
+ ## Real response
119
+
120
+ No approved real integration response is currently published. Unapproved candidates are never rendered as examples.
@@ -0,0 +1,122 @@
1
+ # Get a patient's consolidated health record (provider tenant scope)
2
+
3
+ Operation ID: `provider.getPatientRecord`
4
+
5
+ Get a patient's consolidated health record scoped to the authenticated provider's tenant: allergies, conditions, medications, procedures, immunizations, family history, advance directives, observations, encounters, vitals, questionnaire responses, diagnostics, and intake submissions. Tenant isolation is enforced by the tenant-scoped FHIR store — a patient that does not exist in the provider's own tenant resolves to 404 before any clinical data is read. Section keys and serialized shapes mirror the patient-facing EHR health-record route.
6
+
7
+ ## Public method
8
+
9
+ `getPatientRecord`
10
+
11
+ Signature: `provider.getPatientRecord(patientId)`
12
+
13
+ Return type: `Promise<ProviderPatientRecordResponse>`
14
+
15
+ ## Authentication
16
+
17
+ Classification: **AUTHENTICATED**
18
+
19
+ Schemes: `bearerAuth`
20
+
21
+ ## Prerequisites
22
+
23
+ None documented.
24
+
25
+ ## HTTP
26
+
27
+ `GET /patients/{patient_id}/record`
28
+
29
+ ## Path parameters
30
+
31
+ | Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
32
+ |---|---|---:|---|---|---|---:|---|
33
+ | `patient_id` | `string` | Yes | | | | No | |
34
+
35
+ ## Query parameters
36
+
37
+ None.
38
+
39
+ ## Body parameters
40
+
41
+ None.
42
+
43
+ Request model: None.
44
+
45
+ ## Request example
46
+
47
+ None declared in canonical OpenAPI.
48
+
49
+ ## Success responses
50
+
51
+ | Status | Shape | Content type | Description |
52
+ |---|---|---|---|
53
+ | `200` | [`ProviderPatientRecordResponse`](../models/ProviderPatientRecordResponse.md) | application/json | Consolidated patient health record |
54
+
55
+ ## Success response examples
56
+
57
+ ### 200
58
+
59
+ ```json
60
+ {
61
+ "patient_id": "string",
62
+ "resources": {},
63
+ "totals": {}
64
+ }
65
+ ```
66
+
67
+ ## Common errors
68
+
69
+ | Status | Shape | Content type | Description |
70
+ |---|---|---|---|
71
+ | `401` | [`provider.ErrorResponse`](../models/provider.ErrorResponse.md) | application/json | Provider Bearer authentication is required |
72
+ | `404` | [`provider.ErrorResponse`](../models/provider.ErrorResponse.md) | application/json | Patient not found in this tenant |
73
+
74
+ ## Error examples
75
+
76
+ ### 401 — No provider JWT
77
+
78
+ ```json
79
+ {
80
+ "error": "Provider authorization required"
81
+ }
82
+ ```
83
+
84
+ ### 404 — Unknown patient
85
+
86
+ ```json
87
+ {
88
+ "error": "Patient not found in this tenant"
89
+ }
90
+ ```
91
+
92
+ ## NodeJS / TypeScript implementation
93
+
94
+ ```ts
95
+ import { HCSDK } from "@healthcloudai/hc-sdk";
96
+ ```
97
+
98
+ ```ts
99
+ const patientId = "<PATIENT_ID>";
100
+
101
+ const result = await provider.getPatientRecord(patientId);
102
+ ```
103
+
104
+ ## cURL
105
+
106
+ ```bash
107
+ curl -X GET \
108
+ -H 'Authorization: Bearer <ACCESS_TOKEN>' \
109
+ 'https://dev-api-provider.health.cloud/patients/%3CPATIENT_ID%3E/record'
110
+ ```
111
+
112
+ ## Notes
113
+
114
+ None.
115
+
116
+ ## Prepared Test Console scenario
117
+
118
+ No canonical scenario is currently associated.
119
+
120
+ ## Real response
121
+
122
+ No approved real integration response is currently published. Unapproved candidates are never rendered as examples.
@@ -0,0 +1,176 @@
1
+ # List tenant appointments
2
+
3
+ Operation ID: `provider.listAppointments`
4
+
5
+ List appointments scoped to the authenticated provider's tenant. The date window defaults to today through today + 30 days; start_date pins the window start (end_date defaults to start_date + 30 days), end_date pins the window end (start_date defaults to today), and the legacy date parameter pins exactly one calendar day. The window is capped at 90 days and the result count at limit=100 (max 200). Both backends apply the identical window: a single _include=Appointment:patient search for FHIR tenants, one Athena list plus one batched patient-identifier search for Athena tenants — every returned item carries a patient demographic summary with zero per-patient reads. Use visit_type=telehealth to filter by the tenant's configured telehealth appointment type.
6
+
7
+ ## Public method
8
+
9
+ `listAppointments`
10
+
11
+ Signature: `provider.listAppointments(filters)`
12
+
13
+ Return type: `Promise<ProviderAppointmentsResponse>`
14
+
15
+ ## Authentication
16
+
17
+ Classification: **AUTHENTICATED**
18
+
19
+ Schemes: `bearerAuth`
20
+
21
+ ## Prerequisites
22
+
23
+ None documented.
24
+
25
+ ## HTTP
26
+
27
+ `GET /appointments`
28
+
29
+ ## Path parameters
30
+
31
+ None.
32
+
33
+ ## Query parameters
34
+
35
+ | Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
36
+ |---|---|---:|---|---|---|---:|---|
37
+ | `date` | `string|null` | No | | | | Yes | Optional calendar date in YYYY-MM-DD format; equivalent to start_date=end_date=<date> (legacy parameter) |
38
+ | `end_date` | `string|null` | No | | | | Yes | Optional window end in YYYY-MM-DD format. Defaults to start_date + 30 days (or today + 30 days when start_date is also omitted) |
39
+ | `limit` | `string|null` | No | | | | Yes | Maximum appointments to return; default 100, maximum 200 |
40
+ | `patient_id` | `string|null` | No | | | | Yes | Optional FHIR Patient resource ID to restrict the list |
41
+ | `practitioner_id` | `string|null` | No | | | | Yes | Optional FHIR Practitioner resource ID to restrict the list |
42
+ | `start_date` | `string|null` | No | | | | Yes | Optional window start in YYYY-MM-DD format. Defaults to today |
43
+ | `status` | `string|null` | No | | | | Yes | Optional FHIR Appointment status |
44
+ | `visit_type` | `string|null` | No | | | | Yes | Optional visit type; only telehealth is currently supported |
45
+
46
+ ## Body parameters
47
+
48
+ None.
49
+
50
+ Request model: None.
51
+
52
+ ## Request example
53
+
54
+ None declared in canonical OpenAPI.
55
+
56
+ ## Success responses
57
+
58
+ | Status | Shape | Content type | Description |
59
+ |---|---|---|---|
60
+ | `200` | [`ProviderAppointmentsResponse`](../models/ProviderAppointmentsResponse.md) | application/json | Appointments |
61
+
62
+ ## Success response examples
63
+
64
+ ### 200
65
+
66
+ ```json
67
+ {
68
+ "appointments": [
69
+ {
70
+ "appointment_id": "string",
71
+ "end": "string",
72
+ "patient": {
73
+ "address": {
74
+ "city": "string",
75
+ "country": "string",
76
+ "state": "string",
77
+ "street1": "string",
78
+ "street2": "string",
79
+ "zip_code": "string"
80
+ },
81
+ "date_of_birth": "string",
82
+ "first_name": "string",
83
+ "gender": "string",
84
+ "last_name": "string",
85
+ "patient_id": "string",
86
+ "phone": {
87
+ "extension": "string",
88
+ "number": "string",
89
+ "type": "string"
90
+ }
91
+ },
92
+ "patient_id": "string",
93
+ "provider_id": "string",
94
+ "start": "string",
95
+ "status": "scheduled",
96
+ "telehealth_link": "string"
97
+ }
98
+ ],
99
+ "total": 0
100
+ }
101
+ ```
102
+
103
+ ## Common errors
104
+
105
+ | Status | Shape | Content type | Description |
106
+ |---|---|---|---|
107
+ | `400` | [`provider.ErrorResponse`](../models/provider.ErrorResponse.md) | application/json | date is present but not YYYY-MM-DD, status is invalid, or visit_type is unsupported |
108
+ | `401` | [`provider.ErrorResponse`](../models/provider.ErrorResponse.md) | application/json | Provider Bearer authentication is required |
109
+ | `409` | [`provider.ErrorResponse`](../models/provider.ErrorResponse.md) | application/json | Athena telehealth filtering was requested but the tenant has no configured telehealth appointment type |
110
+ | `502` | [`provider.ErrorResponse`](../models/provider.ErrorResponse.md) | application/json | Athena appointment retrieval failed |
111
+
112
+ ## Error examples
113
+
114
+ ### 400 — Unsupported visit type
115
+
116
+ ```json
117
+ {
118
+ "error": "visit_type must be telehealth"
119
+ }
120
+ ```
121
+
122
+ ### 401 — No provider JWT
123
+
124
+ ```json
125
+ {
126
+ "error": "Provider authorization required"
127
+ }
128
+ ```
129
+
130
+ ### 409 — Athena telehealth type missing
131
+
132
+ ```json
133
+ {
134
+ "error": "Athena telehealth_appointment_type_id is not configured for this tenant"
135
+ }
136
+ ```
137
+
138
+ ### 502 — Athena appointment read failed
139
+
140
+ ```json
141
+ {
142
+ "error": "Could not load appointments from Athena: upstream unavailable"
143
+ }
144
+ ```
145
+
146
+ ## NodeJS / TypeScript implementation
147
+
148
+ ```ts
149
+ import { HCSDK } from "@healthcloudai/hc-sdk";
150
+ ```
151
+
152
+ ```ts
153
+ const filters = "<FILTERS>";
154
+
155
+ const result = await provider.listAppointments(filters);
156
+ ```
157
+
158
+ ## cURL
159
+
160
+ ```bash
161
+ curl -X GET \
162
+ -H 'Authorization: Bearer <ACCESS_TOKEN>' \
163
+ 'https://dev-api-provider.health.cloud/appointments?date=%3CDATE%3E&end_date=2026-08-15T09%3A00%3A00Z&limit=%3CLIMIT%3E&patient_id=%3CPATIENT_ID%3E&practitioner_id=%3CPRACTITIONER_ID%3E&start_date=2026-08-15T09%3A00%3A00Z&status=%3CSTATUS%3E&visit_type=%3CVISIT_TYPE%3E'
164
+ ```
165
+
166
+ ## Notes
167
+
168
+ None.
169
+
170
+ ## Prepared Test Console scenario
171
+
172
+ No canonical scenario is currently associated.
173
+
174
+ ## Real response
175
+
176
+ No approved real integration response is currently published. Unapproved candidates are never rendered as examples.