{ "components": { "schemas": { "AdapterErrorResponse": { "additionalProperties": false, "examples": [ { "error_code": "permission_denied", "message": "Actor cannot access this context.", "retryable": false } ], "properties": { "error_code": { "description": "Stable machine-readable error code. Use letters, numbers, '.', '_', ':', or '-'.", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+$", "title": "Error Code", "type": "string" }, "message": { "maxLength": 512, "minLength": 1, "pattern": "^[^\\x00-\\x1f\\x7f]+$", "title": "Message", "type": "string" }, "retryable": { "title": "Retryable", "type": "boolean" }, "validation_details": { "anyOf": [ { "maxProperties": 8, "patternProperties": { "^[^\\x00-\\x1f\\x7f]+$": { "maxLength": 256, "minLength": 1, "pattern": "^[^\\x00-\\x1f\\x7f]+$", "type": "string" } }, "propertyNames": { "maxLength": 64, "minLength": 1, "pattern": "^[^\\x00-\\x1f\\x7f]+$" }, "type": "object" }, { "type": "null" } ], "description": "Optional safe field-level details. Use at most 8 entries; keys are 64 characters or fewer, values are 256 characters or fewer.", "title": "Validation Details" } }, "required": [ "error_code", "message", "retryable" ], "title": "AdapterErrorResponse", "type": "object" }, "AppointmentParticipant": { "additionalProperties": false, "properties": { "actor_type": { "const": "provider", "examples": [ "provider" ], "title": "Actor Type", "type": "string" }, "provider": { "$ref": "#/components/schemas/ProviderActor" }, "role": { "const": "scheduled_provider", "examples": [ "scheduled_provider" ], "title": "Role", "type": "string" } }, "required": [ "actor_type", "role", "provider" ], "title": "AppointmentParticipant", "type": "object" }, "ChecklistRecommendationBlock": { "additionalProperties": false, "properties": { "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "provenance": { "anyOf": [ { "$ref": "#/components/schemas/ChecklistRecommendationProvenance" }, { "type": "null" } ] }, "source_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Source Metadata" }, "tasks": { "items": { "$ref": "#/components/schemas/ChecklistRecommendationTask" }, "maxItems": 25, "minItems": 1, "title": "Tasks", "type": "array" }, "title": { "maxLength": 200, "minLength": 1, "title": "Title", "type": "string" }, "type": { "enum": [ "task_group", "workflow" ], "examples": [ "workflow" ], "title": "Type", "type": "string" } }, "required": [ "type", "title", "tasks" ], "title": "ChecklistRecommendationBlock", "type": "object" }, "ChecklistRecommendationItem": { "additionalProperties": false, "properties": { "recommendation_set": { "$ref": "#/components/schemas/ChecklistRecommendationSet" }, "type": { "const": "recommendation_set", "examples": [ "recommendation_set" ], "title": "Type", "type": "string" } }, "required": [ "type", "recommendation_set" ], "title": "ChecklistRecommendationItem", "type": "object" }, "ChecklistRecommendationProvenance": { "additionalProperties": false, "properties": { "captured_at": { "examples": [ "2026-06-30T13:00:00Z" ], "format": "date-time", "title": "Captured At", "type": "string" }, "source_data": { "anyOf": [ { "$ref": "#/components/schemas/ChecklistRecommendationSourceData" }, { "type": "null" } ] }, "source_id": { "description": "Upstream source identifier when this recommendation item corresponds to a stable upstream source object.", "examples": [ "gap-123" ], "maxLength": 500, "minLength": 1, "title": "Source Id", "type": "string" }, "source_system": { "enum": [ "CHARTHERO_USPSTF", "CHARTHERO_HEDIS", "CHARTHERO_AWV", "CHARTHERO_TEMPLATE", "ARCADIA", "EPIC", "CERNER", "ATHENA", "OTHER" ], "examples": [ "OTHER" ], "title": "Source System", "type": "string" }, "source_type": { "enum": [ "USPSTF_RECOMMENDATION", "HEDIS_MEASURE", "CMS_AWV", "CARE_GAP", "EHR_ALERT", "MANUAL_ENTRY", "AI_DETECTED", "WORKFLOW_TEMPLATE" ], "examples": [ "CARE_GAP" ], "title": "Source Type", "type": "string" }, "type": { "const": "STANDARD", "default": "STANDARD", "examples": [ "STANDARD" ], "title": "Type", "type": "string" } }, "required": [ "source_id", "source_system", "source_type", "captured_at" ], "title": "ChecklistRecommendationProvenance", "type": "object" }, "ChecklistRecommendationSet": { "additionalProperties": false, "properties": { "blocks": { "items": { "$ref": "#/components/schemas/ChecklistRecommendationBlock" }, "maxItems": 10, "minItems": 1, "title": "Blocks", "type": "array" }, "generated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "examples": [ "2026-06-30T14:00:00Z" ], "title": "Generated At" }, "provenance": { "anyOf": [ { "$ref": "#/components/schemas/ChecklistRecommendationProvenance" }, { "type": "null" } ] }, "source_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Source Metadata" }, "title": { "maxLength": 200, "minLength": 1, "title": "Title", "type": "string" } }, "required": [ "title", "blocks" ], "title": "ChecklistRecommendationSet", "type": "object" }, "ChecklistRecommendationSourceData": { "additionalProperties": false, "properties": { "format": { "enum": [ "json", "text" ], "examples": [ "json" ], "title": "Format", "type": "string" }, "payload": { "description": "Small source payload or display text from the upstream system. Do not include secrets or unrelated clinical records.", "title": "Payload" } }, "required": [ "format", "payload" ], "title": "ChecklistRecommendationSourceData", "type": "object" }, "ChecklistRecommendationSubtask": { "additionalProperties": false, "properties": { "kind": { "default": "task", "enum": [ "task", "check" ], "examples": [ "check" ], "title": "Kind", "type": "string" }, "note": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Note" }, "priority": { "anyOf": [ { "enum": [ "URGENT", "HIGH", "MEDIUM", "LOW" ], "type": "string" }, { "type": "null" } ], "title": "Priority" }, "provenance": { "anyOf": [ { "$ref": "#/components/schemas/ChecklistRecommendationProvenance" }, { "type": "null" } ] }, "rationale": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Rationale" }, "requires_action": { "default": false, "title": "Requires Action", "type": "boolean" }, "source_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Source Metadata" }, "task_type": { "anyOf": [ { "enum": [ "CARE_GAP", "PREVENTIVE", "CHRONIC", "ACUTE", "DIAGNOSTIC", "MEDICATION", "REFERRAL", "COUNSELING", "ADMINISTRATIVE", "OTHER" ], "type": "string" }, { "type": "null" } ], "title": "Task Type" }, "title": { "maxLength": 200, "minLength": 1, "title": "Title", "type": "string" } }, "required": [ "title" ], "title": "ChecklistRecommendationSubtask", "type": "object" }, "ChecklistRecommendationTask": { "additionalProperties": false, "properties": { "category": { "anyOf": [ { "enum": [ "AWV", "HEDIS", "RAF_HCC", "CHRONIC_CONDITIONS", "PREVENTIVE", "ACUTE", "CARE_COORDINATION", "ADMINISTRATIVE" ], "type": "string" }, { "type": "null" } ], "title": "Category" }, "kind": { "default": "task", "enum": [ "task", "check" ], "examples": [ "task" ], "title": "Kind", "type": "string" }, "note": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Note" }, "priority": { "anyOf": [ { "enum": [ "URGENT", "HIGH", "MEDIUM", "LOW" ], "type": "string" }, { "type": "null" } ], "title": "Priority" }, "provenance": { "anyOf": [ { "$ref": "#/components/schemas/ChecklistRecommendationProvenance" }, { "type": "null" } ] }, "rationale": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Rationale" }, "requires_action": { "default": false, "title": "Requires Action", "type": "boolean" }, "source_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Source Metadata" }, "subtasks": { "items": { "$ref": "#/components/schemas/ChecklistRecommendationSubtask" }, "maxItems": 10, "title": "Subtasks", "type": "array" }, "task_type": { "anyOf": [ { "enum": [ "CARE_GAP", "PREVENTIVE", "CHRONIC", "ACUTE", "DIAGNOSTIC", "MEDICATION", "REFERRAL", "COUNSELING", "ADMINISTRATIVE", "OTHER" ], "type": "string" }, { "type": "null" } ], "title": "Task Type" }, "title": { "maxLength": 200, "minLength": 1, "title": "Title", "type": "string" } }, "required": [ "title" ], "title": "ChecklistRecommendationTask", "type": "object" }, "ChecklistRecommendationsEncounter": { "additionalProperties": false, "description": "ChartHero encounter subject for the recommendation request. `id` is the ChartHero internal encounter identifier; `external_ids` contains known partner identifiers for the same encounter.", "properties": { "external_ids": { "description": "Known external identifiers for the appointment or encounter.", "items": { "$ref": "#/components/schemas/EncounterExternalIdentifier" }, "title": "External Ids", "type": "array" }, "id": { "description": "ChartHero internal encounter identifier.", "examples": [ "encounter-1" ], "maxLength": 128, "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "ChecklistRecommendationsEncounter", "type": "object" }, "ChecklistRecommendationsPatient": { "additionalProperties": false, "description": "ChartHero patient subject for the recommendation request. `id` is the ChartHero internal patient identifier; `external_ids` contains known partner identifiers for the same patient.", "properties": { "external_ids": { "description": "Known external identifiers for the patient.", "items": { "$ref": "#/components/schemas/PatientExternalIdentifier" }, "title": "External Ids", "type": "array" }, "id": { "description": "ChartHero internal patient identifier.", "examples": [ "22222222-2222-4222-8222-222222222222" ], "maxLength": 128, "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "ChecklistRecommendationsPatient", "type": "object" }, "ChecklistRecommendationsRequest": { "additionalProperties": false, "examples": [ { "actor": { "active": true, "actor_id": "11111111-1111-4111-8111-111111111111", "actor_type": "user", "display_name": "Dr. Chris Smith", "email": "clinician@example.com", "external_ids": [ { "source": "provider_acme_care_prod", "type": "provider_id", "value": "prov-456" } ] }, "encounter": { "external_ids": [ { "source": "acme_care_prod", "type": "encounter_id", "value": "encounter-1" } ], "id": "encounter-1" }, "patient": { "external_ids": [ { "source": "acme_care_prod", "type": "patient_id", "value": "pat-123" } ], "id": "22222222-2222-4222-8222-222222222222" } } ], "properties": { "actor": { "$ref": "#/components/schemas/ProviderIdentifierSubject", "description": "Authenticated ChartHero actor. Uses the same actor shape as launch context and appointment-search adapter calls." }, "encounter": { "$ref": "#/components/schemas/ChecklistRecommendationsEncounter" }, "patient": { "$ref": "#/components/schemas/ChecklistRecommendationsPatient" } }, "required": [ "patient", "encounter", "actor" ], "title": "ChecklistRecommendationsRequest", "type": "object" }, "ChecklistRecommendationsResponse": { "additionalProperties": false, "examples": [ { "items": [ { "recommendation_set": { "blocks": [ { "description": "Review open diabetes care gaps.", "tasks": [ { "category": "HEDIS", "priority": "HIGH", "provenance": { "captured_at": "2026-06-30T13:00:00Z", "source_id": "gap-123", "source_system": "OTHER", "source_type": "CARE_GAP" }, "requires_action": true, "subtasks": [ { "kind": "check", "title": "Order A1c if clinically appropriate" } ], "title": "Address A1c gap" } ], "title": "Diabetes Review", "type": "workflow" }, { "tasks": [ { "title": "Discuss eye exam" } ], "title": "Loose Recommendations", "type": "task_group" } ], "generated_at": "2026-06-30T14:00:00Z", "title": "ACO Pre-Visit Plan" }, "type": "recommendation_set" } ] } ], "properties": { "items": { "items": { "$ref": "#/components/schemas/ChecklistRecommendationItem" }, "maxItems": 10, "title": "Items", "type": "array" } }, "required": [ "items" ], "title": "ChecklistRecommendationsResponse", "type": "object" }, "CompactJweProtectedHeader": { "additionalProperties": false, "properties": { "alg": { "const": "dir", "examples": [ "dir" ], "title": "Alg", "type": "string" }, "enc": { "const": "A256GCM", "examples": [ "A256GCM" ], "title": "Enc", "type": "string" }, "kid": { "examples": [ "launch-key-2026-06" ], "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+$", "title": "Kid", "type": "string" }, "typ": { "const": "charthero-org-integration-launch+jwe", "examples": [ "charthero-org-integration-launch+jwe" ], "title": "Typ", "type": "string" } }, "required": [ "alg", "enc", "kid", "typ" ], "title": "CompactJweProtectedHeader", "type": "object" }, "EncounterExternalIdentifier": { "additionalProperties": false, "examples": [ { "source": "acme_care_prod", "type": "appointment_id", "value": "apt-789" } ], "properties": { "source": { "description": "Organization-level external identifier source alias. Send this even when the adapter has one default source.", "examples": [ "default" ], "maxLength": 64, "minLength": 1, "pattern": "^[a-z][a-z0-9_]{0,63}$", "title": "Source", "type": "string" }, "type": { "description": "Identifier kind, such as `patient_id` or `appointment_id`; this is not the patient or encounter object itself.", "examples": [ "patient_id" ], "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]{1,64}$", "title": "Type", "type": "string" }, "value": { "description": "Stable non-ChartHero identifier value.", "examples": [ "pat-123" ], "maxLength": 256, "minLength": 1, "pattern": "^[^\\x00-\\x1f\\x7f]*[^\\s\\x00-\\x1f\\x7f][^\\x00-\\x1f\\x7f]*$", "title": "Value", "type": "string" } }, "required": [ "source", "type", "value" ], "title": "EncounterExternalIdentifier", "type": "object" }, "EncounterPreview": { "additionalProperties": false, "properties": { "end_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Timezone-aware appointment end time. When present, it must not be before start_at.", "title": "End At" }, "external_ids": { "description": "Stable identifiers for one upstream encounter. Each source/type tuple may appear at most once for that subject.", "items": { "$ref": "#/components/schemas/EncounterExternalIdentifier" }, "maxItems": 1, "minItems": 1, "title": "External Ids", "type": "array" }, "participants": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AppointmentParticipant" }, "type": "array" }, { "type": "null" } ], "title": "Participants" }, "patient": { "$ref": "#/components/schemas/Patient" }, "start_at": { "description": "Timezone-aware appointment start time. Use an explicit offset or Z.", "format": "date-time", "title": "Start At", "type": "string" } }, "required": [ "external_ids", "patient", "start_at" ], "title": "EncounterPreview", "type": "object" }, "EncryptedLaunchPayload": { "additionalProperties": false, "properties": { "actor": { "$ref": "#/components/schemas/EncryptedLaunchProviderIdentifierSubject", "description": "Optional top-level actor evidence for the ChartHero user expected to resolve the launch." }, "aud": { "const": "charthero", "examples": [ "charthero" ], "title": "Aud", "type": "string" }, "exp": { "description": "Expiration time as a NumericDate. It must be after iat and no more than five minutes after iat.", "minimum": 0, "title": "Exp", "type": "integer" }, "iat": { "description": "Issued-at time as a NumericDate.", "minimum": 0, "title": "Iat", "type": "integer" }, "iss": { "maxLength": 256, "minLength": 1, "pattern": "^[^\\x00-\\x1f\\x7f]+$", "title": "Iss", "type": "string" }, "jti": { "description": "Unique replay-protected launch identifier.", "maxLength": 128, "minLength": 16, "pattern": "^[A-Za-z0-9._:-]{16,128}$", "title": "Jti", "type": "string" }, "launch_state": { "additionalProperties": true, "description": "Required adapter-owned JSON object. Use small opaque workflow handles or correlation ids; do not include raw PHI, secrets, clinical content, documents, transcripts, or setup defaults.", "examples": [ { "correlation_id": "launch-abc", "workflow_id": "schedule-row-123" } ], "title": "Launch State", "type": "object" } }, "required": [ "iss", "aud", "iat", "exp", "jti", "launch_state" ], "title": "EncryptedLaunchPayload", "type": "object" }, "EncryptedLaunchProviderIdentifierSubject": { "additionalProperties": false, "anyOf": [ { "properties": { "actor_id": { "format": "uuid", "type": "string" } }, "required": [ "actor_id" ] }, { "properties": { "email": { "maxLength": 320, "minLength": 1, "pattern": "^[^\\x00-\\x1F\\x7F]*@[^\\x00-\\x1F\\x7F]*$", "type": "string" } }, "required": [ "email" ] }, { "properties": { "external_ids": { "minItems": 1, "type": "array" } }, "required": [ "external_ids" ] } ], "description": "Optional launch-access evidence for the ChartHero user expected to resolve the launch link. Provide `actor_id` when your system stores the ChartHero public user id, `email` when your system knows the verified ChartHero user email, and `external_ids` when provider linking is enabled and your system has durable provider/user identifiers. If multiple criteria are present, every provided criterion must match; direct actor fields do not override conflicting external IDs.", "properties": { "actor_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "ChartHero public actor identifier for the user expected to resolve this launch link. When supplied, it must match the authenticated ChartHero user's public actor id.", "examples": [ "11111111-1111-4111-8111-111111111111" ], "title": "Actor Id" }, "email": { "anyOf": [ { "maxLength": 320, "minLength": 1, "pattern": "^[^\\x00-\\x1F\\x7F]*@[^\\x00-\\x1F\\x7F]*$", "type": "string" }, { "type": "null" } ], "default": null, "description": "Email for the ChartHero user expected to resolve this launch link. ChartHero normalizes and compares this case-insensitively against a verified ChartHero identity.", "examples": [ "clinician@example.com" ], "title": "Email" }, "external_ids": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ProviderExternalIdentifier" }, "maxItems": 16, "minItems": 1, "type": "array" }, { "type": "null" } ], "default": null, "description": "External provider identifiers for the user expected to resolve this launch link. When present, every supplied identifier must match the resolved ChartHero actor linkage. These identifiers are preferred when the partner system has a stable provider/user id.", "title": "External Ids" } }, "title": "EncryptedLaunchProviderIdentifierSubject", "type": "object" }, "ErrorDiagnosticAcknowledgement": { "additionalProperties": false, "description": "The only successful diagnostics acknowledgement.", "examples": [ { "status": "accepted" } ], "properties": { "status": { "const": "accepted", "examples": [ "accepted" ], "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "ErrorDiagnosticAcknowledgement", "type": "object" }, "ErrorDiagnosticCode": { "description": "The six direct HTTP-boundary observations eligible for a diagnostic.", "enum": [ "transport_timeout", "transport_error", "http_error", "response_too_large", "response_content_type_invalid", "response_json_invalid" ], "title": "ErrorDiagnosticCode", "type": "string" }, "ErrorDiagnosticRequest": { "additionalProperties": false, "description": "One failure ChartHero observed at the Custom Adapter HTTP boundary while calling a source endpoint. The body carries no PHI, no partner response content, and no ChartHero source request identifier.", "examples": [ { "diagnostic_id": "diag_2f1dcb4ce6764fbeaa89fe86487b7e37", "error_code": "response_json_invalid", "message": "POST /v1/launch/context returned a successful response that was empty, invalid JSON, or not a JSON object. Return one JSON object matching the endpoint contract.", "occurred_at": "2026-08-06T15:42:18Z", "response_status": 200, "source_endpoint": "/v1/launch/context" } ], "properties": { "diagnostic_id": { "description": "ChartHero-minted correlation value. It equals the X-ChartHero-Diagnostic-Id header on this callback and the same header on every transport attempt of the source call.", "examples": [ "diag_2f1dcb4ce6764fbeaa89fe86487b7e37" ], "pattern": "^diag_[0-9a-f]{32}$", "title": "Diagnostic Id", "type": "string" }, "error_code": { "$ref": "#/components/schemas/ErrorDiagnosticCode", "description": "Stable machine-readable diagnostic code.", "examples": [ "response_json_invalid" ] }, "message": { "description": "Fixed catalog guidance for this endpoint, code, and status combination. ChartHero call sites cannot supply arbitrary text.", "maxLength": 512, "minLength": 1, "title": "Message", "type": "string" }, "occurred_at": { "description": "Timezone-aware UTC completion time of the final selected source attempt.", "examples": [ "2026-08-06T15:42:18Z" ], "format": "date-time", "title": "Occurred At", "type": "string" }, "response_status": { "anyOf": [ { "maximum": 599.0, "minimum": 100.0, "type": "integer" }, { "type": "null" } ], "description": "Received HTTP status, or null for transport_timeout and transport_error, including read failures after response headers were received.", "examples": [ 200 ], "title": "Response Status" }, "source_endpoint": { "description": "Registered adapter source endpoint path ChartHero was calling. It is never a full URL and never the diagnostics path itself.", "enum": [ "/v1/appointments/search", "/v1/checklist-recommendations/fetch", "/v1/launch/context", "/v1/providers/search", "/v1/users/resolve-by-email", "/v1/validate-connection" ], "examples": [ "/v1/launch/context" ], "title": "Source Endpoint", "type": "string" } }, "required": [ "diagnostic_id", "source_endpoint", "error_code", "message", "response_status", "occurred_at" ], "title": "ErrorDiagnosticRequest", "type": "object" }, "LaunchContextRequest": { "additionalProperties": false, "examples": [ { "actor": { "active": true, "actor_id": "11111111-1111-4111-8111-111111111111", "actor_type": "user", "display_name": "Dr. Chris Smith", "email": "clinician@example.com", "external_ids": [ { "source": "provider_acme_care_prod", "type": "provider_id", "value": "prov-456" } ], "first_name": "Chris", "functional_roles": [ "provider" ], "governance_role": "member", "last_name": "Smith", "specialty": "Cardiology" }, "launch_id": "01JZ123456789ABCDEFGHJKLM", "launch_state": { "correlation_id": "launch-abc", "workflow_id": "schedule-row-123" } } ], "properties": { "actor": { "$ref": "#/components/schemas/ProviderIdentifierSubject", "description": "Authenticated ChartHero actor for this callback. Present when provider linking is required or when ChartHero has a valid actor context to send. This is enriched ChartHero user context, not the raw encrypted-launch actor object." }, "launch_id": { "description": "Validated launch jti from the encrypted launch payload.", "examples": [ "01JZ123456789ABCDEFGHJKLM" ], "maxLength": 128, "minLength": 16, "pattern": "^[A-Za-z0-9._:-]{16,128}$", "title": "Launch Id", "type": "string" }, "launch_state": { "additionalProperties": true, "description": "Opaque JSON object copied from the encrypted launch payload. Adapters own its meaning; ChartHero does not interpret it.", "examples": [ { "correlation_id": "launch-abc", "workflow_id": "schedule-row-123" } ], "title": "Launch State", "type": "object" } }, "required": [ "launch_state", "launch_id" ], "title": "LaunchContextRequest", "type": "object" }, "LaunchContextResponse": { "additionalProperties": false, "examples": [ { "patient": { "dob": "1970-01-01", "external_ids": [ { "source": "acme_care_prod", "type": "patient_id", "value": "pat-123" } ], "first_name": "Jane", "last_name": "Doe", "sex": "female" }, "setup_defaults": { "mode": "phone_call", "phone_call": { "to_e164": "+15551234567" }, "template_id": "00000000-0000-0000-0000-000000000013" } }, { "encounter": { "end_at": "2026-06-01T14:30:00Z", "external_ids": [ { "source": "acme_care_prod", "type": "appointment_id", "value": "apt-789" } ], "participants": [ { "actor_type": "provider", "provider": { "display_name": "Dr. Chris Smith", "email": "clinician@example.com", "external_ids": [ { "source": "provider_acme_care_prod", "type": "provider_id", "value": "prov-456" } ] }, "role": "scheduled_provider" } ], "patient": { "dob": "1970-01-01", "external_ids": [ { "source": "acme_care_prod", "type": "patient_id", "value": "pat-123" } ], "first_name": "Jane", "last_name": "Doe" }, "start_at": "2026-06-01T14:00:00Z" }, "setup_defaults": { "mode": "phone_call", "phone_call": { "to_e164": "+15551234567" }, "template_id": "00000000-0000-0000-0000-000000000013" } } ], "oneOf": [ { "not": { "required": [ "encounter" ] }, "required": [ "patient" ] }, { "not": { "required": [ "patient" ] }, "properties": { "encounter": { "required": [ "patient" ] } }, "required": [ "encounter" ] } ], "properties": { "encounter": { "$ref": "#/components/schemas/EncounterPreview", "description": "Encounter or appointment context ChartHero should open. Required for encounter launches and mutually exclusive with top-level patient." }, "patient": { "$ref": "#/components/schemas/Patient", "description": "Patient-only launch context. Return when the launch is not tied to an encounter or appointment. ChartHero creates a new local encounter for each newly minted patient-only launch. Omit when returning encounter context." }, "setup_defaults": { "anyOf": [ { "$ref": "#/components/schemas/LaunchSetupDefaults" }, { "type": "null" } ] } }, "title": "LaunchContextResponse", "type": "object" }, "LaunchKeyset": { "additionalProperties": false, "examples": [ { "keys": [ { "alg": "dir", "enc": "A256GCM", "k": "uF5t2qLGVMrT8zmQhC9aH0-7pQWBIJEPVwNXAXEuwpA", "kid": "launch-key-2026-06", "kty": "oct", "status": "active" } ], "version": 1 } ], "properties": { "keys": { "contains": { "properties": { "status": { "const": "active" } }, "required": [ "status" ], "type": "object" }, "description": "Launch keys. Exactly one key must have status active.", "items": { "$ref": "#/components/schemas/LaunchKeysetEntry" }, "maxContains": 1, "minContains": 1, "minItems": 1, "title": "Keys", "type": "array" }, "version": { "const": 1, "examples": [ 1 ], "title": "Version", "type": "integer" } }, "required": [ "version", "keys" ], "title": "LaunchKeyset", "type": "object" }, "LaunchKeysetEntry": { "additionalProperties": false, "properties": { "alg": { "const": "dir", "examples": [ "dir" ], "title": "Alg", "type": "string" }, "enc": { "const": "A256GCM", "examples": [ "A256GCM" ], "title": "Enc", "type": "string" }, "k": { "description": "Base64url-encoded 32-byte symmetric key.", "maxLength": 43, "minLength": 43, "pattern": "^[A-Za-z0-9_-]+$", "title": "K", "type": "string" }, "kid": { "examples": [ "launch-key-2026-06" ], "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+$", "title": "Kid", "type": "string" }, "kty": { "const": "oct", "examples": [ "oct" ], "title": "Kty", "type": "string" }, "status": { "enum": [ "active", "retired" ], "examples": [ "active" ], "title": "Status", "type": "string" } }, "required": [ "kid", "kty", "alg", "enc", "status", "k" ], "title": "LaunchKeysetEntry", "type": "object" }, "LaunchSetupDefaults": { "additionalProperties": false, "allOf": [ { "anyOf": [ { "required": [ "mode" ] }, { "required": [ "template_id" ] }, { "required": [ "phone_call" ] } ] }, { "not": { "properties": { "mode": { "enum": [ "dictation", "ambient" ] }, "phone_call": { "not": { "type": "null" } } }, "required": [ "mode", "phone_call" ] } } ], "description": "Optional setup defaults. If the object is present, at least one setup default field is required. First-level null values are treated as omitted. Non-null phone_call may only be combined with mode=phone_call.", "properties": { "mode": { "anyOf": [ { "enum": [ "dictation", "ambient", "phone_call" ], "type": "string" }, { "type": "null" } ], "title": "Mode" }, "phone_call": { "anyOf": [ { "$ref": "#/components/schemas/LaunchSetupPhoneCallDefaults" }, { "type": "null" } ] }, "template_id": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "ChartHero core template id provisioned as selectable for the launching user.", "examples": [ "00000000-0000-0000-0000-000000000013" ], "title": "Template Id" } }, "title": "LaunchSetupDefaults", "type": "object" }, "LaunchSetupPhoneCallDefaults": { "additionalProperties": false, "properties": { "to_e164": { "examples": [ "+15551234567" ], "pattern": "^\\+[1-9]\\d{1,14}$", "title": "To E164", "type": "string" } }, "required": [ "to_e164" ], "title": "LaunchSetupPhoneCallDefaults", "type": "object" }, "Patient": { "additionalProperties": false, "properties": { "dob": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "examples": [ "1970-01-01" ], "title": "Dob" }, "email": { "anyOf": [ { "maxLength": 320, "pattern": "^[^\\x00-\\x1F\\x7F]*$", "type": "string" }, { "type": "null" } ], "examples": [ "patient@example.com" ], "title": "Email" }, "ethnicity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ethnicity" }, "external_ids": { "description": "Stable identifiers for one upstream patient. Each source/type tuple may appear at most once for that subject.", "items": { "$ref": "#/components/schemas/PatientExternalIdentifier" }, "minItems": 1, "title": "External Ids", "type": "array" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Jane" ], "title": "First Name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Doe" ], "title": "Last Name" }, "middle_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Middle Name" }, "phone_cell_e164": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "+15551234567" ], "title": "Phone Cell E164" }, "phone_home_e164": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone Home E164" }, "phone_work_e164": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone Work E164" }, "race": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Race" }, "sex": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "female" ], "title": "Sex" }, "suffix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Suffix" } }, "required": [ "external_ids" ], "title": "Patient", "type": "object" }, "PatientExternalIdentifier": { "additionalProperties": false, "examples": [ { "source": "acme_care_prod", "type": "patient_id", "value": "pat-123" } ], "properties": { "source": { "description": "Organization-level external identifier source alias. Send this even when the adapter has one default source.", "examples": [ "default" ], "maxLength": 64, "minLength": 1, "pattern": "^[a-z][a-z0-9_]{0,63}$", "title": "Source", "type": "string" }, "type": { "description": "Identifier kind, such as `patient_id` or `appointment_id`; this is not the patient or encounter object itself.", "examples": [ "patient_id" ], "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]{1,64}$", "title": "Type", "type": "string" }, "value": { "description": "Stable non-ChartHero identifier value.", "examples": [ "pat-123" ], "maxLength": 256, "minLength": 1, "pattern": "^[^\\x00-\\x1f\\x7f]*[^\\s\\x00-\\x1f\\x7f][^\\x00-\\x1f\\x7f]*$", "title": "Value", "type": "string" } }, "required": [ "source", "type", "value" ], "title": "PatientExternalIdentifier", "type": "object" }, "ProviderActor": { "additionalProperties": false, "properties": { "active": { "anyOf": [ { "const": true, "type": "boolean" }, { "type": "null" } ], "description": "Required for provider directory and verified-email responses.", "examples": [ true ], "title": "Active" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Dr. Chris Smith" ], "title": "Display Name" }, "email": { "anyOf": [ { "maxLength": 320, "pattern": "^[^\\x00-\\x1F\\x7F]*$", "type": "string" }, { "type": "null" } ], "examples": [ "clinician@example.com" ], "title": "Email" }, "external_ids": { "description": "Stable identifiers for one upstream provider. Each source/type tuple may appear at most once for that subject.", "items": { "$ref": "#/components/schemas/ProviderExternalIdentifier" }, "minItems": 1, "title": "External Ids", "type": "array" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Chris" ], "title": "First Name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Smith" ], "title": "Last Name" } }, "required": [ "external_ids" ], "title": "ProviderActor", "type": "object" }, "ProviderDirectoryProvider": { "additionalProperties": false, "properties": { "active": { "const": true, "examples": [ true ], "title": "Active", "type": "boolean" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Dr. Chris Smith" ], "title": "Display Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "clinician@example.com" ], "title": "Email" }, "external_ids": { "description": "Stable identifiers for one upstream provider. Each source/type tuple may appear at most once for that subject.", "items": { "$ref": "#/components/schemas/ProviderExternalIdentifier" }, "minItems": 1, "title": "External Ids", "type": "array" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Chris" ], "title": "First Name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Smith" ], "title": "Last Name" } }, "required": [ "external_ids", "active" ], "title": "ProviderDirectoryProvider", "type": "object" }, "ProviderExternalIdentifier": { "additionalProperties": false, "examples": [ { "source": "provider_acme_care_prod", "type": "provider_id", "value": "prov-456" } ], "properties": { "source": { "description": "Configured provider identifier source alias.", "examples": [ "provider_acme_care_prod" ], "maxLength": 64, "minLength": 1, "pattern": "^[a-z][a-z0-9_]{0,63}$", "title": "Source", "type": "string" }, "type": { "const": "provider_id", "description": "External provider identifier type. MVP supports provider_id.", "examples": [ "provider_id" ], "title": "Type", "type": "string" }, "value": { "description": "Stable non-ChartHero identifier value.", "examples": [ "prov-456" ], "maxLength": 256, "minLength": 1, "pattern": "^[^\\x00-\\x1f\\x7f]*[^\\s\\x00-\\x1f\\x7f][^\\x00-\\x1f\\x7f]*$", "title": "Value", "type": "string" } }, "required": [ "source", "type", "value" ], "title": "ProviderExternalIdentifier", "type": "object" }, "ProviderIdentifierSubject": { "additionalProperties": false, "description": "ChartHero actor context sent to partner adapter endpoints. `actor_type` uses the same discriminator vocabulary as the public External API actor resource and is currently always `user` for launch-context adapter calls. `actor_id` is the ChartHero public actor identifier; `email`, name, specialty, and role fields describe the authenticated ChartHero user in the launching organization; `external_ids` contains partner provider/user identifiers only when provider linking exists.", "properties": { "active": { "description": "Whether the ChartHero user actor is active in the launching organization. Uses the same active-state meaning as public External API user actors.", "examples": [ true ], "title": "Active", "type": "boolean" }, "actor_id": { "description": "Stable ChartHero public actor identifier.", "examples": [ "11111111-1111-4111-8111-111111111111" ], "format": "uuid", "title": "Actor Id", "type": "string" }, "actor_type": { "const": "user", "description": "Actor discriminator. Currently always `user` for adapter calls.", "examples": [ "user" ], "title": "Actor Type", "type": "string" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Dr. Chris Smith" ], "title": "Display Name" }, "email": { "anyOf": [ { "maxLength": 320, "pattern": "^[^\\x00-\\x1F\\x7F]*$", "type": "string" }, { "type": "null" } ], "description": "Verified ChartHero user email when available.", "examples": [ "clinician@example.com" ], "title": "Email" }, "external_ids": { "description": "Partner/provider identifiers mapped to this ChartHero actor when provider linking exists for the installation.", "items": { "$ref": "#/components/schemas/ProviderExternalIdentifier" }, "title": "External Ids", "type": "array" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Chris" ], "title": "First Name" }, "functional_roles": { "examples": [ [ "provider" ] ], "items": { "type": "string" }, "title": "Functional Roles", "type": "array" }, "governance_role": { "anyOf": [ { "enum": [ "owner", "admin", "manager", "member" ], "type": "string" }, { "type": "null" } ], "examples": [ "member" ], "title": "Governance Role" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Smith" ], "title": "Last Name" }, "specialty": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Cardiology" ], "title": "Specialty" } }, "required": [ "actor_type", "actor_id", "active" ], "title": "ProviderIdentifierSubject", "type": "object" }, "ProviderSearchPaginationRequest": { "additionalProperties": false, "properties": { "limit": { "const": 100, "title": "Limit", "type": "integer" }, "offset": { "examples": [ 0 ], "minimum": 0.0, "title": "Offset", "type": "integer" } }, "required": [ "limit", "offset" ], "title": "ProviderSearchPaginationRequest", "type": "object" }, "ProviderSearchPaginationResponseComplete": { "additionalProperties": false, "properties": { "has_more": { "const": false, "examples": [ false ], "title": "Has More", "type": "boolean" }, "limit": { "const": 100, "examples": [ 100 ], "title": "Limit", "type": "integer" }, "next_offset": { "description": "Omit or return null when has_more is false.", "examples": [ null ], "title": "Next Offset", "type": "null" }, "offset": { "examples": [ 0 ], "minimum": 0.0, "title": "Offset", "type": "integer" } }, "required": [ "limit", "offset", "has_more" ], "title": "ProviderSearchPaginationResponseComplete", "type": "object" }, "ProviderSearchPaginationResponseHasMore": { "additionalProperties": false, "properties": { "has_more": { "const": true, "examples": [ true ], "title": "Has More", "type": "boolean" }, "limit": { "const": 100, "examples": [ 100 ], "title": "Limit", "type": "integer" }, "next_offset": { "description": "Required and greater than offset when has_more is true.", "examples": [ 100 ], "minimum": 0.0, "title": "Next Offset", "type": "integer" }, "offset": { "examples": [ 0 ], "minimum": 0.0, "title": "Offset", "type": "integer" } }, "required": [ "limit", "offset", "next_offset", "has_more" ], "title": "ProviderSearchPaginationResponseHasMore", "type": "object" }, "ProviderSearchQuery": { "additionalProperties": false, "properties": { "active_only": { "const": true, "default": true, "title": "Active Only", "type": "boolean" }, "updated_since": { "title": "Updated Since", "type": "null" } }, "required": [ "active_only", "updated_since" ], "title": "ProviderSearchQuery", "type": "object" }, "ProviderSearchRequest": { "additionalProperties": false, "examples": [ { "pagination": { "limit": 100, "offset": 0 }, "query": { "active_only": true, "updated_since": null } } ], "properties": { "pagination": { "$ref": "#/components/schemas/ProviderSearchPaginationRequest" }, "query": { "$ref": "#/components/schemas/ProviderSearchQuery" } }, "required": [ "query", "pagination" ], "title": "ProviderSearchRequest", "type": "object" }, "ProviderSearchResponse": { "additionalProperties": false, "examples": [ { "pagination": { "has_more": true, "limit": 100, "next_offset": 100, "offset": 0 }, "providers": [ { "active": true, "display_name": "Dr. Chris Smith", "email": "clinician@example.com", "external_ids": [ { "source": "provider_acme_care_prod", "type": "provider_id", "value": "prov-456" } ], "first_name": "Chris", "last_name": "Smith" } ] } ], "properties": { "pagination": { "anyOf": [ { "$ref": "#/components/schemas/ProviderSearchPaginationResponseHasMore" }, { "$ref": "#/components/schemas/ProviderSearchPaginationResponseComplete" } ], "title": "Pagination" }, "providers": { "items": { "$ref": "#/components/schemas/ProviderDirectoryProvider" }, "title": "Providers", "type": "array" } }, "required": [ "providers", "pagination" ], "title": "ProviderSearchResponse", "type": "object" }, "ResolvedExternalUser": { "additionalProperties": false, "properties": { "active": { "const": true, "examples": [ true ], "title": "Active", "type": "boolean" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Dr. Chris Smith" ], "title": "Display Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "clinician@example.com" ], "title": "Email" }, "external_ids": { "description": "Stable identifiers for one upstream provider. Each source/type tuple may appear at most once for that subject.", "items": { "$ref": "#/components/schemas/ProviderExternalIdentifier" }, "minItems": 1, "title": "External Ids", "type": "array" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Chris" ], "title": "First Name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Smith" ], "title": "Last Name" } }, "required": [ "external_ids", "active" ], "title": "ResolvedExternalUser", "type": "object" }, "UserResolveByEmailRequest": { "additionalProperties": false, "examples": [ { "email": "clinician@example.com", "purpose": "launch_user_mapping" } ], "properties": { "email": { "description": "Verified ChartHero user email. Partner lookup should treat email case-insensitively and return one active external user or an error.", "examples": [ "clinician@example.com" ], "title": "Email", "type": "string" }, "purpose": { "const": "launch_user_mapping", "examples": [ "launch_user_mapping" ], "title": "Purpose", "type": "string" } }, "required": [ "email", "purpose" ], "title": "UserResolveByEmailRequest", "type": "object" }, "UserResolveByEmailResponse": { "additionalProperties": false, "examples": [ { "external_user": { "active": true, "display_name": "Dr. Chris Smith", "email": "clinician@example.com", "external_ids": [ { "source": "provider_acme_care_prod", "type": "provider_id", "value": "prov-456" } ] } } ], "properties": { "external_user": { "$ref": "#/components/schemas/ResolvedExternalUser" } }, "required": [ "external_user" ], "title": "UserResolveByEmailResponse", "type": "object" }, "ValidateConnectionRequest": { "additionalProperties": false, "examples": [ {} ], "properties": {}, "title": "ValidateConnectionRequest", "type": "object" }, "ValidateConnectionResponse": { "additionalProperties": false, "examples": [ { "status": "ok" } ], "properties": { "status": { "const": "ok", "examples": [ "ok" ], "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "ValidateConnectionResponse", "type": "object" } }, "securitySchemes": { "partnerAuthorizationHeader": { "description": "ChartHero sends the saved adapter credential verbatim as the Authorization header value, for example `Bearer abc123`, `ApiKey abc123`, or a bare token.", "in": "header", "name": "Authorization", "type": "apiKey" } } }, "info": { "description": "Contract for partner-implemented adapter endpoints that ChartHero calls. ChartHero-hosted public API routes are intentionally excluded.", "title": "ChartHero Adapter Contract", "version": "1.0" }, "openapi": "3.1.0", "paths": { "/v1/checklist-recommendations/fetch": { "post": { "description": "Return ordered partner-recommended encounter prep items. The MVP supports recommendation_set items; recommendation sets contain blocks, blocks contain tasks, and tasks may contain subtasks. Use provenance when a recommendation item corresponds to a stable upstream source object. source_id, source_system, and source_type describe that upstream origin. Recommendation import/dedupe behavior is not part of this v1 endpoint contract.", "operationId": "fetchChecklistRecommendations", "parameters": [ { "description": "Adapter contract version ChartHero expects for this request.", "example": "1.0", "in": "header", "name": "X-ChartHero-Contract-Version", "required": true, "schema": { "type": "string" } }, { "description": "Opaque request identifier for partner logs and support.", "example": "req_01JZ123456789ABCDEFGHJKLM", "in": "header", "name": "X-ChartHero-Request-Id", "required": true, "schema": { "type": "string" } }, { "description": "Sent only when error diagnostics is enabled for the installation. The same value is repeated on every ChartHero retry of this call and is the correlation value for any resulting diagnostics callback. Log it; do not require it.", "example": "diag_2f1dcb4ce6764fbeaa89fe86487b7e37", "in": "header", "name": "X-ChartHero-Diagnostic-Id", "required": false, "schema": { "pattern": "^diag_[0-9a-f]{32}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChecklistRecommendationsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChecklistRecommendationsResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/json": { "example": { "error_code": "invalid_request", "message": "Request shape or field validation failed.", "retryable": false }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "error_code": "invalid_request", "message": "Request shape or field validation failed.", "retryable": false } }, "unsupported_contract_version": { "summary": "unsupported_contract_version", "value": { "error_code": "unsupported_contract_version", "message": "Requested contract version is not supported.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "invalid_request, unsupported_contract_version" }, "401": { "content": { "application/json": { "example": { "error_code": "unauthorized", "message": "Authorization header value is missing or invalid.", "retryable": false }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "error_code": "unauthorized", "message": "Authorization header value is missing or invalid.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "unauthorized" }, "403": { "content": { "application/json": { "example": { "error_code": "forbidden", "message": "Authorization header value is not authorized for this adapter.", "retryable": false }, "examples": { "forbidden": { "summary": "forbidden", "value": { "error_code": "forbidden", "message": "Authorization header value is not authorized for this adapter.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "forbidden" }, "404": { "content": { "application/json": { "example": { "error_code": "patient_not_found", "message": "Patient was not found.", "retryable": false }, "examples": { "appointment_not_found": { "summary": "appointment_not_found", "value": { "error_code": "appointment_not_found", "message": "Appointment was not found.", "retryable": false } }, "patient_not_found": { "summary": "patient_not_found", "value": { "error_code": "patient_not_found", "message": "Patient was not found.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "patient_not_found, appointment_not_found" }, "409": { "content": { "application/json": { "example": { "error_code": "identifier_mismatch", "message": "Supplied identifiers do not belong together.", "retryable": false }, "examples": { "identifier_mismatch": { "summary": "identifier_mismatch", "value": { "error_code": "identifier_mismatch", "message": "Supplied identifiers do not belong together.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "identifier_mismatch" }, "429": { "content": { "application/json": { "example": { "error_code": "rate_limited", "message": "Partner endpoint rate-limited the request.", "retryable": true }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error_code": "rate_limited", "message": "Partner endpoint rate-limited the request.", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "rate_limited" }, "503": { "content": { "application/json": { "example": { "error_code": "temporarily_unavailable", "message": "Partner endpoint is temporarily unavailable.", "retryable": true }, "examples": { "temporarily_unavailable": { "summary": "temporarily_unavailable", "value": { "error_code": "temporarily_unavailable", "message": "Partner endpoint is temporarily unavailable.", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "temporarily_unavailable" } }, "security": [ { "partnerAuthorizationHeader": [] } ], "summary": "Fetch checklist recommendations", "tags": [ "Adapters" ], "x-charthero-adapter-contract-version": "1.0", "x-charthero-capability": "checklist_recommendations", "x-charthero-partner-implemented": true } }, "/v1/diagnostics/errors": { "post": { "description": "Optional receiver for ChartHero-observed adapter failures. It is sent only when an organization enables error diagnostics for the installation, and ChartHero reuses the configured base URL and `Authorization` value. ChartHero reports only failures observed at the HTTP boundary of a source call: transport timeouts, transport errors, non-2xx statuses, oversized responses, non-JSON content types, and successful responses that are not one JSON object. It does not report semantic validation of an otherwise valid JSON response, ChartHero-local failures, or diagnostics delivery failures.\n\nCorrelate the callback with the source call using `X-ChartHero-Diagnostic-Id`, which is identical on the source attempts and on this callback. `X-ChartHero-Request-Id` on this callback identifies only the callback request; it is never the source request identifier.\n\nRespond with exactly `{\"status\":\"accepted\"}` and HTTP 200. ChartHero makes one delivery attempt per eligible failure and never retries it, so treat a missed diagnostic as expected rather than as a gap to reconcile. Log the diagnostic ID and code; the body intentionally carries no PHI, credentials, or source request content.", "operationId": "reportErrorDiagnostic", "parameters": [ { "description": "Adapter contract version ChartHero expects for this request.", "example": "1.0", "in": "header", "name": "X-ChartHero-Contract-Version", "required": true, "schema": { "type": "string" } }, { "description": "Opaque request identifier for partner logs and support.", "example": "req_01JZ123456789ABCDEFGHJKLM", "in": "header", "name": "X-ChartHero-Request-Id", "required": true, "schema": { "type": "string" } }, { "description": "ChartHero-minted diagnostic identifier. It must equal the request body `diagnostic_id`; return `400 invalid_request` when they differ.", "example": "diag_2f1dcb4ce6764fbeaa89fe86487b7e37", "in": "header", "name": "X-ChartHero-Diagnostic-Id", "required": true, "schema": { "pattern": "^diag_[0-9a-f]{32}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDiagnosticRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDiagnosticAcknowledgement" } } }, "description": "Successful Response" }, "400": { "content": { "application/json": { "example": { "error_code": "invalid_request", "message": "Request shape or field validation failed.", "retryable": false }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "error_code": "invalid_request", "message": "Request shape or field validation failed.", "retryable": false } }, "unsupported_contract_version": { "summary": "unsupported_contract_version", "value": { "error_code": "unsupported_contract_version", "message": "Requested contract version is not supported.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "invalid_request, unsupported_contract_version" }, "401": { "content": { "application/json": { "example": { "error_code": "unauthorized", "message": "Authorization header value is missing or invalid.", "retryable": false }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "error_code": "unauthorized", "message": "Authorization header value is missing or invalid.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "unauthorized" }, "403": { "content": { "application/json": { "example": { "error_code": "forbidden", "message": "Authorization header value is not authorized for this adapter.", "retryable": false }, "examples": { "forbidden": { "summary": "forbidden", "value": { "error_code": "forbidden", "message": "Authorization header value is not authorized for this adapter.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "forbidden" }, "429": { "content": { "application/json": { "example": { "error_code": "rate_limited", "message": "Partner endpoint rate-limited the request.", "retryable": true }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error_code": "rate_limited", "message": "Partner endpoint rate-limited the request.", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "rate_limited" }, "503": { "content": { "application/json": { "example": { "error_code": "temporarily_unavailable", "message": "Partner endpoint is temporarily unavailable.", "retryable": true }, "examples": { "temporarily_unavailable": { "summary": "temporarily_unavailable", "value": { "error_code": "temporarily_unavailable", "message": "Partner endpoint is temporarily unavailable.", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "temporarily_unavailable" } }, "security": [ { "partnerAuthorizationHeader": [] } ], "summary": "Report error diagnostic", "tags": [ "Adapters" ], "x-charthero-adapter-contract-version": "1.0", "x-charthero-partner-implemented": true } }, "/v1/launch/context": { "post": { "description": "Resolve adapter-owned launch_state into the patient plus optional encounter and setup defaults ChartHero should open.", "operationId": "getLaunchContext", "parameters": [ { "description": "Adapter contract version ChartHero expects for this request.", "example": "1.0", "in": "header", "name": "X-ChartHero-Contract-Version", "required": true, "schema": { "type": "string" } }, { "description": "Opaque request identifier for partner logs and support.", "example": "req_01JZ123456789ABCDEFGHJKLM", "in": "header", "name": "X-ChartHero-Request-Id", "required": true, "schema": { "type": "string" } }, { "description": "Sent only when error diagnostics is enabled for the installation. The same value is repeated on every ChartHero retry of this call and is the correlation value for any resulting diagnostics callback. Log it; do not require it.", "example": "diag_2f1dcb4ce6764fbeaa89fe86487b7e37", "in": "header", "name": "X-ChartHero-Diagnostic-Id", "required": false, "schema": { "pattern": "^diag_[0-9a-f]{32}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchContextRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchContextResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/json": { "example": { "error_code": "invalid_request", "message": "Request shape or field validation failed.", "retryable": false }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "error_code": "invalid_request", "message": "Request shape or field validation failed.", "retryable": false } }, "unsupported_contract_version": { "summary": "unsupported_contract_version", "value": { "error_code": "unsupported_contract_version", "message": "Requested contract version is not supported.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "invalid_request, unsupported_contract_version" }, "401": { "content": { "application/json": { "example": { "error_code": "unauthorized", "message": "Authorization header value is missing or invalid.", "retryable": false }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "error_code": "unauthorized", "message": "Authorization header value is missing or invalid.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "unauthorized" }, "403": { "content": { "application/json": { "example": { "error_code": "forbidden", "message": "Authorization header value is not authorized for this adapter.", "retryable": false }, "examples": { "forbidden": { "summary": "forbidden", "value": { "error_code": "forbidden", "message": "Authorization header value is not authorized for this adapter.", "retryable": false } }, "permission_denied": { "summary": "permission_denied", "value": { "error_code": "permission_denied", "message": "Actor cannot access the requested context.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "forbidden, permission_denied" }, "404": { "content": { "application/json": { "example": { "error_code": "patient_not_found", "message": "Patient was not found.", "retryable": false }, "examples": { "appointment_not_found": { "summary": "appointment_not_found", "value": { "error_code": "appointment_not_found", "message": "Appointment was not found.", "retryable": false } }, "patient_not_found": { "summary": "patient_not_found", "value": { "error_code": "patient_not_found", "message": "Patient was not found.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "patient_not_found, appointment_not_found" }, "409": { "content": { "application/json": { "example": { "error_code": "identifier_mismatch", "message": "Supplied identifiers do not belong together.", "retryable": false }, "examples": { "identifier_mismatch": { "summary": "identifier_mismatch", "value": { "error_code": "identifier_mismatch", "message": "Supplied identifiers do not belong together.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "identifier_mismatch" }, "429": { "content": { "application/json": { "example": { "error_code": "rate_limited", "message": "Partner endpoint rate-limited the request.", "retryable": true }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error_code": "rate_limited", "message": "Partner endpoint rate-limited the request.", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "rate_limited" }, "503": { "content": { "application/json": { "example": { "error_code": "temporarily_unavailable", "message": "Partner endpoint is temporarily unavailable.", "retryable": true }, "examples": { "temporarily_unavailable": { "summary": "temporarily_unavailable", "value": { "error_code": "temporarily_unavailable", "message": "Partner endpoint is temporarily unavailable.", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "temporarily_unavailable" } }, "security": [ { "partnerAuthorizationHeader": [] } ], "summary": "Get launch context", "tags": [ "Adapters" ], "x-charthero-adapter-contract-version": "1.0", "x-charthero-capability": "launch_context", "x-charthero-partner-implemented": true } }, "/v1/providers/search": { "post": { "description": "Return provider directory rows for reviewed mapping and provider linking. This endpoint is not actor-scoped.", "operationId": "searchProviders", "parameters": [ { "description": "Adapter contract version ChartHero expects for this request.", "example": "1.0", "in": "header", "name": "X-ChartHero-Contract-Version", "required": true, "schema": { "type": "string" } }, { "description": "Opaque request identifier for partner logs and support.", "example": "req_01JZ123456789ABCDEFGHJKLM", "in": "header", "name": "X-ChartHero-Request-Id", "required": true, "schema": { "type": "string" } }, { "description": "Sent only when error diagnostics is enabled for the installation. The same value is repeated on every ChartHero retry of this call and is the correlation value for any resulting diagnostics callback. Log it; do not require it.", "example": "diag_2f1dcb4ce6764fbeaa89fe86487b7e37", "in": "header", "name": "X-ChartHero-Diagnostic-Id", "required": false, "schema": { "pattern": "^diag_[0-9a-f]{32}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderSearchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderSearchResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/json": { "example": { "error_code": "invalid_request", "message": "Request shape or field validation failed.", "retryable": false }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "error_code": "invalid_request", "message": "Request shape or field validation failed.", "retryable": false } }, "unsupported_contract_version": { "summary": "unsupported_contract_version", "value": { "error_code": "unsupported_contract_version", "message": "Requested contract version is not supported.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "invalid_request, unsupported_contract_version" }, "401": { "content": { "application/json": { "example": { "error_code": "unauthorized", "message": "Authorization header value is missing or invalid.", "retryable": false }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "error_code": "unauthorized", "message": "Authorization header value is missing or invalid.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "unauthorized" }, "403": { "content": { "application/json": { "example": { "error_code": "forbidden", "message": "Authorization header value is not authorized for this adapter.", "retryable": false }, "examples": { "forbidden": { "summary": "forbidden", "value": { "error_code": "forbidden", "message": "Authorization header value is not authorized for this adapter.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "forbidden" }, "429": { "content": { "application/json": { "example": { "error_code": "rate_limited", "message": "Partner endpoint rate-limited the request.", "retryable": true }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error_code": "rate_limited", "message": "Partner endpoint rate-limited the request.", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "rate_limited" }, "503": { "content": { "application/json": { "example": { "error_code": "temporarily_unavailable", "message": "Partner endpoint is temporarily unavailable.", "retryable": true }, "examples": { "temporarily_unavailable": { "summary": "temporarily_unavailable", "value": { "error_code": "temporarily_unavailable", "message": "Partner endpoint is temporarily unavailable.", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "temporarily_unavailable" } }, "security": [ { "partnerAuthorizationHeader": [] } ], "summary": "Search providers", "tags": [ "Adapters" ], "x-charthero-adapter-contract-version": "1.0", "x-charthero-capability": "provider_directory", "x-charthero-partner-implemented": true } }, "/v1/users/resolve-by-email": { "post": { "description": "Optional helper for creating provider links from a verified ChartHero user email to stable partner external identifiers.", "operationId": "resolveUserByEmail", "parameters": [ { "description": "Adapter contract version ChartHero expects for this request.", "example": "1.0", "in": "header", "name": "X-ChartHero-Contract-Version", "required": true, "schema": { "type": "string" } }, { "description": "Opaque request identifier for partner logs and support.", "example": "req_01JZ123456789ABCDEFGHJKLM", "in": "header", "name": "X-ChartHero-Request-Id", "required": true, "schema": { "type": "string" } }, { "description": "Sent only when error diagnostics is enabled for the installation. The same value is repeated on every ChartHero retry of this call and is the correlation value for any resulting diagnostics callback. Log it; do not require it.", "example": "diag_2f1dcb4ce6764fbeaa89fe86487b7e37", "in": "header", "name": "X-ChartHero-Diagnostic-Id", "required": false, "schema": { "pattern": "^diag_[0-9a-f]{32}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResolveByEmailRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResolveByEmailResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/json": { "example": { "error_code": "invalid_request", "message": "Request shape or field validation failed.", "retryable": false }, "examples": { "invalid_request": { "summary": "invalid_request", "value": { "error_code": "invalid_request", "message": "Request shape or field validation failed.", "retryable": false } }, "unsupported_contract_version": { "summary": "unsupported_contract_version", "value": { "error_code": "unsupported_contract_version", "message": "Requested contract version is not supported.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "invalid_request, unsupported_contract_version" }, "401": { "content": { "application/json": { "example": { "error_code": "unauthorized", "message": "Authorization header value is missing or invalid.", "retryable": false }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "error_code": "unauthorized", "message": "Authorization header value is missing or invalid.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "unauthorized" }, "403": { "content": { "application/json": { "example": { "error_code": "forbidden", "message": "Authorization header value is not authorized for this adapter.", "retryable": false }, "examples": { "forbidden": { "summary": "forbidden", "value": { "error_code": "forbidden", "message": "Authorization header value is not authorized for this adapter.", "retryable": false } }, "permission_denied": { "summary": "permission_denied", "value": { "error_code": "permission_denied", "message": "Actor cannot access the requested context.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "forbidden, permission_denied" }, "404": { "content": { "application/json": { "example": { "error_code": "external_user_not_found", "message": "Verified email did not resolve to a user.", "retryable": false }, "examples": { "external_user_not_found": { "summary": "external_user_not_found", "value": { "error_code": "external_user_not_found", "message": "Verified email did not resolve to a user.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "external_user_not_found" }, "409": { "content": { "application/json": { "example": { "error_code": "email_ambiguous", "message": "Verified email resolved to more than one user.", "retryable": false }, "examples": { "email_ambiguous": { "summary": "email_ambiguous", "value": { "error_code": "email_ambiguous", "message": "Verified email resolved to more than one user.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "email_ambiguous" }, "429": { "content": { "application/json": { "example": { "error_code": "rate_limited", "message": "Partner endpoint rate-limited the request.", "retryable": true }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error_code": "rate_limited", "message": "Partner endpoint rate-limited the request.", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "rate_limited" }, "503": { "content": { "application/json": { "example": { "error_code": "temporarily_unavailable", "message": "Partner endpoint is temporarily unavailable.", "retryable": true }, "examples": { "temporarily_unavailable": { "summary": "temporarily_unavailable", "value": { "error_code": "temporarily_unavailable", "message": "Partner endpoint is temporarily unavailable.", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "temporarily_unavailable" } }, "security": [ { "partnerAuthorizationHeader": [] } ], "summary": "Resolve user by verified email", "tags": [ "Adapters" ], "x-charthero-adapter-contract-version": "1.0", "x-charthero-capability": "user_lookup_by_email", "x-charthero-partner-implemented": true } }, "/v1/validate-connection": { "post": { "description": "Lightweight non-PHI connectivity health check. ChartHero sends an empty JSON body and expects a strict `{\"status\":\"ok\"}` response.", "operationId": "validateConnection", "parameters": [ { "description": "Adapter contract version ChartHero expects for this request.", "example": "1.0", "in": "header", "name": "X-ChartHero-Contract-Version", "required": true, "schema": { "type": "string" } }, { "description": "Opaque request identifier for partner logs and support.", "example": "req_01JZ123456789ABCDEFGHJKLM", "in": "header", "name": "X-ChartHero-Request-Id", "required": true, "schema": { "type": "string" } }, { "description": "Sent only when error diagnostics is enabled for the installation. The same value is repeated on every ChartHero retry of this call and is the correlation value for any resulting diagnostics callback. Log it; do not require it.", "example": "diag_2f1dcb4ce6764fbeaa89fe86487b7e37", "in": "header", "name": "X-ChartHero-Diagnostic-Id", "required": false, "schema": { "pattern": "^diag_[0-9a-f]{32}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateConnectionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateConnectionResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/json": { "example": { "error_code": "unsupported_contract_version", "message": "Requested contract version is not supported.", "retryable": false }, "examples": { "unsupported_contract_version": { "summary": "unsupported_contract_version", "value": { "error_code": "unsupported_contract_version", "message": "Requested contract version is not supported.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "unsupported_contract_version" }, "401": { "content": { "application/json": { "example": { "error_code": "unauthorized", "message": "Authorization header value is missing or invalid.", "retryable": false }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "error_code": "unauthorized", "message": "Authorization header value is missing or invalid.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "unauthorized" }, "403": { "content": { "application/json": { "example": { "error_code": "forbidden", "message": "Authorization header value is not authorized for this adapter.", "retryable": false }, "examples": { "forbidden": { "summary": "forbidden", "value": { "error_code": "forbidden", "message": "Authorization header value is not authorized for this adapter.", "retryable": false } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "forbidden" }, "429": { "content": { "application/json": { "example": { "error_code": "rate_limited", "message": "Partner endpoint rate-limited the request.", "retryable": true }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error_code": "rate_limited", "message": "Partner endpoint rate-limited the request.", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "rate_limited" }, "503": { "content": { "application/json": { "example": { "error_code": "temporarily_unavailable", "message": "Partner endpoint is temporarily unavailable.", "retryable": true }, "examples": { "temporarily_unavailable": { "summary": "temporarily_unavailable", "value": { "error_code": "temporarily_unavailable", "message": "Partner endpoint is temporarily unavailable.", "retryable": true } } }, "schema": { "$ref": "#/components/schemas/AdapterErrorResponse" } } }, "description": "temporarily_unavailable" } }, "security": [ { "partnerAuthorizationHeader": [] } ], "summary": "Validate connection", "tags": [ "Adapters" ], "x-charthero-adapter-contract-version": "1.0", "x-charthero-partner-implemented": true } } }, "servers": [ { "description": "Example partner-configured adapter base URL", "url": "https://ehr.example.com/integrations/charthero" } ], "tags": [ { "description": "Partner-implemented endpoints under the configured adapter base URL.", "name": "Adapters" } ] }