{ "openapi": "3.1.0", "info": { "title": "Scribe Public API", "description": "External-facing REST API for integrating with the Telepatia platform. Authenticate with API keys, set consultation context, and look up scribe sessions.", "version": "0.1.0" }, "paths": { "/v1/auth/login": { "post": { "tags": [ "Authentication" ], "summary": "Login", "description": "Login via API key. Returns a verification code.", "operationId": "api_login_v1_auth_login_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" }, "example": { "consultationInternalId": "cons_abc123" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" }, "example": { "code": "K7M2P9X4A1B8N3Q6R5T0V7W2Y9Z4C1D8", "expiresAt": "2026-02-20T18:30:00Z", "expiresIn": 900, "redirectUrl": "https://scribe.telepatia.ai/sign-in?code=K7M2P9X4A1B8N3Q6R5T0V7W2Y9Z4C1D8&consultationInternalId=cons_abc123" } } } }, "400": { "description": "Bad Request \u2014 invalid parameters, validation failures, or missing fields.", "content": { "application/json": { "examples": { "parameter_invalid": { "summary": "Invalid consultation ID format", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "consultationInternalId must contain only alphanumeric characters, hyphens, and underscores.", "param": "consultationInternalId", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "account_invalid": { "summary": "Account has no auth ID", "value": { "error": { "type": "invalid_request_error", "code": "account_invalid", "message": "Account has no valid authId.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Verification code could not be minted", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "Unable to generate verification code. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/set-consultation-context": { "post": { "tags": [ "Consultation" ], "summary": "Set Consultation Context", "description": "Set consultation context for a patient session.", "operationId": "api_consultation_context_set_post_v1_set_consultation_context_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetConsultationContextRequest" }, "example": { "consultationInternalId": "CONSULT-12345", "idCountry": "COLOMBIA", "idType": "PASSPORT", "idValue": "A12345678", "institutionalBranchId": "b1f2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "internalCode": "MRN-000123", "medicalRecordConfigurationId": "mrc_a1b2c3d4e5f6g7h8", "name": "John Doe", "notes": "Patient prefers morning appointments. Allergic to penicillin.", "pastMedicalHistory": "Hypertension diagnosed 2020. Diabetes Type 2 controlled with metformin.", "scribeSessionModality": "IN_PERSON" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetConsultationContextResponse" }, "example": { "consultationInternalId": "CONSULT-12345", "success": true } } } }, "400": { "description": "Bad Request \u2014 invalid parameters, validation failures, or missing fields.", "content": { "application/json": { "examples": { "parameter_missing": { "summary": "Missing required field", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "name is required.", "param": "name", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "parameter_invalid": { "summary": "Invalid field value", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code.", "param": "idCountry", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "account_invalid": { "summary": "Invalid account", "value": { "error": { "type": "invalid_request_error", "code": "account_invalid", "message": "Account has no valid authId.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the requested resource does not exist.", "content": { "application/json": { "examples": { "resource_not_found": { "summary": "Medical record configuration not found", "value": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "Medical record configuration not found.", "param": "medicalRecordConfigurationId", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 resource already exists or is in a conflicting state.", "content": { "application/json": { "examples": { "resource_conflict": { "summary": "consultationInternalId already in use", "value": { "error": { "type": "invalid_request_error", "code": "resource_conflict", "message": "consultationInternalId is already in use by a different consultation.", "param": "consultationInternalId", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "resource_not_active": { "summary": "Medical record configuration exists but is not active", "value": { "error": { "type": "invalid_request_error", "code": "resource_not_active", "message": "Medical record configuration 'mrc_a1b2c3d4e5f6g7h8' is not active yet.", "param": "medicalRecordConfigurationId", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Failed to set consultation context", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "Failed to set consultation context. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/scribe-sessions/{id}": { "get": { "tags": [ "Session Scribes" ], "summary": "Look Up Scribe Session", "description": "Look up a scribe session by ID.", "operationId": "api_scribe_session_retrieved_v1_scribe_sessions__id__get", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$", "description": "The session to look up \u2014 either your consultationInternalId, or the session id (ss_...) the API returns.", "examples": [ "CONSULT-12345", "ss_sa98vgqyra91q5b8" ], "title": "Id" }, "description": "The session to look up \u2014 either your consultationInternalId, or the session id (ss_...) the API returns." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionScribeLookupResponse" }, "example": { "completedAt": "2026-02-20T10:30:00Z", "consultationInternalId": "CONSULT-12345", "createdAt": "2026-02-20T10:00:00Z", "id": "ss_a1b2c3d4e5f6g7h8", "patientName": "John Doe", "scribeSessionModality": "IN_PERSON", "specialty": "Cardiology", "status": "completed" } } } }, "400": { "description": "Bad Request \u2014 invalid parameters, validation failures, or missing fields.", "content": { "application/json": { "examples": { "parameter_invalid": { "summary": "Invalid consultation ID format", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "id must contain only alphanumeric characters, hyphens, and underscores.", "param": "id", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "account_invalid": { "summary": "Account has no auth ID", "value": { "error": { "type": "invalid_request_error", "code": "account_invalid", "message": "Account has no valid authId.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the requested resource does not exist.", "content": { "application/json": { "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "No session scribe found for the given consultation ID.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "428": { "description": "Precondition Required", "content": { "application/json": { "examples": { "cdss_review_required": { "summary": "Doctor has pending CDSS suggestions awaiting review", "value": { "error": { "type": "invalid_request_error", "code": "cdss_review_required", "message": "This doctor has 1 pending CDSS suggestion awaiting review from the last 7 days. The API is blocked by your institution until the suggestions are reviewed. Open the consultation(s) to accept or reject them: https://scribe.telepatia.ai/consultations/session-abc-123.", "details": { "pendingConsultations": [ { "sessionId": "session-abc-123", "url": "https://scribe.telepatia.ai/consultations/session-abc-123" } ] }, "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Failed to look up session scribe", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "Failed to look up session scribe. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/scribe-sessions/{id}/medical-record-documents": { "get": { "tags": [ "Medical Record Documents" ], "summary": "List Medical Record Documents", "description": "List the medical record documents produced for a scribe session.\n\nA dictated report (`purpose` 'report') also carries `reportState`, which says\nwhether the radiologist signed it. Every other record has no workflow, so its\n`reportState` is null. Check `reportState.lifecycleStatus` before you use a\nreport: a `draft` is not complete, and the radiologist can still change it.", "operationId": "api_medical_record_documents_listed_v1_scribe_sessions__id__medical_record_documents_get", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$", "description": "The session to look up \u2014 either your consultationInternalId, or the session id (ss_...) the API returns.", "examples": [ "CONSULT-12345", "ss_sa98vgqyra91q5b8" ], "title": "Id" }, "description": "The session to look up \u2014 either your consultationInternalId, or the session id (ss_...) the API returns." }, { "name": "purpose", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Optional filter \u2014 return only documents with this purpose. Use 'report' to get only the dictated reports.", "examples": [ "primary" ], "title": "Purpose" }, "description": "Optional filter \u2014 return only documents with this purpose. Use 'report' to get only the dictated reports." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MedicalRecordDocumentListResponse" }, "example": { "items": [ { "cdssAlerts": [ { "action": "Suspend ibuprofen; consider paracetamol.", "actionCategory": "replace", "element": "Ibuprofen 600mg q8h", "elementId": "IBUPROFEN", "id": "cfa_bXJkLWFiYy0xMjMfSUJVUFJPRkVO", "issue": "not_pertinent", "newPlanElement": { "content": "Paracetamol 1g q8h PO", "element": "Paracetamol", "id": "PARACETAMOL", "type": "medication" }, "reason": "NSAID contraindicated with documented CKD.", "severity": "red", "source": [ "KDIGO 2024 CKD guideline" ], "status": "pending", "type": "medication" } ], "createdAt": "2026-02-20T10:30:00Z", "diagnosisCodes": [ { "code": "I10", "description": "Essential (primary) hypertension", "type": "primary" } ], "id": "mrd-abc-123", "language": "en", "medicalRecord": { "assessmentPlan": { "assessment": "Likely stable angina.", "plan": [ { "content": "Reduce saturated fat intake.", "element": "Dietary counseling", "id": "DIETARY_COUNSELING", "laboratory": "", "type": "non_pharmacological" } ] }, "chiefComplaint": "Chest pain for two days.", "vitalSigns": { "bloodPressure": "120/80", "heartRate": "78", "temperature": "" } }, "medicalRecordSummary": "Patient presents with chest pain.", "medicalRecordSummaryStructured": { "pastMedicalConditions": [ "Hypertension" ], "pastMedicalConditionsCoded": [ { "code": { "code": "I10", "options": [ { "code": "I10", "score": 0.98 } ] }, "content": "Hypertension" } ], "vitalSigns": { "bloodPressure": "120/80" } }, "purpose": "primary", "specialty": "Cardiology", "updatedAt": "2026-02-20T10:35:00Z" } ], "total": 1 } } } }, "400": { "description": "Bad Request \u2014 invalid parameters, validation failures, or missing fields.", "content": { "application/json": { "examples": { "parameter_missing": { "summary": "Missing required field", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "name is required.", "param": "name", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "parameter_invalid": { "summary": "Invalid field value", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code.", "param": "idCountry", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "account_invalid": { "summary": "Invalid account", "value": { "error": { "type": "invalid_request_error", "code": "account_invalid", "message": "Account has no valid authId.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden \u2014 the API key is not allowed to perform this operation.", "content": { "application/json": { "examples": { "permission_denied": { "summary": "Caller lacks permission for this resource", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "You do not have permission to access this resource.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "permission_denied_role": { "summary": "API key's account role is not allowed this operation", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "Your API key is not allowed to create accounts. Account creation requires an institutional API key; this key is scoped to a doctor account.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the requested resource does not exist.", "content": { "application/json": { "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "No session scribe found for the given consultation ID.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "External service unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/cdss/alerts/{alert_id}/accept": { "post": { "tags": [ "CDSS" ], "summary": "Accept a CDSS alert", "description": "Record the doctor's decision to accept a clinical decision support alert. The accepted change is applied to the medical record asynchronously, so a success response means the decision was recorded, not that the record has already been updated.", "operationId": "api_cdss_alert_accept_v1_cdss_alerts__alert_id__accept_post", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "alert_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$", "description": "The alert `id` returned by the medical record documents endpoint.", "examples": [ "cfa_bXJkLWFiYy0xMjMfSUJVUFJPRkVO" ], "title": "Alert Id" }, "description": "The alert `id` returned by the medical record documents endpoint." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CdssDecisionResponse" }, "example": { "elementId": "IBUPROFEN", "id": "cfa_bXJkLWFiYy0xMjMfSUJVUFJPRkVO", "status": "accepted" } } } }, "400": { "description": "Bad Request \u2014 invalid parameters, validation failures, or missing fields.", "content": { "application/json": { "examples": { "parameter_missing": { "summary": "Missing required field", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "name is required.", "param": "name", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "parameter_invalid": { "summary": "Invalid field value", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code.", "param": "idCountry", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "account_invalid": { "summary": "Invalid account", "value": { "error": { "type": "invalid_request_error", "code": "account_invalid", "message": "Account has no valid authId.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden \u2014 the API key is not allowed to perform this operation.", "content": { "application/json": { "examples": { "permission_denied": { "summary": "Caller lacks permission for this resource", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "You do not have permission to access this resource.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "permission_denied_role": { "summary": "API key's account role is not allowed this operation", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "Your API key is not allowed to create accounts. Account creation requires an institutional API key; this key is scoped to a doctor account.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the requested resource does not exist.", "content": { "application/json": { "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "No session scribe found for the given consultation ID.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 resource already exists or is in a conflicting state.", "content": { "application/json": { "examples": { "resource_conflict": { "summary": "Resource conflict", "value": { "error": { "type": "invalid_request_error", "code": "resource_conflict", "message": "consultationInternalId is already in use by a different consultation.", "param": "consultationInternalId", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "External service unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/cdss/decisions": { "post": { "tags": [ "CDSS" ], "summary": "Record decisions for several CDSS alerts", "description": "Accept or reject several clinical decision support alerts in one call. Every alert is validated before any decision is recorded, so a batch containing an unusable alert changes nothing. Accepted changes are applied to the medical record asynchronously.", "operationId": "api_cdss_decisions_v1_cdss_decisions_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CdssDecisionsRequest" }, "example": { "decisions": [ { "decision": "accepted", "id": "cfa_bXJkLWFiYy0xMjMfSUJVUFJPRkVO" }, { "decision": "rejected", "id": "cfa_bXJkLWFiYy0xMjMfQVNQSVJJTg" } ] } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CdssDecisionsResponse" }, "example": { "decisions": [ { "elementId": "IBUPROFEN", "id": "cfa_bXJkLWFiYy0xMjMfSUJVUFJPRkVO", "status": "accepted" } ] } } } }, "400": { "description": "Bad Request \u2014 invalid parameters, validation failures, or missing fields.", "content": { "application/json": { "examples": { "parameter_missing": { "summary": "Missing required field", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "name is required.", "param": "name", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "parameter_invalid": { "summary": "Invalid field value", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code.", "param": "idCountry", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "account_invalid": { "summary": "Invalid account", "value": { "error": { "type": "invalid_request_error", "code": "account_invalid", "message": "Account has no valid authId.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden \u2014 the API key is not allowed to perform this operation.", "content": { "application/json": { "examples": { "permission_denied": { "summary": "Caller lacks permission for this resource", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "You do not have permission to access this resource.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "permission_denied_role": { "summary": "API key's account role is not allowed this operation", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "Your API key is not allowed to create accounts. Account creation requires an institutional API key; this key is scoped to a doctor account.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the requested resource does not exist.", "content": { "application/json": { "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "No session scribe found for the given consultation ID.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 resource already exists or is in a conflicting state.", "content": { "application/json": { "examples": { "resource_conflict": { "summary": "Resource conflict", "value": { "error": { "type": "invalid_request_error", "code": "resource_conflict", "message": "consultationInternalId is already in use by a different consultation.", "param": "consultationInternalId", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "External service unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/cdss/alerts/{alert_id}/reject": { "post": { "tags": [ "CDSS" ], "summary": "Reject a CDSS alert", "description": "Record the doctor's decision to reject a clinical decision support alert. The medical record is left unchanged.", "operationId": "api_cdss_alert_reject_v1_cdss_alerts__alert_id__reject_post", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "alert_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$", "description": "The alert `id` returned by the medical record documents endpoint.", "examples": [ "cfa_bXJkLWFiYy0xMjMfSUJVUFJPRkVO" ], "title": "Alert Id" }, "description": "The alert `id` returned by the medical record documents endpoint." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CdssDecisionResponse" }, "example": { "elementId": "IBUPROFEN", "id": "cfa_bXJkLWFiYy0xMjMfSUJVUFJPRkVO", "status": "accepted" } } } }, "400": { "description": "Bad Request \u2014 invalid parameters, validation failures, or missing fields.", "content": { "application/json": { "examples": { "parameter_missing": { "summary": "Missing required field", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "name is required.", "param": "name", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "parameter_invalid": { "summary": "Invalid field value", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code.", "param": "idCountry", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "account_invalid": { "summary": "Invalid account", "value": { "error": { "type": "invalid_request_error", "code": "account_invalid", "message": "Account has no valid authId.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden \u2014 the API key is not allowed to perform this operation.", "content": { "application/json": { "examples": { "permission_denied": { "summary": "Caller lacks permission for this resource", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "You do not have permission to access this resource.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "permission_denied_role": { "summary": "API key's account role is not allowed this operation", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "Your API key is not allowed to create accounts. Account creation requires an institutional API key; this key is scoped to a doctor account.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the requested resource does not exist.", "content": { "application/json": { "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "No session scribe found for the given consultation ID.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 resource already exists or is in a conflicting state.", "content": { "application/json": { "examples": { "resource_conflict": { "summary": "Resource conflict", "value": { "error": { "type": "invalid_request_error", "code": "resource_conflict", "message": "consultationInternalId is already in use by a different consultation.", "param": "consultationInternalId", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "External service unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/scribe-session-configurations": { "get": { "tags": [ "Scribe Session Configurations" ], "summary": "List Scribe Session Configurations", "description": "List all scribe session configurations for the authenticated account.", "operationId": "api_scribe_session_configurations_listed_v1_scribe_session_configurations_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScribeSessionConfigListResponse" }, "example": { "items": [ { "id": "ssc_a1b2c3d4e5f6g7h8", "name": "Cardiology Consultation" }, { "id": "ssc_i9j0k1l2m3n4o5p6", "name": "General Medicine" } ], "limit": 20, "page": 1, "total": 2, "totalPages": 1 } } } }, "400": { "description": "Bad Request \u2014 invalid parameters, validation failures, or missing fields.", "content": { "application/json": { "examples": { "parameter_missing": { "summary": "Missing required field", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "name is required.", "param": "name", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "parameter_invalid": { "summary": "Invalid field value", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code.", "param": "idCountry", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "account_invalid": { "summary": "Invalid account", "value": { "error": { "type": "invalid_request_error", "code": "account_invalid", "message": "Account has no valid authId.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "External service unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/medical-record-configurations": { "post": { "tags": [ "Medical Record Configurations" ], "summary": "Create a Smart Template", "description": "Register a Smart Template (medical record configuration). Idempotent on content hash: identical configurations for the same account return the existing id with `created: false`.", "operationId": "api_medical_record_configuration_create_v1_medical_record_configurations_post", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMedicalRecordConfigurationRequest" }, "example": { "configuration": { "chiefComplaint": { "instructionSet": { "telepatiaPromptId": "CHIEF_COMPLAINT" }, "schema": { "instructions": "Patient's chief complaint.", "type": "string" } }, "vitals": { "instructionSet": { "telepatiaPromptId": "VITAL_SIGNS" }, "schema": { "instructions": "Vital signs.", "properties": { "heartRate": { "instructions": "Heart rate in bpm.", "type": "integer" } }, "type": "object" } } }, "name": "Cardiology intake" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMedicalRecordConfigurationResponse" }, "example": { "created": true, "createdAt": "2026-04-20T14:30:00Z", "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "id": "mrc_a1b2c3d4e5f6g7h8", "name": "Cardiology intake" } } } }, "400": { "description": "Bad Request \u2014 invalid parameters, validation failures, or missing fields.", "content": { "application/json": { "examples": { "parameter_missing": { "summary": "Missing required field", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "name is required.", "param": "name", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "parameter_invalid": { "summary": "Invalid field value", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code.", "param": "idCountry", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "account_invalid": { "summary": "Invalid account", "value": { "error": { "type": "invalid_request_error", "code": "account_invalid", "message": "Account has no valid authId.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 resource already exists or is in a conflicting state.", "content": { "application/json": { "examples": { "resource_conflict": { "summary": "Resource conflict", "value": { "error": { "type": "invalid_request_error", "code": "resource_conflict", "message": "consultationInternalId is already in use by a different consultation.", "param": "consultationInternalId", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Failed to create medical record configuration", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "Failed to create medical record configuration.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": [ "Medical Record Configurations" ], "summary": "List Smart Templates", "description": "List Smart Templates visible to the authenticated caller, paginated.", "operationId": "api_medical_record_configuration_list_v1_medical_record_configurations_get", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Page number (1-based).", "default": 1, "title": "Page" }, "description": "Page number (1-based)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Number of items per page.", "default": 20, "title": "Limit" }, "description": "Number of items per page." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/MrcStatusFilter" }, { "type": "null" } ], "description": "Lifecycle-status view. Omit for the default non-deleted list; `deleted` returns only soft-deleted templates (audit view); `all` returns non-deleted + deleted.", "title": "Status" }, "description": "Lifecycle-status view. Omit for the default non-deleted list; `deleted` returns only soft-deleted templates (audit view); `all` returns non-deleted + deleted.", "example": "deleted" }, { "name": "workflow", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/MrcWorkflow" }, { "type": "null" } ], "description": "Product discriminator view. Omit to list every value's templates. `defaultOutpatient`, `inpatient`, and `emergencyRoom` filter Scribe templates by clinical care setting; `reportDictation` returns only dictation report templates and `historySummary` only patient-history summarizers.", "title": "Workflow" }, "description": "Product discriminator view. Omit to list every value's templates. `defaultOutpatient`, `inpatient`, and `emergencyRoom` filter Scribe templates by clinical care setting; `reportDictation` returns only dictation report templates and `historySummary` only patient-history summarizers.", "example": "defaultOutpatient" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MrcListResponse" }, "example": { "items": [ { "createdAt": "2026-04-20T12:34:56Z", "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "id": "mrc_a1b2c3d4e5f6g7h8", "name": "Cardiology intake", "specialties": [ "cardiology" ], "status": "active" } ], "limit": 20, "page": 1, "total": 1, "totalPages": 1 } } } }, "400": { "description": "Bad Request \u2014 invalid parameters, validation failures, or missing fields.", "content": { "application/json": { "examples": { "parameter_missing": { "summary": "Missing required field", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "name is required.", "param": "name", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "parameter_invalid": { "summary": "Invalid field value", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code.", "param": "idCountry", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "account_invalid": { "summary": "Invalid account", "value": { "error": { "type": "invalid_request_error", "code": "account_invalid", "message": "Account has no valid authId.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "428": { "description": "Precondition Required", "content": { "application/json": { "examples": { "cdss_review_required": { "summary": "Doctor has pending CDSS suggestions awaiting review", "value": { "error": { "type": "invalid_request_error", "code": "cdss_review_required", "message": "This doctor has 1 pending CDSS suggestion awaiting review from the last 7 days. The API is blocked by your institution until the suggestions are reviewed. Open the consultation(s) to accept or reject them: https://scribe.telepatia.ai/consultations/session-abc-123.", "details": { "pendingConsultations": [ { "sessionId": "session-abc-123", "url": "https://scribe.telepatia.ai/consultations/session-abc-123" } ] }, "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "External service unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/medical-record-configurations/{configuration_id}": { "get": { "tags": [ "Medical Record Configurations" ], "summary": "Get a Smart Template by ID", "description": "Get a Smart Template by its public identifier.", "operationId": "api_medical_record_configuration_get_v1_medical_record_configurations__configuration_id__get", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "configuration_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Configuration Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MrcDetailResponse" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the requested resource does not exist.", "content": { "application/json": { "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "No session scribe found for the given consultation ID.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "External service unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Medical Record Configurations" ], "summary": "Delete a Smart Template", "description": "Soft-deletes a Smart Template by its public identifier. The template drops from the default list; historical consultations that referenced it are unaffected. Blocked with a 409 while a linked scribe session is still processing.", "operationId": "api_medical_record_configuration_delete_v1_medical_record_configurations__configuration_id__delete", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "configuration_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Configuration Id" } } ], "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Bad Request \u2014 invalid parameters, validation failures, or missing fields.", "content": { "application/json": { "examples": { "parameter_missing": { "summary": "Missing required field", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "name is required.", "param": "name", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "parameter_invalid": { "summary": "Invalid field value", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code.", "param": "idCountry", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "account_invalid": { "summary": "Invalid account", "value": { "error": { "type": "invalid_request_error", "code": "account_invalid", "message": "Account has no valid authId.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden \u2014 the API key is not allowed to perform this operation.", "content": { "application/json": { "examples": { "permission_denied": { "summary": "Caller lacks permission for this resource", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "You do not have permission to access this resource.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "permission_denied_role": { "summary": "API key's account role is not allowed this operation", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "Your API key is not allowed to create accounts. Account creation requires an institutional API key; this key is scoped to a doctor account.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the requested resource does not exist.", "content": { "application/json": { "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "No session scribe found for the given consultation ID.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 resource already exists or is in a conflicting state.", "content": { "application/json": { "examples": { "resource_conflict": { "summary": "Resource conflict", "value": { "error": { "type": "invalid_request_error", "code": "resource_conflict", "message": "consultationInternalId is already in use by a different consultation.", "param": "consultationInternalId", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "External service unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/appointments": { "post": { "tags": [ "Appointments" ], "summary": "Create an appointment", "description": "Create a scheduled consultation (idempotent on `consultationInternalId`).\n\n**Required:** `consultationInternalId`, `start`, `end`, plus exactly one patient reference: `patientId`, `internalCode`, or the full inline identity (`name` + `idCountry` + `idType` + `idValue`).\n\n**Optional:** the remaining scheduling fields (`minutesDuration`, `serviceType`, `appointmentType`, `reason`, `description`) and a template (`medicalRecordConfigurationId`) that seeds the consultation context before the visit.\n\nReturns the appointment with its stable public id (`apt_...`).", "operationId": "api_appointment_create_v1_appointments_post", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentCreateRequest" }, "example": { "consultationInternalId": "CONSULT-12345", "end": "2026-09-01T14:30:00.000Z", "idCountry": "COLOMBIA", "idType": "CC", "idValue": "1024567890", "medicalRecordConfigurationId": "mrc_a1b2c3d4e5f6g7h8", "name": "John Doe", "reason": "Follow-up", "scribeSessionModality": "IN_PERSON", "serviceType": "cardiology", "start": "2026-09-01T14:00:00.000Z" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentResponse" }, "example": { "appointmentType": "follow-up", "consultationInternalId": "CONSULT-12345", "createdAt": "2026-08-28T12:00:00.000Z", "end": "2026-09-01T14:30:00.000Z", "id": "apt_a1b2c3d4e5f6g7h8", "minutesDuration": 30, "reason": "Follow-up", "serviceType": "cardiology", "start": "2026-09-01T14:00:00.000Z", "status": "booked" } } } }, "400": { "description": "Bad Request \u2014 invalid parameters, validation failures, or missing fields.", "content": { "application/json": { "examples": { "parameter_missing": { "summary": "Missing required field", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "name is required.", "param": "name", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "parameter_invalid": { "summary": "Invalid field value", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code.", "param": "idCountry", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "account_invalid": { "summary": "Invalid account", "value": { "error": { "type": "invalid_request_error", "code": "account_invalid", "message": "Account has no valid authId.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden \u2014 the API key is not allowed to perform this operation.", "content": { "application/json": { "examples": { "permission_denied": { "summary": "Caller lacks permission for this resource", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "You do not have permission to access this resource.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "permission_denied_role": { "summary": "API key's account role is not allowed this operation", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "Your API key is not allowed to create accounts. Account creation requires an institutional API key; this key is scoped to a doctor account.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the requested resource does not exist.", "content": { "application/json": { "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "No session scribe found for the given consultation ID.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 resource already exists or is in a conflicting state.", "content": { "application/json": { "examples": { "resource_conflict": { "summary": "Resource conflict", "value": { "error": { "type": "invalid_request_error", "code": "resource_conflict", "message": "consultationInternalId is already in use by a different consultation.", "param": "consultationInternalId", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "External service unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": [ "Appointments" ], "summary": "List appointments (agenda)", "description": "List the appointments visible to the authenticated caller, tenant-scoped by role, sorted by start time. Filter by a start-time range and status, paginated.", "operationId": "api_appointment_list_v1_appointments_get", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "startFrom", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 lower bound on start (inclusive).", "title": "Startfrom" }, "description": "ISO-8601 lower bound on start (inclusive)." }, { "name": "startTo", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 upper bound on start (inclusive).", "title": "Startto" }, "description": "ISO-8601 upper bound on start (inclusive)." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/AppointmentStatus" } }, { "type": "null" } ], "description": "Filter by one or more statuses (repeatable).", "title": "Status" }, "description": "Filter by one or more statuses (repeatable)." }, { "name": "consultationInternalId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to the booking that carries this consultation id.", "title": "Consultationinternalid" }, "description": "Filter to the booking that carries this consultation id." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Page number (1-based).", "default": 1, "title": "Page" }, "description": "Page number (1-based)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Number of items per page.", "default": 20, "title": "Limit" }, "description": "Number of items per page." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentListResponse" } } } }, "400": { "description": "Bad Request \u2014 invalid parameters, validation failures, or missing fields.", "content": { "application/json": { "examples": { "parameter_missing": { "summary": "Missing required field", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "name is required.", "param": "name", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "parameter_invalid": { "summary": "Invalid field value", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code.", "param": "idCountry", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "account_invalid": { "summary": "Invalid account", "value": { "error": { "type": "invalid_request_error", "code": "account_invalid", "message": "Account has no valid authId.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "External service unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/appointments/{appointment_id}": { "get": { "tags": [ "Appointments" ], "summary": "Get an appointment by id", "description": "Get one appointment by its public id (apt_...) or the consultationInternalId you sent when creating it. Returns 404 if no appointment with that id is visible to your key.", "operationId": "api_appointment_get_v1_appointments__appointment_id__get", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "appointment_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Appointment Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentResponse" }, "example": { "appointmentType": "follow-up", "consultationInternalId": "CONSULT-12345", "createdAt": "2026-08-28T12:00:00.000Z", "end": "2026-09-01T14:30:00.000Z", "id": "apt_a1b2c3d4e5f6g7h8", "minutesDuration": 30, "reason": "Follow-up", "serviceType": "cardiology", "start": "2026-09-01T14:00:00.000Z", "status": "booked" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the requested resource does not exist.", "content": { "application/json": { "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "No session scribe found for the given consultation ID.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "External service unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Appointments" ], "summary": "Update an appointment", "description": "Cancel a booking or mark it no-show, or repair a missed session link, by its public id (apt_...) or the consultationInternalId you sent at create. `status` accepts only `cancelled` or `noshow` (a booking is marked fulfilled only by the server when its session is created). `scribeSessionId` attaches the session whose id did not match the booking at create time, and marks it fulfilled. Provide exactly one of the two.", "operationId": "api_appointment_update_v1_appointments__appointment_id__patch", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "appointment_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Appointment Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentUpdateRequest" }, "example": { "status": "cancelled" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentResponse" }, "example": { "appointmentType": "follow-up", "consultationInternalId": "CONSULT-12345", "createdAt": "2026-08-28T12:00:00.000Z", "end": "2026-09-01T14:30:00.000Z", "id": "apt_a1b2c3d4e5f6g7h8", "minutesDuration": 30, "reason": "Follow-up", "serviceType": "cardiology", "start": "2026-09-01T14:00:00.000Z", "status": "booked" } } } }, "400": { "description": "Bad Request \u2014 invalid parameters, validation failures, or missing fields.", "content": { "application/json": { "examples": { "parameter_missing": { "summary": "Missing required field", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "name is required.", "param": "name", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "parameter_invalid": { "summary": "Invalid field value", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code.", "param": "idCountry", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "account_invalid": { "summary": "Invalid account", "value": { "error": { "type": "invalid_request_error", "code": "account_invalid", "message": "Account has no valid authId.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden \u2014 the API key is not allowed to perform this operation.", "content": { "application/json": { "examples": { "permission_denied": { "summary": "Caller lacks permission for this resource", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "You do not have permission to access this resource.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "permission_denied_role": { "summary": "API key's account role is not allowed this operation", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "Your API key is not allowed to create accounts. Account creation requires an institutional API key; this key is scoped to a doctor account.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the requested resource does not exist.", "content": { "application/json": { "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "No session scribe found for the given consultation ID.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 resource already exists or is in a conflicting state.", "content": { "application/json": { "examples": { "resource_conflict": { "summary": "Resource conflict", "value": { "error": { "type": "invalid_request_error", "code": "resource_conflict", "message": "consultationInternalId is already in use by a different consultation.", "param": "consultationInternalId", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "External service unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/patients": { "post": { "tags": [ "Patients" ], "summary": "Create a patient", "description": "Create a patient from the same identity fields used by set-consultation-context. Returns the patient with its stable public id.", "operationId": "api_patient_create_v1_patients_post", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientCreateRequest" }, "example": { "idCountry": "COLOMBIA", "idType": "CC", "idValue": "1024567890", "internalCode": "EMR-12345", "name": "John Doe" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientResponse" }, "example": { "createdAt": "2026-07-01T12:00:00.000Z", "id": "sp_a1b2c3d4e5f6g7h8", "idCountry": "COLOMBIA", "idType": "CC", "idValue": "1024567890", "internalCode": "EMR-12345", "name": "John Doe" } } } }, "400": { "description": "Bad Request \u2014 invalid parameters, validation failures, or missing fields.", "content": { "application/json": { "examples": { "parameter_missing": { "summary": "Missing required field", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "name is required.", "param": "name", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "parameter_invalid": { "summary": "Invalid field value", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code.", "param": "idCountry", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "account_invalid": { "summary": "Invalid account", "value": { "error": { "type": "invalid_request_error", "code": "account_invalid", "message": "Account has no valid authId.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 resource already exists or is in a conflicting state.", "content": { "application/json": { "examples": { "resource_conflict": { "summary": "Resource conflict", "value": { "error": { "type": "invalid_request_error", "code": "resource_conflict", "message": "consultationInternalId is already in use by a different consultation.", "param": "consultationInternalId", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "External service unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": [ "Patients" ], "summary": "List patients", "description": "List patients visible to the authenticated caller, paginated.", "operationId": "api_patient_list_v1_patients_get", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Page number (1-based).", "default": 1, "title": "Page" }, "description": "Page number (1-based)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Number of items per page.", "default": 20, "title": "Limit" }, "description": "Number of items per page." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientListResponse" } } } }, "400": { "description": "Bad Request \u2014 invalid parameters, validation failures, or missing fields.", "content": { "application/json": { "examples": { "parameter_missing": { "summary": "Missing required field", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "name is required.", "param": "name", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "parameter_invalid": { "summary": "Invalid field value", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code.", "param": "idCountry", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "account_invalid": { "summary": "Invalid account", "value": { "error": { "type": "invalid_request_error", "code": "account_invalid", "message": "Account has no valid authId.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "External service unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/patients/{patient_id}": { "get": { "tags": [ "Patients" ], "summary": "Get a patient by ID", "description": "Get a patient by its public identifier (sp_...) or by the internalCode you set for your institution.", "operationId": "api_patient_get_v1_patients__patient_id__get", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "patient_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Patient Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientResponse" }, "example": { "createdAt": "2026-07-01T12:00:00.000Z", "id": "sp_a1b2c3d4e5f6g7h8", "idCountry": "COLOMBIA", "idType": "CC", "idValue": "1024567890", "internalCode": "EMR-12345", "name": "John Doe" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the requested resource does not exist.", "content": { "application/json": { "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "No session scribe found for the given consultation ID.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "External service unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Patients" ], "summary": "Update a patient", "description": "Update a patient's name or internalCode by its public id (sp_...) or the internalCode you set for your institution. The national identity is not editable here. Omit a field to leave it unchanged.", "operationId": "api_patient_update_v1_patients__patient_id__patch", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "patient_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Patient Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientUpdateRequest" }, "example": { "internalCode": "EMR-99999", "name": "Jane Doe" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientResponse" }, "example": { "createdAt": "2026-07-01T12:00:00.000Z", "id": "sp_a1b2c3d4e5f6g7h8", "idCountry": "COLOMBIA", "idType": "CC", "idValue": "1024567890", "internalCode": "EMR-12345", "name": "John Doe" } } } }, "400": { "description": "Bad Request \u2014 invalid parameters, validation failures, or missing fields.", "content": { "application/json": { "examples": { "parameter_missing": { "summary": "Missing required field", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "name is required.", "param": "name", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "parameter_invalid": { "summary": "Invalid field value", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code.", "param": "idCountry", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "account_invalid": { "summary": "Invalid account", "value": { "error": { "type": "invalid_request_error", "code": "account_invalid", "message": "Account has no valid authId.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden \u2014 the API key is not allowed to perform this operation.", "content": { "application/json": { "examples": { "permission_denied": { "summary": "Caller lacks permission for this resource", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "You do not have permission to access this resource.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "permission_denied_role": { "summary": "API key's account role is not allowed this operation", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "Your API key is not allowed to create accounts. Account creation requires an institutional API key; this key is scoped to a doctor account.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the requested resource does not exist.", "content": { "application/json": { "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "No session scribe found for the given consultation ID.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 resource already exists or is in a conflicting state.", "content": { "application/json": { "examples": { "resource_conflict": { "summary": "Resource conflict", "value": { "error": { "type": "invalid_request_error", "code": "resource_conflict", "message": "consultationInternalId is already in use by a different consultation.", "param": "consultationInternalId", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "External service unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Patients" ], "summary": "Delete a patient", "description": "Soft-delete a patient by its public id (sp_...) or by the internalCode you set for your institution. For right-to-erasure requests. Returns 404 if no patient with that id is visible to your key.", "operationId": "api_patient_delete_v1_patients__patient_id__delete", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "patient_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Patient Id" } } ], "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden \u2014 the API key is not allowed to perform this operation.", "content": { "application/json": { "examples": { "permission_denied": { "summary": "Caller lacks permission for this resource", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "You do not have permission to access this resource.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "permission_denied_role": { "summary": "API key's account role is not allowed this operation", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "Your API key is not allowed to create accounts. Account creation requires an institutional API key; this key is scoped to a doctor account.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the requested resource does not exist.", "content": { "application/json": { "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "No session scribe found for the given consultation ID.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "External service unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/patients/{patient_id}/scribe-sessions": { "get": { "tags": [ "Patients" ], "summary": "List a patient's scribe sessions", "description": "List the scribe sessions for a patient, paginated. The patient id can be the public id (sp_...) or the internalCode you set for your institution.", "operationId": "api_patient_scribe_sessions_list_v1_patients__patient_id__scribe_sessions_get", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "patient_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Patient Id" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Page number (1-based).", "default": 1, "title": "Page" }, "description": "Page number (1-based)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Number of items per page.", "default": 20, "title": "Limit" }, "description": "Number of items per page." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientSessionListResponse" }, "example": { "hasMore": false, "items": [ { "completedAt": "2026-02-20T10:30:00Z", "consultationInternalId": "CONSULT-12345", "createdAt": "2026-02-20T10:00:00Z", "id": "ss_a1b2c3d4e5f6g7h8", "patientName": "John Doe", "scribeSessionModality": "IN_PERSON", "specialty": "Cardiology", "status": "completed" } ], "limit": 20, "page": 1, "total": 1, "totalPages": 1 } } } }, "400": { "description": "Bad Request \u2014 invalid parameters, validation failures, or missing fields.", "content": { "application/json": { "examples": { "parameter_missing": { "summary": "Missing required field", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "name is required.", "param": "name", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "parameter_invalid": { "summary": "Invalid field value", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code.", "param": "idCountry", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "account_invalid": { "summary": "Invalid account", "value": { "error": { "type": "invalid_request_error", "code": "account_invalid", "message": "Account has no valid authId.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the requested resource does not exist.", "content": { "application/json": { "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "No session scribe found for the given consultation ID.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "External service unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/scribe-sessions/{id}/audit": { "get": { "tags": [ "Audits" ], "summary": "Get a session's audit", "description": "Get the clinical-quality audit for a scribe session.\n\nReturns the weighted `score` (0..1), the qualitative `grade`, the per-section\nbreakdown, and the rubric the audit was scored against. Returns `404` when the\nsession has no audit \u2014 audit is disabled for it, or has not run yet.", "operationId": "api_session_audit_get_v1_scribe_sessions__id__audit_get", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$", "description": "The session to look up \u2014 either your consultationInternalId, or the session id (ss_...) the API returns.", "examples": [ "CONSULT-12345", "ss_sa98vgqyra91q5b8" ], "title": "Id" }, "description": "The session to look up \u2014 either your consultationInternalId, or the session id (ss_...) the API returns." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditResponse" }, "example": { "configuration": { "id": "ac_9f8e7d6c5b4a3210", "name": "General medicine v2", "version": "1.2" }, "createdAt": "2026-02-20T10:35:00Z", "grade": "ACEPTABLE", "id": "au_a1b2c3d4e5f6g7h8", "origin": "scribe", "reviewStatus": "reviewed", "score": 0.82, "sections": [ { "label": "Anamnesis", "name": "ANAMNESIS", "score": 0.9 }, { "label": "Physical exam", "name": "PHYSICAL_EXAM", "score": 0.75 } ] } } } }, "400": { "description": "Bad Request \u2014 invalid parameters, validation failures, or missing fields.", "content": { "application/json": { "examples": { "parameter_missing": { "summary": "Missing required field", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "name is required.", "param": "name", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "parameter_invalid": { "summary": "Invalid field value", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code.", "param": "idCountry", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "account_invalid": { "summary": "Invalid account", "value": { "error": { "type": "invalid_request_error", "code": "account_invalid", "message": "Account has no valid authId.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden \u2014 the API key is not allowed to perform this operation.", "content": { "application/json": { "examples": { "permission_denied": { "summary": "Caller lacks permission for this resource", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "You do not have permission to access this resource.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "permission_denied_role": { "summary": "API key's account role is not allowed this operation", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "Your API key is not allowed to create accounts. Account creation requires an institutional API key; this key is scoped to a doctor account.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the requested resource does not exist.", "content": { "application/json": { "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "No session scribe found for the given consultation ID.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "External service unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/scribe-sessions/live": { "post": { "tags": [ "Scribe Sessions" ], "summary": "Start a live consultation audio session", "description": "Create a consultation and receive a WebSocket URL to stream the audio to. Body is `application/json` with the same metadata as the batch endpoint (`consultation`, `template`, `patient`, `context`); the `audio` block is not accepted. Stream to `live.url` as described on that field, then finish through the webhook + document GET contract shared with the batch endpoint. Retrying with the same consultation id while recording returns the same session with a fresh URL; finished consultations return 409.", "operationId": "api_scribe_session_live_init_v1_scribe_sessions_live_post", "requestBody": { "content": { "application/json": { "schema": { "properties": { "consultation": { "$ref": "#/components/schemas/ConsultationInput" }, "template": { "$ref": "#/components/schemas/TemplateInput" }, "patient": { "$ref": "#/components/schemas/PatientInput" }, "context": { "anyOf": [ { "$ref": "#/components/schemas/ContextInput" }, { "type": "null" } ] } }, "type": "object", "required": [ "consultation", "template", "patient" ], "title": "IngestScribeSessionMetadata", "description": "The consultation metadata: the multipart ``metadata`` part, or the JSON body.", "example": { "consultation": { "id": "CONSULT-12345", "modality": "IN_PERSON" }, "template": { "id": "mrc_a1b2c3d4e5f6g7h8" }, "patient": { "id": "sp_a1b2c3d4e5f6g7h8" }, "context": { "notes": "Patient reports headache since Monday.", "pastMedicalHistory": "Hypertension diagnosed 2020." } } }, "example": { "consultation": { "id": "CONSULT-12345", "modality": "IN_PERSON" }, "template": { "id": "mrc_a1b2c3d4e5f6g7h8" }, "patient": { "id": "sp_a1b2c3d4e5f6g7h8" }, "context": { "notes": "Patient reports headache since Monday.", "pastMedicalHistory": "Hypertension diagnosed 2020." } } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveScribeSessionResponse" } } } }, "400": { "description": "Bad Request \u2014 invalid parameters, validation failures, or missing fields.", "content": { "application/json": { "examples": { "parameter_missing": { "summary": "Missing required field", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "name is required.", "param": "name", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "parameter_invalid": { "summary": "Invalid field value", "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code.", "param": "idCountry", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "account_invalid": { "summary": "Invalid account", "value": { "error": { "type": "invalid_request_error", "code": "account_invalid", "message": "Account has no valid authId.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid API key.", "content": { "application/json": { "examples": { "authentication_required": { "summary": "Invalid or missing API key", "value": { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden \u2014 the API key is not allowed to perform this operation.", "content": { "application/json": { "examples": { "permission_denied": { "summary": "Caller lacks permission for this resource", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "You do not have permission to access this resource.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } }, "permission_denied_role": { "summary": "API key's account role is not allowed this operation", "value": { "error": { "type": "permission_error", "code": "permission_denied", "message": "Your API key is not allowed to create accounts. Account creation requires an institutional API key; this key is scoped to a doctor account.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found \u2014 the requested resource does not exist.", "content": { "application/json": { "examples": { "resource_not_found": { "summary": "Resource not found", "value": { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "No session scribe found for the given consultation ID.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict \u2014 resource already exists or is in a conflicting state.", "content": { "application/json": { "examples": { "resource_conflict": { "summary": "Resource conflict", "value": { "error": { "type": "invalid_request_error", "code": "resource_conflict", "message": "consultationInternalId is already in use by a different consultation.", "param": "consultationInternalId", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Content Too Large", "content": { "application/json": { "examples": { "request_too_large": { "summary": "Uploaded file exceeds the maximum size", "value": { "error": { "type": "invalid_request_error", "code": "request_too_large", "message": "The audio file exceeds the maximum supported size.", "param": "audio_file", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable \u2014 an external dependency is down.", "content": { "application/json": { "examples": { "service_unavailable": { "summary": "External service unavailable", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Please try again later.", "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } } }, "components": { "schemas": { "AccountSummary": { "properties": { "id": { "type": "string", "title": "Id", "description": "Account publicId (acc_*).", "examples": [ "acc_a1b2c3d4e5f6g7h8" ] }, "nameFull": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namefull", "description": "Account full name.", "examples": [ "Dr. Juan P\u00e9rez" ] }, "email": { "type": "string", "title": "Email", "examples": [ "dr.juan@clinica.com" ] }, "disabledAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Disabledat", "description": "When the account was disabled; null means active.", "examples": [ null ] }, "roles": { "items": { "type": "string" }, "type": "array", "title": "Roles", "description": "Account roles, e.g. doctor or institutional.", "examples": [ [ "doctor" ] ] } }, "type": "object", "required": [ "id", "email" ], "title": "AccountSummary", "description": "Summary of a single account in a list response." }, "ApiKeyConfig": { "properties": { "validForDays": { "type": "integer", "maximum": 365.0, "minimum": 1.0, "title": "Validfordays", "description": "API key lifetime in days (1\u2013365). Defaults to 365 (1 year).", "default": 365, "examples": [ 365 ] } }, "type": "object", "title": "ApiKeyConfig", "description": "Configuration for the API key minted with the new account." }, "ApiKeyMetadata": { "properties": { "id": { "type": "string", "title": "Id", "description": "API key public identifier (ak_*).", "examples": [ "ak_a1b2c3d4e5f6g7h8" ] }, "accountId": { "type": "string", "title": "Accountid", "description": "publicId (acc_*) of the account that owns the key.", "examples": [ "acc_a1b2c3d4e5f6g7h8" ] }, "prefix": { "type": "string", "title": "Prefix", "description": "Display-safe hint of the raw key ('...').", "examples": [ "sk_prod_aB3x...zzzz" ] }, "status": { "type": "string", "title": "Status", "description": "Effective lifecycle status, computed like auth: 'active', 'revoked', or 'expired' (a non-revoked key past its expiresAt).", "examples": [ "active" ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Revocation reason; null unless the key is revoked.", "examples": [ "rotated" ] }, "createdAt": { "type": "string", "title": "Createdat", "examples": [ "2024-01-15T10:30:00Z" ] }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expiresat", "description": "Expiry timestamp; null when the key never expires.", "examples": [ "2025-01-15T10:30:00Z" ] } }, "type": "object", "required": [ "id", "accountId", "prefix", "status", "createdAt" ], "title": "ApiKeyMetadata", "description": "Metadata for a single API key. The raw secret is never exposed." }, "AppointmentCreateRequest": { "properties": { "consultationInternalId": { "type": "string", "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]{1,128}$", "title": "Consultationinternalid", "description": "Your own consultation id. The booking join key: the consultation that fulfils this appointment carries the same id.", "examples": [ "CONSULT-12345" ] }, "name": { "anyOf": [ { "type": "string", "maxLength": 500, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "Patient full name. Part of the inline identity. Provide the full inline identity (name + idCountry + idType + idValue), or reference an existing patient with patientId or internalCode: exactly one of the three is required.", "examples": [ "John Doe" ] }, "idCountry": { "anyOf": [ { "$ref": "#/components/schemas/IdCountry" }, { "type": "null" } ], "description": "Patient document country. Part of the inline identity (see `name`).", "examples": [ "CO" ] }, "idType": { "anyOf": [ { "$ref": "#/components/schemas/IdType" }, { "type": "null" } ], "description": "Patient document type. Part of the inline identity (see `name`).", "examples": [ "CC" ] }, "idValue": { "anyOf": [ { "type": "string", "maxLength": 50, "minLength": 1 }, { "type": "null" } ], "title": "Idvalue", "description": "Patient document number. Part of the inline identity (see `name`).", "examples": [ "1024567890" ] }, "patientId": { "anyOf": [ { "type": "string", "pattern": "^sp_[a-z0-9]{16}$" }, { "type": "null" } ], "title": "Patientid", "description": "Public id of an existing patient (sp_...). One of the three patient references (exactly one required): patientId, internalCode, or the inline identity.", "examples": [ "sp_a1b2c3d4e5f6g7h8" ] }, "internalCode": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1 }, { "type": "null" } ], "title": "Internalcode", "description": "Your own patient code, unique per institution. Looks up an existing patient; when none matches, the inline identity creates one. One of the three patient references (exactly one required).", "examples": [ "MRN-000123" ] }, "doctorId": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1 }, { "type": "null" } ], "title": "Doctorid", "description": "The doctor whose agenda this booking joins: an account publicId (acc_...) or your own internalCode for that account. Omit it to book into the calling key's own agenda. Naming another account requires an institutional key; a doctor key always books for itself.", "examples": [ "acc_a1b2c3d4e5f6g7h8" ] }, "start": { "type": "string", "maxLength": 64, "title": "Start", "description": "ISO-8601 start. Required.", "examples": [ "2026-09-01T14:00:00.000Z" ] }, "end": { "type": "string", "maxLength": 64, "title": "End", "description": "ISO-8601 end. Required.", "examples": [ "2026-09-01T14:30:00.000Z" ] }, "minutesDuration": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Minutesduration", "description": "Duration in minutes.", "examples": [ 30 ] }, "serviceType": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "title": "Servicetype", "examples": [ "cardiology" ] }, "appointmentType": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "title": "Appointmenttype", "examples": [ "follow-up" ] }, "reason": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Reason", "examples": [ "Follow-up" ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Description", "examples": [ "Routine check" ] }, "medicalRecordConfigurationId": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Medicalrecordconfigurationid", "description": "Public id of a medical record configuration (mrc_...). When present, the consultation context is seeded.", "examples": [ "mrc_a1b2c3d4e5f6g7h8" ] }, "scribeSessionModality": { "anyOf": [ { "$ref": "#/components/schemas/ScribeSessionModality" }, { "type": "null" } ], "examples": [ "IN_PERSON" ] }, "notes": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ], "title": "Notes", "examples": [ "Patient reports headache" ] }, "pastMedicalHistory": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ], "title": "Pastmedicalhistory", "examples": [ "Hypertension" ] } }, "type": "object", "required": [ "consultationInternalId", "start", "end" ], "title": "AppointmentCreateRequest", "description": "Request body for creating (idempotent upsert) an appointment.\n\nThe patient identity mirrors set-consultation-context: reference an existing\npatient by `patientId` (sp_) or `internalCode`, or send the inline identity\nto create one. Send a template (`medicalRecordConfigurationId`) to also seed the\nconsultation context so it is ready before the visit.", "examples": [ { "consultationInternalId": "CONSULT-12345", "end": "2026-09-01T14:30:00.000Z", "idCountry": "COLOMBIA", "idType": "CC", "idValue": "1024567890", "medicalRecordConfigurationId": "mrc_a1b2c3d4e5f6g7h8", "name": "John Doe", "reason": "Follow-up", "scribeSessionModality": "IN_PERSON", "serviceType": "cardiology", "start": "2026-09-01T14:00:00.000Z" }, { "consultationInternalId": "CONSULT-12345", "end": "2026-09-01T14:30:00.000Z", "medicalRecordConfigurationId": "mrc_a1b2c3d4e5f6g7h8", "patientId": "sp_a1b2c3d4e5f6g7h8", "start": "2026-09-01T14:00:00.000Z" }, { "consultationInternalId": "CONSULT-12345", "end": "2026-09-01T14:30:00.000Z", "internalCode": "MRN-000123", "medicalRecordConfigurationId": "mrc_a1b2c3d4e5f6g7h8", "start": "2026-09-01T14:00:00.000Z" }, { "consultationInternalId": "CONSULT-12345", "doctorId": "acc_a1b2c3d4e5f6g7h8", "end": "2026-09-01T14:30:00.000Z", "patientId": "sp_a1b2c3d4e5f6g7h8", "start": "2026-09-01T14:00:00.000Z" } ] }, "AppointmentListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/AppointmentResponse" }, "type": "array", "title": "Items", "description": "Page of appointments." }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total", "description": "Total appointments matching the filter (null on later pages)." }, "page": { "type": "integer", "title": "Page", "description": "Current page number (1-based)." }, "limit": { "type": "integer", "title": "Limit", "description": "Number of items per page." }, "totalPages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Totalpages", "description": "Total number of pages (null when the total is unknown)." }, "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Whether another page likely exists (accurate on every page)." } }, "type": "object", "required": [ "items", "page", "limit", "hasMore" ], "title": "AppointmentListResponse", "description": "Paginated list of appointments (the agenda)." }, "AppointmentResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Stable public identifier.", "examples": [ "apt_a1b2c3d4e5f6g7h8" ] }, "consultationInternalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Consultationinternalid", "examples": [ "CONSULT-12345" ] }, "status": { "type": "string", "title": "Status", "examples": [ "booked" ] }, "start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start", "examples": [ "2026-09-01T14:00:00.000Z" ] }, "end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End", "examples": [ "2026-09-01T14:30:00.000Z" ] }, "minutesDuration": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Minutesduration", "examples": [ 30 ] }, "serviceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Servicetype", "examples": [ "cardiology" ] }, "appointmentType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Appointmenttype", "examples": [ "follow-up" ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "examples": [ "Follow-up" ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "examples": [ "Routine check" ] }, "createdAt": { "type": "string", "title": "Createdat", "description": "ISO-8601 timestamp when the appointment was created." } }, "type": "object", "required": [ "id", "status", "createdAt" ], "title": "AppointmentResponse", "description": "A single appointment. `id` is the stable public id (apt_...).", "examples": [ { "appointmentType": "follow-up", "consultationInternalId": "CONSULT-12345", "createdAt": "2026-08-28T12:00:00.000Z", "end": "2026-09-01T14:30:00.000Z", "id": "apt_a1b2c3d4e5f6g7h8", "minutesDuration": 30, "reason": "Follow-up", "serviceType": "cardiology", "start": "2026-09-01T14:00:00.000Z", "status": "booked" } ] }, "AppointmentStatus": { "type": "string", "enum": [ "proposed", "pending", "booked", "arrived", "checkedIn", "fulfilled", "cancelled", "noshow", "waitlist", "enteredInError" ], "title": "AppointmentStatus", "description": "FHIR appointment status set (mirrors datalayer AppointmentStatus). Used to\nvalidate the agenda `status` filter, so a typo is a clean 400, not a 5xx." }, "AppointmentUpdateRequest": { "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "cancelled", "noshow" ] }, { "type": "null" } ], "title": "Status", "description": "Set the booking to cancelled or noshow.", "examples": [ "cancelled" ] }, "scribeSessionId": { "anyOf": [ { "type": "string", "pattern": "^ss_[a-z0-9]{16}$" }, { "type": "null" } ], "title": "Scribesessionid", "description": "Public id of the session to attach when it was not auto-linked at create time. Sets the link and marks the booking fulfilled.", "examples": [ "ss_a1b2c3d4e5f6g7h8" ] } }, "type": "object", "title": "AppointmentUpdateRequest", "description": "PATCH body. Provide exactly one of `status` or `scribeSessionId`.\n\n`status` is limited to `cancelled` / `noshow` (a booking is fulfilled only by the\nserver when its session is created). `scribeSessionId` repairs a missed link:\nattach the session (`ss_`) whose id did not match the booking at create time; the\nbooking then becomes `fulfilled`.", "examples": [ { "status": "cancelled" }, { "scribeSessionId": "ss_a1b2c3d4e5f6g7h8" } ] }, "ArraySchema": { "properties": { "type": { "type": "string", "const": "array", "title": "Type" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "items": { "oneOf": [ { "$ref": "#/components/schemas/StringSchema" }, { "$ref": "#/components/schemas/NumberSchema" }, { "$ref": "#/components/schemas/BooleanSchema" }, { "$ref": "#/components/schemas/ObjectSchema" }, { "$ref": "#/components/schemas/ArraySchema" }, { "$ref": "#/components/schemas/CodeSchema" }, { "$ref": "#/components/schemas/CodeListSchema" }, { "$ref": "#/components/schemas/DerivedSchema" } ], "title": "Items" }, "minItems": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Minitems" }, "maxItems": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Maxitems" }, "examples": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Examples" }, "template": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Template" }, "required": { "type": "boolean", "title": "Required", "default": false } }, "type": "object", "required": [ "type", "items" ], "title": "ArraySchema", "description": "Schema for array outputs with a single item schema." }, "AuditConfigurationDetail": { "properties": { "id": { "type": "string", "title": "Id", "examples": [ "ac_9f8e7d6c5b4a3210" ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "examples": [ "General medicine v2" ] }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Version", "examples": [ "1.2" ] }, "active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Active", "description": "Whether the rubric is active." }, "sections": { "items": { "$ref": "#/components/schemas/AuditConfigurationSection" }, "type": "array", "title": "Sections", "description": "Weighted rubric sections." }, "scoreBands": { "items": { "$ref": "#/components/schemas/AuditConfigurationScoreBand" }, "type": "array", "title": "Scorebands", "description": "Grade bands that map a score to a label." } }, "type": "object", "required": [ "id" ], "title": "AuditConfigurationDetail", "description": "An audit rubric: its weighted sections and its grade bands." }, "AuditConfigurationListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/AuditConfigurationDetail" }, "type": "array", "title": "Items", "description": "Audit rubrics assigned to the institution." } }, "type": "object", "required": [ "items" ], "title": "AuditConfigurationListResponse", "description": "The audit rubrics available to the caller's institution.", "examples": [ { "items": [ { "active": true, "id": "ac_9f8e7d6c5b4a3210", "name": "General medicine v2", "scoreBands": [ { "label": "SOBRESALIENTE", "threshold": 0.9, "tone": "success" }, { "label": "ACEPTABLE", "threshold": 0.8, "tone": "info" }, { "label": "DEFICIENTE", "threshold": 0.0, "tone": "destructive" } ], "sections": [ { "displayName": "Anamnesis", "name": "ANAMNESIS", "weight": 0.2 } ], "version": "1.2" } ] } ] }, "AuditConfigurationRef": { "properties": { "id": { "type": "string", "title": "Id", "examples": [ "ac_9f8e7d6c5b4a3210" ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "examples": [ "General medicine v2" ] }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Version", "examples": [ "1.2" ] } }, "type": "object", "required": [ "id" ], "title": "AuditConfigurationRef", "description": "The rubric an audit was scored against." }, "AuditConfigurationScoreBand": { "properties": { "threshold": { "type": "number", "title": "Threshold", "description": "Inclusive lower bound on the 0..1 score scale.", "examples": [ 0.8 ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label", "description": "Band label (default locale).", "examples": [ "ACEPTABLE" ] }, "tone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tone", "description": "Semantic tone: 'success', 'info', 'warning', or 'destructive'.", "examples": [ "success" ] } }, "type": "object", "required": [ "threshold" ], "title": "AuditConfigurationScoreBand", "description": "One grade band: a score at or above `threshold` earns this band's label." }, "AuditConfigurationSection": { "properties": { "name": { "type": "string", "title": "Name", "description": "Section key.", "examples": [ "ANAMNESIS" ] }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Displayname", "description": "Section label (default locale).", "examples": [ "Anamnesis" ] }, "weight": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Weight", "description": "Weight of this section in the total score.", "examples": [ 0.2 ] } }, "type": "object", "required": [ "name" ], "title": "AuditConfigurationSection", "description": "One weighted rubric section of an audit configuration." }, "AuditListItem": { "properties": { "id": { "type": "string", "title": "Id", "description": "Stable audit identifier.", "examples": [ "au_a1b2c3d4e5f6g7h8" ] }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Score", "description": "Weighted total quality score, 0..1.", "examples": [ 0.82 ] }, "grade": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Grade", "description": "Qualitative grade of the score.", "examples": [ "ACEPTABLE" ] }, "reviewStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reviewstatus", "description": "Human-review state: 'pending', 'inReview', or 'reviewed'." }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Origin", "description": "How the audit was created (e.g. 'scribe').", "examples": [ "scribe" ] }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Createdat" }, "patientName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Patientname", "description": "Name of the audited patient." }, "configuration": { "anyOf": [ { "$ref": "#/components/schemas/AuditConfigurationRef" }, { "type": "null" } ], "description": "The rubric this audit was scored against (null for legacy audits)." } }, "type": "object", "required": [ "id" ], "title": "AuditListItem", "description": "One audit in the institution's audit list (overview; no per-section breakdown)." }, "AuditListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/AuditListItem" }, "type": "array", "title": "Items", "description": "Page of audits." }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total", "description": "Total audits in scope \u2014 always null (no server-side count)." }, "page": { "type": "integer", "title": "Page", "description": "Current page number (1-based)." }, "limit": { "type": "integer", "title": "Limit", "description": "Number of items per page." }, "totalPages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Totalpages", "description": "Total pages \u2014 always null." }, "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Whether another page exists." } }, "type": "object", "required": [ "items", "page", "limit", "hasMore" ], "title": "AuditListResponse", "description": "Paginated list of the institution's audits.", "examples": [ { "hasMore": false, "items": [ { "configuration": { "id": "ac_9f8e7d6c5b4a3210", "name": "General medicine v2", "version": "1.2" }, "createdAt": "2026-02-20T10:35:00Z", "grade": "ACEPTABLE", "id": "au_a1b2c3d4e5f6g7h8", "origin": "scribe", "patientName": "John Doe", "reviewStatus": "reviewed", "score": 0.82 } ], "limit": 20, "page": 1 } ] }, "AuditResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Stable audit identifier.", "examples": [ "au_a1b2c3d4e5f6g7h8" ] }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Score", "description": "Weighted total quality score, 0..1.", "examples": [ 0.82 ] }, "grade": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Grade", "description": "Qualitative grade of the score.", "examples": [ "ACEPTABLE" ] }, "reviewStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reviewstatus", "description": "Human-review state: 'pending', 'inReview', or 'reviewed'." }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Origin", "description": "How the audit was created (e.g. 'scribe').", "examples": [ "scribe" ] }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Createdat" }, "configuration": { "anyOf": [ { "$ref": "#/components/schemas/AuditConfigurationRef" }, { "type": "null" } ], "description": "The rubric this audit was scored against (null for legacy audits)." }, "sections": { "items": { "$ref": "#/components/schemas/AuditSection" }, "type": "array", "title": "Sections", "description": "Per-section scores with their labels." } }, "type": "object", "required": [ "id" ], "title": "AuditResponse", "description": "A scribe session's clinical-quality audit.", "examples": [ { "configuration": { "id": "ac_9f8e7d6c5b4a3210", "name": "General medicine v2", "version": "1.2" }, "createdAt": "2026-02-20T10:35:00Z", "grade": "ACEPTABLE", "id": "au_a1b2c3d4e5f6g7h8", "origin": "scribe", "reviewStatus": "reviewed", "score": 0.82, "sections": [ { "label": "Anamnesis", "name": "ANAMNESIS", "score": 0.9 }, { "label": "Physical exam", "name": "PHYSICAL_EXAM", "score": 0.75 } ] } ] }, "AuditReviewStatus": { "type": "string", "enum": [ "pending", "inReview", "reviewed" ], "title": "AuditReviewStatus", "description": "Human-review state of an audit (filter value on the list endpoint)." }, "AuditSection": { "properties": { "name": { "type": "string", "title": "Name", "description": "Section key of the rubric.", "examples": [ "ANAMNESIS" ] }, "label": { "type": "string", "title": "Label", "description": "Human-readable section label.", "examples": [ "Anamnesis" ] }, "score": { "type": "number", "title": "Score", "description": "Section score, 0..1.", "examples": [ 0.9 ] } }, "type": "object", "required": [ "name", "label", "score" ], "title": "AuditSection", "description": "One rubric section's score for an audit." }, "BatchAccountResult": { "properties": { "index": { "type": "integer", "title": "Index", "description": "Zero-based position of this account in the request.", "examples": [ 0 ] }, "email": { "type": "string", "title": "Email", "description": "Email submitted for this account. Echoed so a caller maps a result to its input.", "examples": [ "dr.juan@clinica.com" ] }, "status": { "type": "string", "enum": [ "created", "error" ], "title": "Status", "description": "`created` when the account was created; `error` when it was not.", "examples": [ "created" ] }, "account": { "anyOf": [ { "$ref": "#/components/schemas/CreateAccountResponse" }, { "type": "null" } ], "description": "The created account. Present only when `status` is `created`." }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ErrorDetail" }, { "type": "null" } ], "description": "Why this account was not created. Present only when `status` is `error`." } }, "type": "object", "required": [ "index", "email", "status" ], "title": "BatchAccountResult", "description": "Outcome of one account inside a batch response." }, "BatchCreateAccountsRequest": { "properties": { "accounts": { "items": { "$ref": "#/components/schemas/CreateAccountRequest" }, "type": "array", "maxItems": 10, "minItems": 1, "title": "Accounts", "description": "The doctor accounts to create (1\u201310). Each item takes the same fields as the single-create endpoint. The whole request is rejected before any account is created when it repeats an email or an internalCode." } }, "type": "object", "required": [ "accounts" ], "title": "BatchCreateAccountsRequest", "description": "Request body for creating several institutional doctor accounts in one call.", "examples": [ { "accounts": [ { "doctorSpecialties": [ "cardiology" ], "email": "dr.juan@clinica.com", "internalCode": "DOC-001", "nameFull": "Dr. Juan P\u00e9rez" }, { "doctorSpecialties": [ "pediatrics" ], "email": "dra.ana@clinica.com", "internalCode": "DOC-002", "nameFull": "Dra. Ana G\u00f3mez" } ] } ] }, "BatchCreateAccountsResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/BatchAccountResult" }, "type": "array", "title": "Results", "description": "One entry per submitted account, in the order received." }, "createdCount": { "type": "integer", "title": "Createdcount", "description": "Number of accounts created.", "examples": [ 1 ] }, "failedCount": { "type": "integer", "title": "Failedcount", "description": "Number of accounts that were not created.", "examples": [ 1 ] } }, "type": "object", "required": [ "results", "createdCount", "failedCount" ], "title": "BatchCreateAccountsResponse", "description": "Per-item outcome of a batch account-creation request.\n\nThe request never fails as a whole once creation starts: each account is\ncreated independently, so an entry can succeed while another fails. The\nresults keep the request order.", "examples": [ { "createdCount": 1, "failedCount": 1, "results": [ { "account": { "apiKey": "", "apiKeyExpiresInDays": 365, "email": "dr.juan@clinica.com", "expiresAt": "2027-06-17T00:00:00Z", "id": "acc_a1b2c3d4e5f6g7h8", "internalCode": "DOC-001", "publishableApiKey": "" }, "email": "dr.juan@clinica.com", "index": 0, "status": "created" }, { "email": "dra.ana@clinica.com", "error": { "code": "resource_conflict", "message": "An account with this internalCode already exists for this institution.", "param": "internalCode", "type": "invalid_request_error" }, "index": 1, "status": "error" } ] } ] }, "BooleanSchema": { "properties": { "type": { "type": "string", "const": "boolean", "title": "Type" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "required": { "type": "boolean", "title": "Required", "default": false }, "default": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Default" } }, "type": "object", "required": [ "type" ], "title": "BooleanSchema", "description": "Schema for boolean outputs." }, "CdssAlert": { "properties": { "id": { "type": "string", "title": "Id", "description": "Stable opaque identifier for the alert. Use it as-is; do not parse it." }, "elementId": { "type": "string", "title": "Elementid", "description": "Clinical element key (e.g. 'IBUPROFEN'). Human-meaningful but not unique across documents \u2014 never use it as an identifier." }, "reason": { "type": "string", "title": "Reason" }, "action": { "type": "string", "title": "Action" }, "actionCategory": { "type": "string", "title": "Actioncategory" }, "type": { "type": "string", "title": "Type" }, "issue": { "type": "string", "title": "Issue" }, "element": { "type": "string", "title": "Element" }, "severity": { "type": "string", "title": "Severity" }, "source": { "items": { "type": "string" }, "type": "array", "title": "Source" }, "newPlanElement": { "anyOf": [ { "$ref": "#/components/schemas/CdssAlertNewPlanElement" }, { "type": "null" } ] }, "previousTestDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previoustestdate" }, "guidelineIntervalDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Guidelineintervaldays" }, "status": { "type": "string", "title": "Status", "description": "Doctor's decision on the alert: 'pending', 'accepted', or 'rejected'.", "default": "pending" } }, "type": "object", "required": [ "id", "elementId", "reason", "action", "actionCategory", "type", "issue", "element", "severity" ], "title": "CdssAlert", "description": "A single corrective CDSS alert as exposed on the public API." }, "CdssAlertNewPlanElement": { "properties": { "type": { "type": "string", "title": "Type" }, "element": { "type": "string", "title": "Element" }, "id": { "type": "string", "title": "Id" }, "content": { "type": "string", "title": "Content" }, "laboratory": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Laboratory" } }, "type": "object", "required": [ "type", "element", "id", "content" ], "title": "CdssAlertNewPlanElement", "description": "The plan element a CDSS alert proposes (present on add/replace/modify)." }, "CdssDecisionItem": { "properties": { "id": { "type": "string", "maxLength": 512, "minLength": 1, "title": "Id", "description": "The alert `id` returned by the medical record documents endpoint.", "examples": [ "cfa_bXJkLWFiYy0xMjMfSUJVUFJPRkVO" ] }, "decision": { "type": "string", "enum": [ "accepted", "rejected" ], "title": "Decision", "description": "The doctor's decision for this alert.", "examples": [ "accepted" ] } }, "type": "object", "required": [ "id", "decision" ], "title": "CdssDecisionItem", "description": "One alert decision inside a batch request." }, "CdssDecisionResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "The alert identifier the decision was recorded for.", "examples": [ "cfa_bXJkLWFiYy0xMjMfSUJVUFJPRkVO" ] }, "elementId": { "type": "string", "title": "Elementid", "description": "Clinical element key the alert refers to.", "examples": [ "IBUPROFEN" ] }, "status": { "type": "string", "title": "Status", "description": "The recorded decision: `accepted` or `rejected`.", "examples": [ "accepted" ] } }, "type": "object", "required": [ "id", "elementId", "status" ], "title": "CdssDecisionResponse", "description": "The decision recorded for a CDSS alert.\n\nA 200 means the decision is recorded. An accepted alert is applied to the medical\nrecord by a background task, so the record itself may still show its previous\ncontent immediately afterwards.", "examples": [ { "elementId": "IBUPROFEN", "id": "cfa_bXJkLWFiYy0xMjMfSUJVUFJPRkVO", "status": "accepted" } ] }, "CdssDecisionsRequest": { "properties": { "decisions": { "items": { "$ref": "#/components/schemas/CdssDecisionItem" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Decisions", "description": "The alerts to act on. Every alert is validated before any decision is recorded." } }, "type": "object", "required": [ "decisions" ], "title": "CdssDecisionsRequest", "description": "Record decisions for several CDSS alerts in one call.", "examples": [ { "decisions": [ { "decision": "accepted", "id": "cfa_bXJkLWFiYy0xMjMfSUJVUFJPRkVO" }, { "decision": "rejected", "id": "cfa_bXJkLWFiYy0xMjMfQVNQSVJJTg" } ] } ] }, "CdssDecisionsResponse": { "properties": { "decisions": { "items": { "$ref": "#/components/schemas/CdssDecisionResponse" }, "type": "array", "title": "Decisions", "description": "One entry per submitted alert, in the order received." } }, "type": "object", "required": [ "decisions" ], "title": "CdssDecisionsResponse", "description": "The decisions recorded for a batch request.", "examples": [ { "decisions": [ { "elementId": "IBUPROFEN", "id": "cfa_bXJkLWFiYy0xMjMfSUJVUFJPRkVO", "status": "accepted" } ] } ] }, "CodeListSchema": { "properties": { "type": { "type": "string", "const": "codeList", "title": "Type" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions" }, "system": { "type": "string", "title": "System" }, "source": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Source" }, "maxItems": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Maxitems" }, "maxOptions": { "type": "integer", "minimum": 1.0, "title": "Maxoptions", "default": 1 }, "required": { "type": "boolean", "title": "Required", "default": false } }, "type": "object", "required": [ "type", "system" ], "title": "CodeListSchema", "description": "A catalog code-list declaration inside an object. Stores system, sibling source names, and maxOptions. maxItems is not persisted by this API." }, "CodeSchema": { "properties": { "type": { "type": "string", "const": "code", "title": "Type" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions" }, "system": { "type": "string", "title": "System" }, "source": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Source" }, "maxOptions": { "type": "integer", "minimum": 1.0, "title": "Maxoptions", "default": 1 }, "required": { "type": "boolean", "title": "Required", "default": false } }, "type": "object", "required": [ "type", "system" ], "title": "CodeSchema", "description": "A catalog code declaration inside an object. Stores system, sibling source names, and maxOptions for post-generation resolution." }, "ConsultationRef": { "properties": { "id": { "type": "string", "title": "Id", "examples": [ "CONSULT-12345" ] } }, "type": "object", "required": [ "id" ], "title": "ConsultationRef", "description": "Echo of the caller's consultation reference." }, "Coordinates": { "properties": { "latitude": { "type": "number", "maximum": 90.0, "minimum": -90.0, "title": "Latitude", "examples": [ 4.711 ] }, "longitude": { "type": "number", "maximum": 180.0, "minimum": -180.0, "title": "Longitude", "examples": [ -74.072 ] } }, "type": "object", "required": [ "latitude", "longitude" ], "title": "Coordinates", "description": "Geographic coordinates of a branch." }, "CreateAccountRequest": { "properties": { "email": { "type": "string", "maxLength": 254, "title": "Email", "examples": [ "dr.juan@clinica.com" ] }, "doctorSpecialties": { "items": { "$ref": "#/components/schemas/MedicalSpecialty" }, "type": "array", "minItems": 1, "title": "Doctorspecialties", "description": "Accepts either the specialty key ('CARDIOLOGY') or value ('cardiology'); always persisted as the value.", "examples": [ [ "cardiology" ] ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country", "description": "Country as ISO 3166-1 alpha-2 (e.g. 'CO', 'BR'). Also accepts alpha-3 ('COL') or the English country name ('COLOMBIA'); all are normalized to the alpha-2 code Telepatia stores. Omit to inherit the institution's country.", "examples": [ "CO" ] }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language", "description": "Account UI/content language as ISO 639-1 (e.g. 'es', 'pt', 'en'). Omit to inherit the institution's language.", "examples": [ "es" ] }, "timeZone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timezone", "description": "IANA time zone (e.g. 'America/Bogota', 'America/Sao_Paulo'). Omit to inherit the institution's time zone.", "examples": [ "America/Bogota" ] }, "nameFull": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Namefull", "examples": [ "Dr. Juan P\u00e9rez" ] }, "institutionalBranchName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Institutionalbranchname", "examples": [ "Sede Norte" ] }, "internalCode": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Internalcode", "description": "Idempotency key scoped to the institution. Re-submitting the same value returns 409 if the account already exists. Omit to have the server generate a UUID v7 (no idempotency when generated); the value is returned in the response.", "examples": [ "DOC-001" ] }, "apiKeyConfig": { "anyOf": [ { "$ref": "#/components/schemas/ApiKeyConfig" }, { "type": "null" } ], "description": "Optional API key settings. Omit to mint a key valid for 365 days (1 year)." } }, "type": "object", "required": [ "email", "doctorSpecialties" ], "title": "CreateAccountRequest", "description": "Request body for creating an institutional doctor account.", "examples": [ { "apiKeyConfig": { "validForDays": 365 }, "country": "CO", "doctorSpecialties": [ "cardiology" ], "email": "dr.juan@clinica.com", "institutionalBranchName": "Sede Norte", "internalCode": "DOC-001", "language": "es", "nameFull": "Dr. Juan P\u00e9rez", "timeZone": "America/Bogota" } ] }, "CreateAccountResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Account publicId (acc_*). Use this as the identifier in subsequent API calls.", "examples": [ "acc_a1b2c3d4e5f6g7h8" ] }, "email": { "type": "string", "title": "Email", "examples": [ "dr.juan@clinica.com" ] }, "apiKey": { "type": "string", "title": "Apikey", "description": "Raw secret API key for this account. Shown only once \u2014 store it securely.", "examples": [ "" ] }, "publishableApiKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Publishableapikey", "description": "Raw publishable (pk_) key for the browser/embed exchange flow. Exchange-only (cannot call the API directly) and shown only once \u2014 minted alongside the secret key.", "examples": [ "" ] }, "internalCode": { "type": "string", "title": "Internalcode", "description": "Institution-scoped code for this account. Echoes the request value when supplied; otherwise a server-generated UUID v7. Always present \u2014 store it to fetch the account later via GET /accounts/{internalCode}.", "examples": [ "DOC-001" ] }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expiresat", "description": "UTC timestamp when this API key expires. Always present for institutional keys.", "examples": [ "2027-06-17T00:00:00Z" ] }, "apiKeyExpiresInDays": { "type": "integer", "title": "Apikeyexpiresindays", "description": "API key lifetime in days that was applied (the validForDays used, default 365).", "examples": [ 365 ] } }, "type": "object", "required": [ "id", "email", "apiKey", "internalCode", "expiresAt", "apiKeyExpiresInDays" ], "title": "CreateAccountResponse", "description": "Response body after creating an institutional doctor account.", "examples": [ { "apiKey": "", "apiKeyExpiresInDays": 365, "email": "dr.juan@clinica.com", "expiresAt": "2027-06-17T00:00:00Z", "id": "acc_a1b2c3d4e5f6g7h8", "internalCode": "DOC-001", "publishableApiKey": "" } ] }, "CreateBranchRequest": { "properties": { "name": { "type": "string", "maxLength": 255, "title": "Name", "examples": [ "Sede Norte" ] }, "type": { "anyOf": [ { "$ref": "#/components/schemas/InstitutionalBranchType" }, { "type": "null" } ], "examples": [ "single" ] }, "visible": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Visible", "examples": [ true ] }, "main": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Main", "examples": [ false ] }, "order": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Order", "examples": [ 0 ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Description" }, "address": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Address", "examples": [ "Av. 7 #12-34" ] }, "IPS": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Ips" }, "coordinates": { "anyOf": [ { "$ref": "#/components/schemas/Coordinates" }, { "type": "null" } ] }, "expectedConsultations": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Expectedconsultations" }, "branchManagerAccountIds": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Branchmanageraccountids" }, "cdssConfigurationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cdssconfigurationid" }, "auditConfigurationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Auditconfigurationid" }, "sessionStartLabel": { "anyOf": [ { "$ref": "#/components/schemas/SessionStartLabel" }, { "type": "null" } ] } }, "type": "object", "required": [ "name" ], "title": "CreateBranchRequest", "description": "Request body for creating an institution branch.\n\nMirrors datalayer's branch input. Only ``name`` is required; omitted fields\nfall back to datalayer defaults (``visible=true``, ``type=single``,\n``main=false``, ``order=0``, ``IPS=[]``). The branch ``id`` is generated\nserver-side.", "examples": [ { "address": "Av. 7 #12-34", "main": false, "name": "Sede Norte", "type": "single" } ] }, "CreateBranchResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Server-generated branch id." }, "name": { "type": "string", "title": "Name", "examples": [ "Sede Norte" ] }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type", "examples": [ "single" ] }, "visible": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Visible" }, "main": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Main" }, "order": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Order" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Address" }, "IPS": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Ips" }, "coordinates": { "anyOf": [ { "$ref": "#/components/schemas/Coordinates" }, { "type": "null" } ] }, "expectedConsultations": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Expectedconsultations" }, "branchManagerAccountIds": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Branchmanageraccountids" }, "cdssConfigurationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cdssconfigurationid" }, "auditConfigurationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Auditconfigurationid" }, "sessionStartLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sessionstartlabel" } }, "type": "object", "required": [ "id", "name" ], "title": "CreateBranchResponse", "description": "Response body after creating an institution branch.", "examples": [ { "address": "Av. 7 #12-34", "id": "b1f2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "main": false, "name": "Sede Norte", "order": 0, "type": "single", "visible": true } ] }, "CreateMedicalRecordConfigurationRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Name", "description": "Human-readable display name. Defaults to the public id when omitted.", "examples": [ "Cardiology intake" ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Description", "description": "Optional human-readable description of the template.", "examples": [ "Intake template for the cardiology outpatient clinic." ] }, "specialty": { "anyOf": [ { "$ref": "#/components/schemas/MedicalSpecialty" }, { "type": "null" } ], "description": "Medical specialty this template targets, given as the enum key (such as `GENERAL_MEDICINE`) or its camelCase value (such as `generalMedicine`). When set by an institutional API key, the template is distributed as a child copy to every enabled account in the institution that already carries this specialty. Accounts without this specialty are not targets, and a doctor API key never distributes. Optional; omitting it skips distribution.", "examples": [ "GENERAL_MEDICINE" ] }, "workflow": { "anyOf": [ { "$ref": "#/components/schemas/MrcWorkflow" }, { "type": "null" } ], "description": "Product discriminator for this template. Omit for an ordinary Scribe template with no declared care setting; readers treat the omitted value as `defaultOutpatient`. `defaultOutpatient`, `inpatient`, and `emergencyRoom` also denote a Scribe template, and each names the clinical care setting. `reportDictation` is a dictation report template; `historySummary` is a patient-history summarizer. Set at creation and never changed; it is part of the deduplication identity, so the same configuration may exist once per value.", "examples": [ "reportDictation" ] }, "configuration": { "additionalProperties": { "$ref": "#/components/schemas/Section" }, "type": "object", "minProperties": 1, "title": "Configuration", "description": "Section map keyed by node name (schema + optional prompt strategy)." } }, "type": "object", "required": [ "configuration" ], "title": "CreateMedicalRecordConfigurationRequest", "description": "Request body for registering a medical record configuration \u2014 a map of section key to section definition.", "examples": [ { "configuration": { "chiefComplaint": { "instructionSet": { "telepatiaPromptId": "CHIEF_COMPLAINT" }, "schema": { "instructions": "Patient's chief complaint.", "type": "string" } }, "vitals": { "instructionSet": { "telepatiaPromptId": "VITAL_SIGNS" }, "schema": { "instructions": "Vital signs.", "properties": { "heartRate": { "instructions": "Heart rate in bpm.", "type": "integer" } }, "type": "object" } } }, "name": "Cardiology intake" } ] }, "CreateMedicalRecordConfigurationResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Public ID of the medical record configuration.", "examples": [ "mrc_a1b2c3d4e5f6g7h8" ] }, "name": { "type": "string", "title": "Name", "description": "Resolved display name (defaults to the public id when none was provided).", "examples": [ "Cardiology intake" ] }, "hash": { "type": "string", "title": "Hash", "description": "SHA-256 hash of the canonical configuration JSON.", "examples": [ "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" ] }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat", "examples": [ "2026-04-20T14:30:00Z" ] }, "created": { "type": "boolean", "title": "Created", "description": "True if a new configuration was created; False if a matching one already existed.", "examples": [ true ] } }, "type": "object", "required": [ "id", "name", "hash", "createdAt", "created" ], "title": "CreateMedicalRecordConfigurationResponse", "description": "Response body for registering a medical record configuration.", "examples": [ { "created": true, "createdAt": "2026-04-20T14:30:00Z", "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "id": "mrc_a1b2c3d4e5f6g7h8", "name": "Cardiology intake" } ] }, "CreateWebhookRequest": { "properties": { "url": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Url", "description": "https endpoint that will receive event POSTs." }, "name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Name", "description": "Optional human-readable label to identify this webhook in lists/UI. Trimmed server-side; a blank value stores no name." }, "events": { "anyOf": [ { "items": { "$ref": "#/components/schemas/WebhookEventName" }, "type": "array" }, { "type": "null" } ], "title": "Events", "description": "Event types to subscribe to (at least one). Preferred over `event`." }, "event": { "anyOf": [ { "$ref": "#/components/schemas/WebhookEventName" }, { "type": "null" } ], "description": "Deprecated: a single event type. Use `events`. When set and `events` is omitted, it is saved as a one-element `events` list.", "deprecated": true } }, "type": "object", "required": [ "url" ], "title": "CreateWebhookRequest", "examples": [ { "events": [ "scribe_session.created", "scribe_session.completed", "scribe_session.error" ], "name": "Scribe prod webhook", "url": "https://example.com/webhooks/scribe" } ] }, "CreateWebhookResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "url": { "type": "string", "title": "Url" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Optional human-readable label, or null if unset." }, "events": { "items": { "$ref": "#/components/schemas/WebhookEventName" }, "type": "array", "title": "Events" }, "event": { "anyOf": [ { "$ref": "#/components/schemas/WebhookEventName" }, { "type": "null" } ], "description": "Deprecated: the first subscribed event (events[0]). Use `events`.", "deprecated": true }, "isActive": { "type": "boolean", "title": "Isactive" }, "signingSecretPrefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signingsecretprefix", "description": "Display hint for the signing secret (e.g. 'whsec_a1b2c3d4'). The raw secret is only returned at creation/rotation." }, "signingSecretVersion": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Signingsecretversion" }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Createdat" }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updatedat" }, "deletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deletedat" }, "signingSecret": { "type": "string", "title": "Signingsecret", "description": "Raw HMAC signing secret. Shown once at creation \u2014 store it now; it is never retrievable again. Use it to verify the X-Scribe-Api-Signature header." } }, "type": "object", "required": [ "id", "url", "events", "isActive", "signingSecret" ], "title": "CreateWebhookResponse", "description": "Create response \u2014 carries the raw signing secret, shown exactly once." }, "DerivedSchema": { "properties": { "type": { "type": "string", "const": "derivedString", "title": "Type" }, "derivation": { "items": { "$ref": "#/components/schemas/DerivedStringVariant" }, "type": "array", "minItems": 1, "title": "Derivation" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "required": { "type": "boolean", "title": "Required", "default": false } }, "type": "object", "required": [ "type", "derivation" ], "title": "DerivedSchema", "description": "A string field computed from sibling values after LLM generation.\n\n``{placeholder}`` refs interpolate scalar siblings. Non-nested ``[...]`` groups render\nonly when every placeholder inside has a non-empty scalar value." }, "DerivedStringVariant": { "properties": { "language": { "type": "string", "title": "Language" }, "template": { "type": "string", "title": "Template" } }, "type": "object", "required": [ "language", "template" ], "title": "DerivedStringVariant", "description": "A language-specific template for a derived string field." }, "DiagnosisCode": { "properties": { "code": { "type": "string", "title": "Code", "examples": [ "I10" ] }, "description": { "type": "string", "title": "Description", "description": "Localized description of the code (may be empty for legacy records).", "examples": [ "Essential (primary) hypertension" ] }, "type": { "type": "string", "enum": [ "primary", "secondary" ], "title": "Type", "description": "Whether the code is the primary diagnosis or a secondary one.", "examples": [ "primary" ] } }, "type": "object", "required": [ "code", "description", "type" ], "title": "DiagnosisCode", "description": "A single diagnosis ICD-10 (CIE-10 / CID-10) code the record documents." }, "EnumOption": { "properties": { "label": { "type": "string", "title": "Label" }, "value": { "type": "string", "title": "Value" } }, "type": "object", "required": [ "label", "value" ], "title": "EnumOption", "description": "A decoupled enum option: display ``label`` vs stored ``value`` (code).\n\nLets a partner show ``label`` while the generated record stores the stable\n``value`` (catalog id, ICD-10, SNOMED), so labels can be renamed/translated\nwithout breaking the integration that consumes the code." }, "EnumOptionModel": { "properties": { "label": { "type": "string", "title": "Label", "description": "Human-readable display label." }, "value": { "type": "string", "title": "Value", "description": "Stable stored code (e.g. catalog id, ICD-10, SNOMED)." } }, "type": "object", "required": [ "label", "value" ], "title": "EnumOptionModel", "description": "A decoupled enum option: display ``label`` vs stored ``value`` (code)." }, "ErrorDetail": { "description": "Error detail with machine-readable codes and human-readable message.", "properties": { "type": { "description": "Broad error category for high-level handling.", "examples": [ "invalid_request_error" ], "title": "Type", "type": "string" }, "code": { "description": "Machine-readable error code. Clients should switch on this value.", "examples": [ "parameter_invalid" ], "title": "Code", "type": "string" }, "message": { "description": "Human-readable error message ending with a period.", "examples": [ "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code." ], "title": "Message", "type": "string" }, "param": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The request field that caused the error, if applicable.", "examples": [ "idCountry" ], "title": "Param" }, "details": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional structured, machine-readable context for the error.", "examples": [ { "pendingConsultations": [ { "sessionId": "abc123", "url": "https://..." } ] } ], "title": "Details" } }, "required": [ "type", "code", "message" ], "title": "ErrorDetail", "type": "object" }, "GetAccountResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Account publicId (acc_*).", "examples": [ "acc_a1b2c3d4e5f6g7h8" ] }, "email": { "type": "string", "title": "Email", "examples": [ "dr.juan@clinica.com" ] }, "nameFull": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Namefull", "examples": [ "Dr. Juan P\u00e9rez" ] }, "doctorSpecialties": { "items": { "$ref": "#/components/schemas/MedicalSpecialty" }, "type": "array", "title": "Doctorspecialties", "examples": [ [ "cardiology" ] ] }, "enabled": { "type": "boolean", "title": "Enabled", "examples": [ true ] }, "internalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Internalcode", "examples": [ "DOC-001" ] }, "roles": { "items": { "type": "string" }, "type": "array", "title": "Roles", "description": "Account roles, e.g. doctor or institutional.", "examples": [ [ "doctor" ] ] }, "createdAt": { "type": "string", "title": "Createdat", "examples": [ "2024-01-15T10:30:00Z" ] } }, "type": "object", "required": [ "id", "email", "doctorSpecialties", "enabled", "createdAt" ], "title": "GetAccountResponse", "description": "Response body for fetching an institutional doctor account.", "examples": [ { "createdAt": "2024-01-15T10:30:00Z", "doctorSpecialties": [ "cardiology" ], "email": "dr.juan@clinica.com", "enabled": true, "id": "acc_a1b2c3d4e5f6g7h8", "internalCode": "DOC-001", "nameFull": "Dr. Juan P\u00e9rez", "roles": [ "doctor" ] } ] }, "IdCountry": { "type": "string", "enum": [ "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CX", "CC", "CO", "KM", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "CD", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "SZ", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IQ", "IE", "IR", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "KP", "MP", "NO", "OM", "PK", "PW", "PA", "PG", "PY", "CN", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "CG", "GM", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "KR", "SS", "ES", "LK", "PS", "SD", "SR", "SJ", "SE", "CH", "SY", "TW", "TJ", "TH", "MK", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "TZ", "UM", "US", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ], "title": "IdCountry", "description": "ISO 3166-1 alpha-2 country codes. Mirrors tanjiro's CountryCodes enum." }, "IdType": { "type": "string", "enum": [ "CC", "TI", "CE", "RC", "PASSPORT", "RG", "CPF", "OTHER_DOC" ], "title": "IdType", "description": "Supported patient identification document types." }, "InstitutionalBranchType": { "type": "string", "enum": [ "single", "multi" ], "title": "InstitutionalBranchType", "description": "Branch type \u2014 single site or multi-site." }, "InstructionSetModel": { "properties": { "telepatiaPromptId": { "type": "string", "title": "Telepatiapromptid", "description": "Identifier of the Telepatia-managed prompt." }, "values": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Values", "description": "Optional variable values passed into the prompt." } }, "type": "object", "required": [ "telepatiaPromptId" ], "title": "InstructionSetModel", "description": "Reference to a Telepatia managed prompt." }, "InstructionSetRef": { "properties": { "telepatiaPromptId": { "$ref": "#/components/schemas/TelepatiaPromptId" }, "values": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Values" } }, "type": "object", "required": [ "telepatiaPromptId" ], "title": "InstructionSetRef", "description": "Reference to a prompt template with optional variable substitutions." }, "ListAccountsResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/AccountSummary" }, "type": "array", "title": "Items", "description": "Page of accounts." }, "total": { "type": "integer", "title": "Total", "description": "Total accounts matching the request." }, "page": { "type": "integer", "title": "Page", "description": "Current page (1-based)." }, "limit": { "type": "integer", "title": "Limit", "description": "Items per page." } }, "type": "object", "required": [ "items", "total", "page", "limit" ], "title": "ListAccountsResponse", "description": "Paginated list of institution accounts.", "examples": [ { "items": [ { "email": "dr.juan@clinica.com", "id": "acc_a1b2c3d4e5f6g7h8", "nameFull": "Dr. Juan P\u00e9rez", "roles": [ "doctor" ] } ], "limit": 20, "page": 1, "total": 1 } ] }, "ListApiKeysResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiKeyMetadata" }, "type": "array", "title": "Items", "description": "Page of API key metadata." }, "total": { "type": "integer", "title": "Total", "description": "Total API keys matching the request." }, "page": { "type": "integer", "title": "Page", "description": "Current page (1-based)." }, "limit": { "type": "integer", "title": "Limit", "description": "Items per page." } }, "type": "object", "required": [ "items", "total", "page", "limit" ], "title": "ListApiKeysResponse", "description": "Paginated list of API key metadata.", "examples": [ { "items": [ { "accountId": "acc_a1b2c3d4e5f6g7h8", "createdAt": "2024-01-15T10:30:00Z", "expiresAt": "2025-01-15T10:30:00Z", "id": "ak_a1b2c3d4e5f6g7h8", "prefix": "sk_prod_aB3x...zzzz", "status": "active" } ], "limit": 20, "page": 1, "total": 1 } ] }, "LiveScribeSessionResponse": { "properties": { "consultation": { "$ref": "#/components/schemas/ConsultationRef" }, "status": { "type": "string", "const": "created", "title": "Status", "description": "Always `created` on success. Stream the audio to `live.url`; completion then follows the batch contract described on `status` above.", "default": "created" }, "live": { "$ref": "#/components/schemas/LiveSessionInfo" } }, "type": "object", "required": [ "consultation", "live" ], "title": "LiveScribeSessionResponse", "description": "201 response: the batch envelope plus the streaming URL.", "examples": [ { "consultation": { "id": "CONSULT-12345" }, "live": { "expiresAt": "2026-08-12T14:00:00+00:00", "url": "wss://example.telepatia.ai/v1/ws/audio/abc?token=..." }, "status": "created" } ] }, "LiveSessionInfo": { "properties": { "url": { "type": "string", "title": "Url", "description": "Opaque wss URL to stream the audio to. Connect, send binary audio frames (PCM 16 kHz mono s16le, or Ogg/WebM Opus), then send `{\"type\": \"stop_recording\", \"data\": {}}`. Reconnecting to the same URL resumes the session.", "examples": [ "wss://example.telepatia.ai/v1/ws/audio/abc?token=..." ] }, "expiresAt": { "type": "string", "title": "Expiresat", "description": "ISO 8601 instant after which the URL's credential is no longer valid.", "examples": [ "2026-08-12T14:00:00+00:00" ] } }, "type": "object", "required": [ "url", "expiresAt" ], "title": "LiveSessionInfo", "description": "Where and until when the caller can stream the consultation audio." }, "LoginRequest": { "properties": { "consultationInternalId": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Consultationinternalid", "examples": [ "cons_abc123" ] } }, "type": "object", "title": "LoginRequest", "description": "Login request body.", "examples": [ { "consultationInternalId": "cons_abc123" } ] }, "LoginResponse": { "properties": { "code": { "type": "string", "maxLength": 255, "title": "Code", "examples": [ "K7M2P9X4A1B8N3Q6R5T0V7W2Y9Z4C1D8" ] }, "expiresAt": { "type": "string", "maxLength": 255, "title": "Expiresat", "examples": [ "2026-02-20T18:30:00Z" ] }, "expiresIn": { "type": "integer", "title": "Expiresin", "examples": [ 900 ] }, "redirectUrl": { "type": "string", "title": "Redirecturl", "examples": [ "https://scribe.telepatia.ai/sign-in?code=K7M2P9X4A1B8N3Q6R5T0V7W2Y9Z4C1D8&consultationInternalId=cons_abc123" ] } }, "type": "object", "required": [ "code", "expiresAt", "expiresIn", "redirectUrl" ], "title": "LoginResponse", "description": "Login response with verification code.", "examples": [ { "code": "K7M2P9X4A1B8N3Q6R5T0V7W2Y9Z4C1D8", "expiresAt": "2026-02-20T18:30:00Z", "expiresIn": 900, "redirectUrl": "https://scribe.telepatia.ai/sign-in?code=K7M2P9X4A1B8N3Q6R5T0V7W2Y9Z4C1D8&consultationInternalId=cons_abc123" } ] }, "MedicalRecordDocumentItem": { "properties": { "id": { "type": "string", "maxLength": 255, "title": "Id", "examples": [ "mrd-abc-123" ] }, "purpose": { "type": "string", "maxLength": 255, "title": "Purpose", "description": "Identifies the record when a session produced several (e.g. 'primary', 'rpa', 'emr'). A dictated report has the purpose 'report'.", "examples": [ "primary" ] }, "reportState": { "anyOf": [ { "$ref": "#/components/schemas/ReportState" }, { "type": "null" } ], "description": "Workflow state of a dictated report. It is set only when `purpose` is 'report'. Null has one meaning: this record is not a dictated report, because only a dictated report has a workflow. Null never means that the state of a report is unknown. Read `reportState.lifecycleStatus` before you use a report: a draft is not complete, and the radiologist can still change it." }, "specialty": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Specialty", "description": "Medical specialty associated with the record.", "examples": [ "Cardiology" ] }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language", "description": "Language of the record content.", "examples": [ "en" ] }, "medicalRecordSummary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Medicalrecordsummary", "description": "Plain-text summary of the medical record." }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Createdat", "examples": [ "2026-02-20T10:30:00Z" ] }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updatedat", "examples": [ "2026-02-20T10:35:00Z" ] }, "medicalRecord": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Medicalrecord", "description": "The medical record as a JSON object keyed by section name (e.g. `chiefComplaint`, `vitalSigns`, `assessmentPlan`). Each section value is a plain string or a nested object, depending on the section. Iterate the keys that are present; the section set depends on the template." }, "medicalRecordSummaryStructured": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Medicalrecordsummarystructured", "description": "Structured summary: vital signs, medication, past conditions, recent labs/imaging, and last consultation. Includes `pastMedicalConditionsCoded` \u2014 the past conditions with resolved ICD-10 codes (`content` plus a `code` object with the best `code` and scored `options`) \u2014 which is `null` until code resolution has run for the record." }, "diagnosisCodes": { "items": { "$ref": "#/components/schemas/DiagnosisCode" }, "type": "array", "title": "Diagnosiscodes", "description": "Diagnosis ICD-10 (CIE-10 / CID-10) codes for the record \u2014 the doctor-curated set (model suggestions plus doctor additions, minus deletions). Empty when the session has no diagnosis codes." }, "cdssAlerts": { "anyOf": [ { "items": { "$ref": "#/components/schemas/CdssAlert" }, "type": "array" }, { "type": "null" } ], "title": "Cdssalerts", "description": "Corrective CDSS ('conducta feedback') alerts for this record. `null` when clinical decision support is disabled for the session or no alerts were generated; `[]` when it ran and produced none." } }, "type": "object", "required": [ "id", "purpose" ], "title": "MedicalRecordDocumentItem", "description": "A medical record document produced for a scribe session." }, "MedicalRecordDocumentListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/MedicalRecordDocumentItem" }, "type": "array", "title": "Items", "description": "Medical record documents for the session, one per purpose." }, "total": { "type": "integer", "title": "Total", "description": "Total number of medical record documents." } }, "type": "object", "required": [ "items", "total" ], "title": "MedicalRecordDocumentListResponse", "description": "Response body for listing a scribe session's medical record documents.", "examples": [ { "items": [ { "cdssAlerts": [ { "action": "Suspend ibuprofen; consider paracetamol.", "actionCategory": "replace", "element": "Ibuprofen 600mg q8h", "elementId": "IBUPROFEN", "id": "cfa_bXJkLWFiYy0xMjMfSUJVUFJPRkVO", "issue": "not_pertinent", "newPlanElement": { "content": "Paracetamol 1g q8h PO", "element": "Paracetamol", "id": "PARACETAMOL", "type": "medication" }, "reason": "NSAID contraindicated with documented CKD.", "severity": "red", "source": [ "KDIGO 2024 CKD guideline" ], "status": "pending", "type": "medication" } ], "createdAt": "2026-02-20T10:30:00Z", "diagnosisCodes": [ { "code": "I10", "description": "Essential (primary) hypertension", "type": "primary" } ], "id": "mrd-abc-123", "language": "en", "medicalRecord": { "assessmentPlan": { "assessment": "Likely stable angina.", "plan": [ { "content": "Reduce saturated fat intake.", "element": "Dietary counseling", "id": "DIETARY_COUNSELING", "laboratory": "", "type": "non_pharmacological" } ] }, "chiefComplaint": "Chest pain for two days.", "vitalSigns": { "bloodPressure": "120/80", "heartRate": "78", "temperature": "" } }, "medicalRecordSummary": "Patient presents with chest pain.", "medicalRecordSummaryStructured": { "pastMedicalConditions": [ "Hypertension" ], "pastMedicalConditionsCoded": [ { "code": { "code": "I10", "options": [ { "code": "I10", "score": 0.98 } ] }, "content": "Hypertension" } ], "vitalSigns": { "bloodPressure": "120/80" } }, "purpose": "primary", "specialty": "Cardiology", "updatedAt": "2026-02-20T10:35:00Z" } ], "total": 1 } ] }, "MedicalSpecialty": { "type": "string", "enum": [ "acupuncture", "alternativeMedicine", "ayurvedicMedicine", "chiropractic", "herbalMedicine", "homeopathy", "naturopathy", "traditionalChineseMedicine", "cosmeticDentistry", "dentistry", "developmentalBehavioralPediatrics", "endodontics", "forensicDentistry", "maxillofacialProsthodontics", "oralMaxillofacialSurgery", "oralMedicine", "oralPathology", "oralSurgery", "orthodontics", "pediatricDentistry", "periodontics", "prosthodontics", "addictionPsychiatry", "adolescentMedicine", "aerospaceMedicine", "allergyImmunology", "andrology", "anesthesiology", "anesthesiologyCriticalCare", "bariatricSurgery", "breastRadiology", "breastSurgery", "cardiacSurgery", "cardiovascularSurgery", "cardiology", "cardiovascularDisease", "cardiovascularRiskProgram", "childAbusePediatrics", "childAdolescentPsychiatry", "childNeurology", "childWelfareSocialWork", "clinicalNeurophysiology", "clinicalSocialWork", "colorectalSurgery", "communityMedicine", "communitySocialWork", "consultationLiaisonPsychiatry", "cosmeticDermatology", "craniofacialTrauma", "dermatology", "dermoscopy", "diabetes", "diagnosticRadiology", "electrophysiology", "emergencyCriticalCare", "emergencyMedicine", "emergencyPsychiatry", "endocrineSurgery", "endocrinology", "epilepsy", "facialPlasticSurgery", "familyMedicine", "familySocialWork", "footAnkleSurgery", "forensicPsychiatry", "forensicSocialWork", "gastroenterology", "generalMedicine", "generalMedicinePsychiatry", "generalSurgery", "geriatricMedicine", "geriatricPsychiatry", "geriatricSocialWork", "ginecology", "gynecologicOncology", "gynecologicSurgery", "gynecology", "handSurgery", "headNeckSurgery", "headacheMedicine", "heartFailureTransplantCardiology", "hematology", "hepatobiliarySurgery", "hipKneeSurgery", "hospitalist", "infectiousDisease", "internalCriticalCare", "internalMedicine", "interventionalCardiology", "interventionalRadiology", "maternalFetalMedicine", "medicalSocialWork", "militarySocialWork", "minimallyInvasiveGynecologicSurgery", "mohsSurgery", "musculoskeletalRadiology", "neonatology", "nephrology", "neurocriticalCare", "neuroimmunology", "neurology", "neuromuscularMedicine", "neuroradiology", "neurorehabilitation", "neurosurgery", "neurotology", "nuclearMedicine", "obstetrics", "obstetricsGynecology", "occupationalMedicine", "occupationalSocialWork", "oculoplasticSurgery", "oncology", "oncologySocialWork", "ophthalmology", "orthopedicHandSurgery", "orthopedicSportsMedicine", "orthopedicTrauma", "orthopedics", "otolaryngology", "painMedicine", "palliativeMedicine", "palliativeSocialWork", "pediatricAllergyImmunology", "pediatricAnesthesiology", "pediatricCardiology", "pediatricCriticalCare", "pediatricDermatology", "pediatricEmergencyMedicine", "pediatricEndocrinology", "pediatricENT", "pediatricGastroenterology", "pediatricHematologyOncology", "pediatricInfectiousDisease", "pediatricNephrology", "pediatricNeurology", "pediatricCardiacSurgery", "pediatricOncology", "pediatricOphthalmology", "pediatricOrthopedics", "pediatricPalliativeCare", "pediatricPulmonology", "pediatricRadiology", "pediatricRheumatology", "pediatricSocialWork", "pediatricSurgery", "pediatricTrauma", "pediatricUrology", "pediatrics", "perinatalPsychiatry", "physicalMedicineRehab", "plasticSurgery", "prenatalCareProgram", "preventiveMedicine", "psychiatricSocialWork", "psychiatry", "psychosomaticMedicine", "publicHealth", "pulmonaryDisease", "pulmonology", "radiationOncologist", "radiationOncology", "reproductiveEndocrinology", "retinaSurgery", "rheumatology", "riasProgram", "manager", "schoolSocialWork", "shoulderElbowSurgery", "sleepMedicine", "socialWork", "spinalCordInjury", "spinalTrauma", "spineSurgery", "sportsMedicine", "substanceAbuseSocialWork", "surgicalOncology", "telemedicine", "thoracicSurgery", "transplantHepatology", "transplantSurgery", "traumaSurgery", "traumatology", "triage", "unknown", "urgentCare", "urologicOncology", "urology", "vascularSurgery", "nursing", "clinicalNutrition", "eatingDisorderNutrition", "gastroenterologicNutrition", "geriatricNutrition", "nutrition", "oncologyNutrition", "pediatricNutrition", "renalNutrition", "sportsNutrition", "clinicalPsychology", "counselingPsychology", "developmentalPsychology", "forensicPsychology", "geropsychology", "healthPsychology", "industrialOrganizationalPsychology", "militaryPsychology", "neuropsychology", "positivePsychology", "psychology", "rehabilitationPsychology", "schoolPsychology", "sportsPsychology", "occupationalTherapy", "physicalTherapy", "respiratoryTherapy", "speechTherapy", "therapy", "other" ], "title": "MedicalSpecialty" }, "MrcDetailResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Stable public identifier.", "examples": [ "mrc_a1b2c3d4e5f6g7h8" ] }, "name": { "type": "string", "title": "Name", "description": "Display name (defaults to the public id when none was set).", "examples": [ "Cardiology intake" ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Optional human-readable description of the template.", "examples": [ "Intake template for the cardiology outpatient clinic." ] }, "hash": { "type": "string", "title": "Hash", "description": "Content hash used to detect configuration changes." }, "createdAt": { "type": "string", "title": "Createdat", "description": "ISO-8601 timestamp when the configuration was created." }, "configuration": { "additionalProperties": { "$ref": "#/components/schemas/MrcSectionModel" }, "type": "object", "title": "Configuration", "description": "Section configurations keyed by section name (e.g., 'chiefComplaint', 'vitals')." }, "specialties": { "items": { "type": "string" }, "type": "array", "title": "Specialties", "description": "Medical specialty values this configuration applies to.", "examples": [ [ "cardiology" ] ] }, "status": { "$ref": "#/components/schemas/MrcStatus", "description": "Lifecycle status: `active`, `inactive` (archived/draft), or `deleted`.", "examples": [ "active" ] }, "workflow": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workflow", "description": "Product this template belongs to. Null for an ordinary Scribe template.", "examples": [ "reportDictation" ] } }, "type": "object", "required": [ "id", "name", "hash", "createdAt", "configuration", "status" ], "title": "MrcDetailResponse", "description": "Full medical record configuration (detail response)." }, "MrcListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/MrcSummary" }, "type": "array", "title": "Items", "description": "Page of medical record configurations." }, "total": { "type": "integer", "title": "Total", "description": "Total number of configurations matching the filter." }, "page": { "type": "integer", "title": "Page", "description": "Current page number (1-based)." }, "limit": { "type": "integer", "title": "Limit", "description": "Number of items per page." }, "totalPages": { "type": "integer", "title": "Totalpages", "description": "Total number of pages." } }, "type": "object", "required": [ "items", "total", "page", "limit", "totalPages" ], "title": "MrcListResponse", "description": "Paginated list of medical record configurations.", "examples": [ { "items": [ { "createdAt": "2026-04-20T12:34:56Z", "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "id": "mrc_a1b2c3d4e5f6g7h8", "name": "Cardiology intake", "specialties": [ "cardiology" ], "status": "active" } ], "limit": 20, "page": 1, "total": 1, "totalPages": 1 } ] }, "MrcSectionModel": { "properties": { "systemPrompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Systemprompt", "description": "Optional raw system prompt for this section." }, "instructionSet": { "anyOf": [ { "$ref": "#/components/schemas/InstructionSetModel" }, { "type": "null" } ], "description": "Optional reference to a Telepatia managed prompt." }, "schema": { "$ref": "#/components/schemas/OutputSchemaModel", "description": "Output schema for this section." } }, "type": "object", "required": [ "schema" ], "title": "MrcSectionModel", "description": "The typed configuration for a single section within a medical record configuration." }, "MrcStatus": { "type": "string", "enum": [ "active", "inactive", "deleted" ], "title": "MrcStatus", "description": "Public lifecycle status exposed on list/detail responses." }, "MrcStatusFilter": { "type": "string", "enum": [ "deleted", "all" ], "title": "MrcStatusFilter", "description": "Filter for the templates list view: `deleted` (only soft-deleted templates) or\n`all` (non-deleted and deleted). Omit for the default non-deleted view." }, "MrcSummary": { "properties": { "id": { "type": "string", "title": "Id", "description": "Stable public identifier for the configuration.", "examples": [ "mrc_a1b2c3d4e5f6g7h8" ] }, "name": { "type": "string", "title": "Name", "description": "Display name (defaults to the public id when none was set).", "examples": [ "Cardiology intake" ] }, "hash": { "type": "string", "title": "Hash", "description": "Content hash used to detect configuration changes.", "examples": [ "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" ] }, "createdAt": { "type": "string", "title": "Createdat", "description": "ISO-8601 timestamp when the configuration was created.", "examples": [ "2026-04-20T12:34:56Z" ] }, "specialties": { "items": { "type": "string" }, "type": "array", "title": "Specialties", "description": "Medical specialty values this configuration applies to.", "examples": [ [ "cardiology" ] ] }, "status": { "$ref": "#/components/schemas/MrcStatus", "description": "Lifecycle status: `active`, `inactive` (archived/draft), or `deleted`.", "examples": [ "active" ] }, "workflow": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workflow", "description": "Product this template belongs to. Null for an ordinary Scribe template.", "examples": [ "reportDictation" ] } }, "type": "object", "required": [ "id", "name", "hash", "createdAt", "status" ], "title": "MrcSummary", "description": "A single medical record configuration summary (list response item)." }, "MrcWorkflow": { "type": "string", "enum": [ "defaultOutpatient", "inpatient", "emergencyRoom", "reportDictation", "historySummary" ], "title": "MrcWorkflow", "description": "Product discriminator for a template. Absent means an ordinary Scribe template.\n\n`defaultOutpatient`, `inpatient`, and `emergencyRoom` also denote a Scribe\ntemplate; each names the clinical care setting the template is written for.\n`reportDictation` and `historySummary` denote a non-Scribe product." }, "NumberSchema": { "properties": { "type": { "type": "string", "enum": [ "number", "integer" ], "title": "Type" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "minimum": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Minimum" }, "maximum": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Maximum" }, "exclusiveMinimum": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Exclusiveminimum" }, "exclusiveMaximum": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Exclusivemaximum" }, "enum": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Enum" }, "required": { "type": "boolean", "title": "Required", "default": false }, "default": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Default" } }, "type": "object", "required": [ "type" ], "title": "NumberSchema", "description": "Schema for numeric outputs (number or integer)." }, "ObjectSchema": { "properties": { "type": { "type": "string", "const": "object", "title": "Type" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "properties": { "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/StringSchema" }, { "$ref": "#/components/schemas/NumberSchema" }, { "$ref": "#/components/schemas/BooleanSchema" }, { "$ref": "#/components/schemas/ObjectSchema" }, { "$ref": "#/components/schemas/ArraySchema" }, { "$ref": "#/components/schemas/CodeSchema" }, { "$ref": "#/components/schemas/CodeListSchema" }, { "$ref": "#/components/schemas/DerivedSchema" } ] }, "type": "object", "title": "Properties" }, "examples": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Examples" }, "template": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Template" }, "required": { "type": "boolean", "title": "Required", "default": false } }, "type": "object", "required": [ "type", "properties" ], "title": "ObjectSchema", "description": "Schema for object outputs with named properties." }, "OutputSchemaModel": { "properties": { "type": { "type": "string", "title": "Type", "description": "Schema type (string, object, array, boolean, integer, number, code, codeList)." }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions", "description": "Free-form generation instructions." }, "examples": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Examples", "description": "Reference outputs that guide generation for a textual property." }, "properties": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OutputSchemaPropertyModel" }, "type": "array" }, { "type": "null" } ], "title": "Properties", "description": "Named properties (only present when type=object)." }, "items": { "anyOf": [ { "$ref": "#/components/schemas/OutputSchemaModel" }, { "type": "null" } ], "description": "Schema of array items (only present when type=array)." }, "enum": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/EnumOptionModel" } ] }, "type": "array" }, { "type": "null" } ], "title": "Enum", "description": "Allowed values. Either plain strings, or `{label, value}` objects that decouple display (`label`) from the stored code (`value`)." }, "minimum": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Minimum", "description": "Minimum numeric value." }, "maximum": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Maximum", "description": "Maximum numeric value." }, "minLength": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Minlength", "description": "Minimum string length." }, "maxLength": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Maxlength", "description": "Maximum string length." }, "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Format", "description": "String format hint: 'date', 'time', or 'date-time' (generation returns ISO)." }, "required": { "type": "boolean", "title": "Required", "description": "Whether the field must be generated. Defaults to false when omitted (the field is optional).", "default": false }, "default": { "title": "Default", "description": "Value substituted when generation extracts nothing; type must match `type`." }, "system": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "System", "description": "Catalog identifier for a code or codeList field, such as icd-10." }, "source": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Source", "description": "Sibling property names used for coding. Null means all non-code siblings." }, "maxOptions": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Maxoptions", "description": "Maximum number of ranked alternatives per code. Defaults to 1 when omitted." } }, "type": "object", "required": [ "type" ], "title": "OutputSchemaModel", "description": "Recursive template schema returned by GET, including nested properties, array items, and coding settings. Coding source names are returned as a list." }, "OutputSchemaPropertyModel": { "properties": { "key": { "type": "string", "title": "Key", "description": "Property key." }, "schema": { "$ref": "#/components/schemas/OutputSchemaModel", "description": "Schema describing this property." } }, "type": "object", "required": [ "key", "schema" ], "title": "OutputSchemaPropertyModel", "description": "A named property within an object output schema." }, "PatientCreateRequest": { "properties": { "name": { "type": "string", "maxLength": 500, "minLength": 1, "title": "Name", "examples": [ "John Doe" ] }, "idCountry": { "$ref": "#/components/schemas/IdCountry", "examples": [ "CO" ] }, "idType": { "$ref": "#/components/schemas/IdType", "examples": [ "CC" ] }, "idValue": { "type": "string", "maxLength": 50, "minLength": 1, "title": "Idvalue", "examples": [ "1024567890" ] }, "internalCode": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1 }, { "type": "null" } ], "title": "Internalcode", "description": "Caller-provided internal code, unique within your institution.", "examples": [ "EMR-12345" ] } }, "type": "object", "required": [ "name", "idCountry", "idType", "idValue" ], "title": "PatientCreateRequest", "description": "Request body for creating a patient.\n\nMirrors the identity fields of set-consultation-context.", "examples": [ { "idCountry": "COLOMBIA", "idType": "CC", "idValue": "1024567890", "internalCode": "EMR-12345", "name": "John Doe" } ] }, "PatientListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/PatientResponse" }, "type": "array", "title": "Items", "description": "Page of patients." }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total", "description": "Total patients matching the caller's scope (null on later pages)." }, "page": { "type": "integer", "title": "Page", "description": "Current page number (1-based)." }, "limit": { "type": "integer", "title": "Limit", "description": "Number of items per page." }, "totalPages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Totalpages", "description": "Total number of pages (null when the total is unknown)." }, "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Whether another page likely exists (accurate on every page)." } }, "type": "object", "required": [ "items", "page", "limit", "hasMore" ], "title": "PatientListResponse", "description": "Paginated list of patients." }, "PatientResponse": { "properties": { "id": { "type": "string", "title": "Id", "description": "Stable public identifier.", "examples": [ "sp_a1b2c3d4e5f6g7h8" ] }, "name": { "type": "string", "title": "Name", "examples": [ "John Doe" ] }, "idCountry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idcountry", "examples": [ "COLOMBIA" ] }, "idType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idtype", "examples": [ "CC" ] }, "idValue": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idvalue", "examples": [ "1024567890" ] }, "internalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Internalcode", "description": "Caller-provided internal code for your institution (null if none).", "examples": [ "EMR-12345" ] }, "createdAt": { "type": "string", "title": "Createdat", "description": "ISO-8601 timestamp when the patient was created." } }, "type": "object", "required": [ "id", "name", "createdAt" ], "title": "PatientResponse", "description": "A single patient. `id` is the stable public id (sp_...).", "examples": [ { "createdAt": "2026-07-01T12:00:00.000Z", "id": "sp_a1b2c3d4e5f6g7h8", "idCountry": "COLOMBIA", "idType": "CC", "idValue": "1024567890", "internalCode": "EMR-12345", "name": "John Doe" } ] }, "PatientSessionItem": { "properties": { "id": { "type": "string", "maxLength": 255, "title": "Id", "examples": [ "ss_a1b2c3d4e5f6g7h8" ] }, "status": { "type": "string", "maxLength": 255, "title": "Status", "examples": [ "completed" ] }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Createdat" }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completedat" }, "patientName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Patientname" }, "scribeSessionModality": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scribesessionmodality", "description": "The modality of the scribe session (e.g. 'IN_PERSON', 'TELEMEDICINE')." }, "consultationInternalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Consultationinternalid", "description": "The consultation ID provided by the API consumer." }, "specialty": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Specialty", "description": "The medical specialty of the clinician who conducted the session." } }, "type": "object", "required": [ "id", "status" ], "title": "PatientSessionItem", "description": "A single scribe session in a patient's timeline.\n\nMirrors the single-session lookup response \u2014 lifecycle + consultation metadata\nonly." }, "PatientSessionListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/PatientSessionItem" }, "type": "array", "title": "Items", "description": "Page of scribe sessions." }, "total": { "type": "integer", "title": "Total", "description": "Total sessions for the patient in the caller's scope." }, "page": { "type": "integer", "title": "Page", "description": "Current page number (1-based)." }, "limit": { "type": "integer", "title": "Limit", "description": "Number of items per page." }, "totalPages": { "type": "integer", "title": "Totalpages", "description": "Total number of pages." }, "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Whether another page exists." } }, "type": "object", "required": [ "items", "total", "page", "limit", "totalPages", "hasMore" ], "title": "PatientSessionListResponse", "description": "Paginated list of a patient's scribe sessions.", "examples": [ { "hasMore": false, "items": [ { "completedAt": "2026-02-20T10:30:00Z", "consultationInternalId": "CONSULT-12345", "createdAt": "2026-02-20T10:00:00Z", "id": "ss_a1b2c3d4e5f6g7h8", "patientName": "John Doe", "scribeSessionModality": "IN_PERSON", "specialty": "Cardiology", "status": "completed" } ], "limit": 20, "page": 1, "total": 1, "totalPages": 1 } ] }, "PatientUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 500, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "New display name.", "examples": [ "Jane Doe" ] }, "internalCode": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1 }, { "type": "null" } ], "title": "Internalcode", "description": "Caller-provided internal code, unique within your institution. Omit to leave unchanged; send null to clear.", "examples": [ "EMR-99999" ] } }, "type": "object", "title": "PatientUpdateRequest", "description": "Request body for updating a patient. All fields optional; at least one required.\n\nThe national identity (idCountry/idType/idValue) is not editable here \u2014 it stays\nthe deduplication key. `internalCode` follows PATCH semantics: omit to leave it\nunchanged, send null to clear it.", "examples": [ { "internalCode": "EMR-99999", "name": "Jane Doe" } ] }, "RegenerateApiKeyRequest": { "properties": { "validForDays": { "anyOf": [ { "type": "integer", "maximum": 365.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Validfordays", "description": "New key lifetime in days (1\u2013365). Omit to keep the account's default lifetime.", "examples": [ 365 ] } }, "type": "object", "title": "RegenerateApiKeyRequest", "description": "Request body for regenerating (rotating) a doctor account's API key.", "examples": [ { "validForDays": 365 } ] }, "RegenerateApiKeyResponse": { "properties": { "accountId": { "type": "string", "title": "Accountid", "description": "Account publicId (acc_*) the key belongs to.", "examples": [ "acc_a1b2c3d4e5f6g7h8" ] }, "apiKey": { "type": "string", "title": "Apikey", "description": "Raw API key. Shown only once \u2014 store it securely.", "examples": [ "" ] }, "id": { "type": "string", "title": "Id", "description": "API key publicId (ak_*).", "examples": [ "ak_a1b2c3d4e5f6g7h8" ] }, "prefix": { "type": "string", "title": "Prefix", "description": "Non-secret key prefix, safe to display/store for identification.", "examples": [ "sk_prod_a1b2c3d4...e5f6" ] }, "mode": { "type": "string", "title": "Mode", "examples": [ "prod" ] }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expiresat", "examples": [ "2027-01-15T10:30:00Z" ] } }, "type": "object", "required": [ "accountId", "apiKey", "id", "prefix", "mode" ], "title": "RegenerateApiKeyResponse", "description": "Response after rotating a doctor account's API key.\n\nMirrors the API-key fields returned on account creation, for the rotated key.\nThe raw key is shown only once \u2014 store it securely.", "examples": [ { "accountId": "acc_a1b2c3d4e5f6g7h8", "apiKey": "", "expiresAt": "2027-01-15T10:30:00Z", "id": "ak_a1b2c3d4e5f6g7h8", "mode": "prod", "prefix": "sk_prod_a1b2c3d4...e5f6" } ] }, "ReportState": { "properties": { "lifecycleStatus": { "type": "string", "title": "Lifecyclestatus", "description": "`draft` while the radiologist still works on the report. `final` once they sign it. `amended` after they change a report they already signed. Read a report as clinically complete only when the status is `final` or `amended`. Treat any other value the same way you treat `draft`: this field can take a new value in the future, and a value you do not know never means that the report is ready.", "examples": [ "final" ] }, "revision": { "type": "integer", "title": "Revision", "description": "Counter of the changes applied to this report. It only increases. Use it to tell two versions of the same report apart, for example to know that an amendment is newer than the copy you hold.", "examples": [ 7 ] } }, "type": "object", "required": [ "lifecycleStatus", "revision" ], "title": "ReportState", "description": "Workflow state of a dictated report.\n\nOnly a dictated report carries this state. Every other record \u2014 the record\nof an ordinary Scribe consultation, for example \u2014 has no workflow, and\n`reportState` is null for it." }, "RotateSecretResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "url": { "type": "string", "title": "Url" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Optional human-readable label, or null if unset." }, "events": { "items": { "$ref": "#/components/schemas/WebhookEventName" }, "type": "array", "title": "Events" }, "event": { "anyOf": [ { "$ref": "#/components/schemas/WebhookEventName" }, { "type": "null" } ], "description": "Deprecated: the first subscribed event (events[0]). Use `events`.", "deprecated": true }, "isActive": { "type": "boolean", "title": "Isactive" }, "signingSecretPrefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signingsecretprefix", "description": "Display hint for the signing secret (e.g. 'whsec_a1b2c3d4'). The raw secret is only returned at creation/rotation." }, "signingSecretVersion": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Signingsecretversion" }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Createdat" }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updatedat" }, "deletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deletedat" }, "signingSecret": { "type": "string", "title": "Signingsecret", "description": "Raw HMAC signing secret. Shown once at creation \u2014 store it now; it is never retrievable again. Use it to verify the X-Scribe-Api-Signature header." } }, "type": "object", "required": [ "id", "url", "events", "isActive", "signingSecret" ], "title": "RotateSecretResponse", "description": "Rotate response \u2014 same shape as create; carries the new raw secret once." }, "ScribeSessionConfigItem": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "description": "Stable public identifier for the configuration.", "examples": [ "ssc_a1b2c3d4e5f6g7h8" ] }, "name": { "type": "string", "title": "Name", "description": "Display name of the scribe session configuration.", "examples": [ "Cardiology Consultation" ] } }, "type": "object", "required": [ "name" ], "title": "ScribeSessionConfigItem", "description": "A single scribe session configuration." }, "ScribeSessionConfigListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ScribeSessionConfigItem" }, "type": "array", "title": "Items", "description": "List of scribe session configurations." }, "total": { "type": "integer", "title": "Total", "description": "Total number of configurations." }, "page": { "type": "integer", "title": "Page", "description": "Current page number." }, "limit": { "type": "integer", "title": "Limit", "description": "Number of items per page." }, "totalPages": { "type": "integer", "title": "Totalpages", "description": "Total number of pages." } }, "type": "object", "required": [ "items", "total", "page", "limit", "totalPages" ], "title": "ScribeSessionConfigListResponse", "description": "Response body for listing scribe session configurations.", "examples": [ { "items": [ { "id": "ssc_a1b2c3d4e5f6g7h8", "name": "Cardiology Consultation" }, { "id": "ssc_i9j0k1l2m3n4o5p6", "name": "General Medicine" } ], "limit": 20, "page": 1, "total": 2, "totalPages": 1 } ] }, "ScribeSessionModality": { "type": "string", "enum": [ "IN_PERSON", "TELEMEDICINE", "DICTATION" ], "title": "ScribeSessionModality", "description": "Supported scribe session modalities." }, "Section": { "properties": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/StringSchema" }, { "$ref": "#/components/schemas/NumberSchema" }, { "$ref": "#/components/schemas/BooleanSchema" }, { "$ref": "#/components/schemas/ObjectSchema" }, { "$ref": "#/components/schemas/ArraySchema" }, { "$ref": "#/components/schemas/CodeSchema" }, { "$ref": "#/components/schemas/CodeListSchema" }, { "$ref": "#/components/schemas/DerivedSchema" } ], "title": "Schema" }, "systemPrompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Systemprompt" }, "instructionSet": { "anyOf": [ { "$ref": "#/components/schemas/InstructionSetRef" }, { "type": "null" } ] }, "join": { "type": "boolean", "title": "Join", "description": "When False, the section always runs as its own LangGraph node instead of being batched with peers that share the same prompt strategy. Use this for sections whose per-instance content (e.g. distinct `templateN` bodies) would be lost in a merged LLM call.", "default": true } }, "type": "object", "required": [ "schema" ], "title": "Section", "description": "A single section in the medical record configuration.\n\nPairs an output schema with optional generation instructions." }, "SessionScribeLookupResponse": { "properties": { "id": { "type": "string", "maxLength": 255, "title": "Id", "examples": [ "ss_a1b2c3d4e5f6g7h8" ] }, "status": { "type": "string", "maxLength": 255, "title": "Status", "examples": [ "completed" ] }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Createdat", "examples": [ "2026-02-20T10:00:00Z" ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completedat", "examples": [ "2026-02-20T10:30:00Z" ] }, "patientName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Patientname", "examples": [ "John Doe" ] }, "scribeSessionModality": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scribesessionmodality", "description": "The modality of the scribe session (e.g. 'IN_PERSON', 'TELEMEDICINE').", "examples": [ "IN_PERSON" ] }, "consultationInternalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Consultationinternalid", "description": "The consultation ID provided by the API consumer.", "examples": [ "CONSULT-12345" ] }, "specialty": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Specialty", "description": "The medical specialty of the clinician who conducted the session.", "examples": [ "Cardiology" ] } }, "type": "object", "required": [ "id", "status" ], "title": "SessionScribeLookupResponse", "description": "Response body for session scribe lookup.", "examples": [ { "completedAt": "2026-02-20T10:30:00Z", "consultationInternalId": "CONSULT-12345", "createdAt": "2026-02-20T10:00:00Z", "id": "ss_a1b2c3d4e5f6g7h8", "patientName": "John Doe", "scribeSessionModality": "IN_PERSON", "specialty": "Cardiology", "status": "completed" } ] }, "SessionStartLabel": { "type": "string", "enum": [ "consultation", "reading" ], "title": "SessionStartLabel", "description": "Wording the scribe clients use on the start-session button." }, "SetConsultationContextRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 500, "minLength": 1 }, { "type": "null" } ], "title": "Name", "examples": [ "John Doe" ] }, "idCountry": { "anyOf": [ { "$ref": "#/components/schemas/IdCountry" }, { "type": "null" } ], "examples": [ "CO" ] }, "idType": { "anyOf": [ { "$ref": "#/components/schemas/IdType" }, { "type": "null" } ], "examples": [ "CC" ] }, "idValue": { "anyOf": [ { "type": "string", "maxLength": 50, "minLength": 1 }, { "type": "null" } ], "title": "Idvalue", "examples": [ "123456789" ] }, "patientId": { "anyOf": [ { "type": "string", "pattern": "^sp_[a-z0-9]{16}$" }, { "type": "null" } ], "title": "Patientid", "description": "Public id of an existing patient (sp_...). When provided, the patient's stored identity is used and the inline identity fields (name, idCountry, idType, idValue) must be omitted. Mutually exclusive with the inline identity.", "examples": [ "sp_a1b2c3d4e5f6g7h8" ] }, "internalCode": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1 }, { "type": "null" } ], "title": "Internalcode", "description": "Your own patient code, unique per institution. Looks up an existing patient by this code; when none matches, the inline identity (name, idCountry, idType, idValue) creates and tags the patient at session start. Mutually exclusive with patientId.", "examples": [ "MRN-000123" ] }, "notes": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ], "title": "Notes", "examples": [ "Patient reports headache" ] }, "pastMedicalHistory": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ], "title": "Pastmedicalhistory", "examples": [ "Hypertension, Diabetes Type 2" ] }, "consultationInternalId": { "anyOf": [ { "type": "string", "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]{1,128}$" }, { "type": "null" } ], "title": "Consultationinternalid", "examples": [ "CONSULT-12345" ] }, "scribeSessionModality": { "anyOf": [ { "$ref": "#/components/schemas/ScribeSessionModality" }, { "type": "null" } ], "examples": [ "IN_PERSON" ] }, "institutionalBranchId": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Institutionalbranchid", "description": "Id of the institution branch for this consultation, returned by the create-branch endpoint. Stamped onto the scribe session at creation. Provide the id or the name.", "examples": [ "b1f2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d" ] }, "institutionalBranch": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "title": "Institutionalbranch", "description": "Name of the institution branch for this consultation. Resolved when institutionalBranchId is not provided. Provide the id or the name.", "examples": [ "Sede Norte" ] }, "scribeSessionConfigurationId": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Scribesessionconfigurationid", "description": "Public id of a scribe session configuration (`ssc_` + 16 chars `[a-z0-9]`). Mutually exclusive with `medicalRecordConfigurationId` and `medicalRecordConfiguration`.", "examples": [ "ssc_a1b2c3d4e5f6g7h8" ] }, "medicalRecordConfigurationId": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Medicalrecordconfigurationid", "description": "Public id of a medical record configuration (`mrc_` + 16 chars `[a-z0-9]`). Mutually exclusive with `scribeSessionConfigurationId` and `medicalRecordConfiguration`.", "examples": [ "mrc_a1b2c3d4e5f6g7h8" ] }, "medicalRecordConfiguration": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Medicalrecordconfiguration", "description": "Inline medical record configuration JSON keyed by section name (e.g. 'chiefComplaint'). Auto-persisted and deduplicated by content hash; the resolved configuration id is attached to the doctor context buffer. Mutually exclusive with `medicalRecordConfigurationId` and `scribeSessionConfigurationId`." } }, "type": "object", "title": "SetConsultationContextRequest", "description": "Request body for setting consultation context.", "examples": [ { "consultationInternalId": "CONSULT-12345", "idCountry": "COLOMBIA", "idType": "PASSPORT", "idValue": "A12345678", "institutionalBranchId": "b1f2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "internalCode": "MRN-000123", "medicalRecordConfigurationId": "mrc_a1b2c3d4e5f6g7h8", "name": "John Doe", "notes": "Patient prefers morning appointments. Allergic to penicillin.", "pastMedicalHistory": "Hypertension diagnosed 2020. Diabetes Type 2 controlled with metformin.", "scribeSessionModality": "IN_PERSON" }, { "consultationInternalId": "CONSULT-12345", "idCountry": "COLOMBIA", "idType": "PASSPORT", "idValue": "A12345678", "medicalRecordConfiguration": { "chiefComplaint": { "instructionSet": { "telepatiaPromptId": "CHIEF_COMPLAINT" }, "schema": { "instructions": "Chief complaint", "properties": { "chiefComplaint": { "instructions": "Patient's own words", "type": "string" } }, "type": "object" } } }, "name": "John Doe", "scribeSessionModality": "IN_PERSON" }, { "consultationInternalId": "CONSULT-12345", "idCountry": "COLOMBIA", "idType": "PASSPORT", "idValue": "A12345678", "name": "John Doe", "scribeSessionConfigurationId": "ssc_a1b2c3d4e5f6g7h8", "scribeSessionModality": "IN_PERSON" }, { "consultationInternalId": "CONSULT-12345", "patientId": "sp_a1b2c3d4e5f6g7h8", "scribeSessionConfigurationId": "ssc_a1b2c3d4e5f6g7h8", "scribeSessionModality": "IN_PERSON" }, { "consultationInternalId": "CONSULT-12345", "institutionalBranchId": "b1f2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "internalCode": "MRN-000123", "scribeSessionConfigurationId": "ssc_a1b2c3d4e5f6g7h8", "scribeSessionModality": "IN_PERSON" } ] }, "SetConsultationContextResponse": { "properties": { "success": { "type": "boolean", "title": "Success", "examples": [ true ] }, "consultationInternalId": { "type": "string", "title": "Consultationinternalid", "examples": [ "CONSULT-12345" ] } }, "type": "object", "required": [ "success", "consultationInternalId" ], "title": "SetConsultationContextResponse", "description": "Response body for setting consultation context.", "examples": [ { "consultationInternalId": "CONSULT-12345", "success": true } ] }, "SsoExchangeRequest": { "properties": { "samlResponse": { "type": "string", "title": "Samlresponse", "description": "Base64-encoded SAML Response issued by the institution's IdP.", "examples": [ "PHNhbWxwOlJlc3BvbnNl...==" ] } }, "type": "object", "required": [ "samlResponse" ], "title": "SsoExchangeRequest", "description": "The institution posts the base64 SAML assertion; the institution key rides in\nthe ``Authorization`` header." }, "SsoExchangeResponse": { "properties": { "documentId": { "type": "string", "title": "Documentid" }, "token": { "$ref": "#/components/schemas/SsoToken" } }, "type": "object", "required": [ "documentId", "token" ], "title": "SsoExchangeResponse", "description": "A doctor session \u2014 use ``token.accessToken`` on every business call." }, "SsoRefreshRequest": { "properties": { "refreshToken": { "type": "string", "title": "Refreshtoken", "description": "The refreshToken returned by /v1/sso/exchange (or a prior refresh)." } }, "type": "object", "required": [ "refreshToken" ], "title": "SsoRefreshRequest", "description": "Rotate a doctor session with the refresh token from a prior exchange/refresh." }, "SsoToken": { "properties": { "accessToken": { "type": "string", "title": "Accesstoken" }, "expiresIn": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Expiresin" }, "refreshToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Refreshtoken" } }, "type": "object", "required": [ "accessToken" ], "title": "SsoToken", "description": "The doctor session token minted from the assertion." }, "StringSchema": { "properties": { "type": { "type": "string", "const": "string", "title": "Type" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "enum": { "anyOf": [ { "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/EnumOption" } ] }, "type": "array" }, { "type": "null" } ], "title": "Enum" }, "examples": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Examples" }, "template": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Template" }, "pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pattern" }, "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Format" }, "required": { "type": "boolean", "title": "Required", "default": false }, "default": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default" } }, "type": "object", "required": [ "type" ], "title": "StringSchema", "description": "Schema for string-valued outputs." }, "TelepatiaPromptId": { "type": "string", "enum": [ "IDENTIFICATION", "CHIEF_COMPLAINT", "HISTORY_OF_PRESENT_ILLNESS", "REVIEW_OF_SYSTEMS", "PAST_MEDICAL_HISTORY", "PAST_MEDICAL_GYNECOLOGICAL_HISTORY", "VITAL_SIGNS", "ANTHROPOMETRIC_MEASURES", "PHYSICAL_EXAMINATION", "LABORATORY_AND_DIAGNOSTIC_TEST_RESULTS", "CURRENT_TREATMENT", "ASSESSMENT_PLAN", "RECOMMENDATION_WARNING_SIGNS", "PROCEDURE", "MEDICAL_ORDERS_GENERAL_ORDERS", "MEDICAL_ORDERS_INTERCONSULTATIONS", "MEDICAL_ORDERS_MEDICATIONS", "MEDICAL_ORDERS_DIAGNOSTIC_TESTS", "MEDICAL_ORDERS_REFERRALS", "MEDICAL_ORDERS_FOLLOW_UPS", "MEDICAL_ORDERS_NON_PHARMACOLOGICAL", "MEDICAL_ORDERS_WARNING_SIGNS", "MEDICAL_ORDERS_MEDICAL_LEAVES", "MEDICAL_ORDERS_INTERCONSULTATIONS_AND_REFERRALS", "MEDICAL_ORDERS_PROCEDURES_OR_SURGERIES", "MEDICAL_ORDERS_MEDICAL_DEVICES", "SUBJECTIVE", "OBJECTIVE", "DIAGNOSIS", "SUMMARY", "TEMPLATE", "CHIEF_COMPLAINT_TRIAGE", "EXTRA_ORAL_EXAMINATION", "INTRA_ORAL_EXAMINATION", "ODONTOGRAM", "HISTORY_OF_PRESENT_ILLNESS_PSYCHOLOGY", "PAST_MEDICAL_HISTORY_PSYCHOLOGY", "COGNITIVE_BEHAVIORAL_EMOTIONAL_FUNCTIONAL_STATUS", "MENTAL_EXAMINATION", "MENTAL_EXAM", "FUNCTIONAL_COGNITIVE_SPIRITUAL_ASSESSMENT", "PSYCHOLOGY_ADJUSTMENT_AREA", "PSYCHOLOGY_GENOGRAM", "ASSESSMENT_PLAN_PSYCHOLOGY", "PAST_MEDICAL_CONDITIONS_CARDIOVASCULAR_RISK", "CARDIOVASCULAR_RISK", "PAST_MEDICAL_CONDITIONS_PRENATAL_CARE", "PRENATAL_CARE_PARTNER", "PRENATAL_CARE_GYNECOLOGICAL_HISTORY", "PRENATAL_CARE_LABORATORY_AND_DIAGNOSTIC_TEST_RESULTS", "INTEGRATED_HEALTH_CARE_ROUTES_AGING", "HEALTHY_LIFESTYLE" ], "title": "TelepatiaPromptId", "description": "Available Telepatia instruction set identifiers." }, "UpdateWebhookRequest": { "properties": { "url": { "anyOf": [ { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri" }, { "type": "null" } ], "title": "Url" }, "name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Name", "description": "Optional label. Send a non-empty value to set/replace it, or an empty string to clear it. Omit to leave it unchanged." }, "events": { "anyOf": [ { "items": { "$ref": "#/components/schemas/WebhookEventName" }, "type": "array" }, { "type": "null" } ], "title": "Events", "description": "Replace the subscribed event types (at least one). Preferred over `event`." }, "event": { "anyOf": [ { "$ref": "#/components/schemas/WebhookEventName" }, { "type": "null" } ], "description": "Deprecated: a single event type. Use `events`. When set and `events` is omitted, it replaces the subscription with a one-element list.", "deprecated": true }, "isActive": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Isactive", "description": "Pause/resume delivery without deleting the subscription." } }, "type": "object", "title": "UpdateWebhookRequest", "examples": [ { "events": [ "scribe_session.completed", "scribe_session.error" ], "isActive": true } ] }, "WebhookDeliveryStatus": { "type": "string", "enum": [ "pending", "processing", "delivered", "delivered_failed", "failed" ], "title": "WebhookDeliveryStatus" }, "WebhookEventLogResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "attempt": { "type": "integer", "title": "Attempt" }, "requestUrl": { "type": "string", "title": "Requesturl" }, "requestPayload": { "additionalProperties": true, "type": "object", "title": "Requestpayload" }, "responseStatus": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Responsestatus" }, "responseBody": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Responsebody" }, "durationMs": { "type": "integer", "title": "Durationms" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "succeeded": { "type": "boolean", "title": "Succeeded" }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Createdat" } }, "type": "object", "required": [ "id", "attempt", "requestUrl", "requestPayload", "durationMs", "succeeded" ], "title": "WebhookEventLogResponse", "description": "A single delivery attempt log line." }, "WebhookEventName": { "type": "string", "enum": [ "scribe_session.created", "scribe_session.completed", "scribe_session.error", "scribe_session.updated", "scribe_session.cancelled", "scribe_session.deleted", "appointment.fulfilled", "appointment.cancelled" ], "title": "WebhookEventName", "description": "Webhook event types exposed to API clients.\n\nMirrors `SynapseWebhookEventType` enum in datalayer (camelCase) but\nrendered to clients as snake_case dotted strings (closer to Stripe\nconvention and easier to grep in caller logs)." }, "WebhookEventResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "webhookId": { "type": "string", "title": "Webhookid" }, "event": { "$ref": "#/components/schemas/WebhookEventName" }, "status": { "$ref": "#/components/schemas/WebhookDeliveryStatus" }, "attempts": { "type": "integer", "title": "Attempts" }, "data": { "additionalProperties": true, "type": "object", "title": "Data" }, "lastAttemptAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lastattemptat" }, "deliveredAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deliveredat" }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Createdat" } }, "type": "object", "required": [ "id", "webhookId", "event", "status", "attempts", "data" ], "title": "WebhookEventResponse", "description": "A queued/delivered webhook event." }, "WebhookEventsPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/WebhookEventResponse" }, "type": "array", "title": "Items" }, "total": { "type": "integer", "title": "Total" }, "page": { "type": "integer", "title": "Page" }, "limit": { "type": "integer", "title": "Limit" } }, "type": "object", "required": [ "items", "total", "page", "limit" ], "title": "WebhookEventsPage" }, "WebhookResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "url": { "type": "string", "title": "Url" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Optional human-readable label, or null if unset." }, "events": { "items": { "$ref": "#/components/schemas/WebhookEventName" }, "type": "array", "title": "Events" }, "event": { "anyOf": [ { "$ref": "#/components/schemas/WebhookEventName" }, { "type": "null" } ], "description": "Deprecated: the first subscribed event (events[0]). Use `events`.", "deprecated": true }, "isActive": { "type": "boolean", "title": "Isactive" }, "signingSecretPrefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signingsecretprefix", "description": "Display hint for the signing secret (e.g. 'whsec_a1b2c3d4'). The raw secret is only returned at creation/rotation." }, "signingSecretVersion": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Signingsecretversion" }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Createdat" }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updatedat" }, "deletedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deletedat" } }, "type": "object", "required": [ "id", "url", "events", "isActive" ], "title": "WebhookResponse", "description": "A single webhook subscription." }, "ErrorResponse": { "description": "Standardized error response envelope.", "properties": { "error": { "$ref": "#/components/schemas/ErrorDetailWithRequestId" } }, "required": [ "error" ], "title": "ErrorResponse", "type": "object" }, "ErrorDetailWithRequestId": { "description": "Top-level error object: :class:`ErrorDetail` plus the request correlation id.\n\nKept as a subclass rather than a field on ``ErrorDetail`` because ``ErrorDetail`` is\nalso the per-item error shape inside the batch account-creation response\n(``BatchAccountResult.error``), which is serialized with nulls included. Adding the\nfield there would publish ``\"requestId\": null`` on an HTTP 200, and there is only\never one request id per batch anyway -- batch callers read the ``X-Request-ID``\nresponse header.", "properties": { "type": { "description": "Broad error category for high-level handling.", "examples": [ "invalid_request_error" ], "title": "Type", "type": "string" }, "code": { "description": "Machine-readable error code. Clients should switch on this value.", "examples": [ "parameter_invalid" ], "title": "Code", "type": "string" }, "message": { "description": "Human-readable error message ending with a period.", "examples": [ "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code." ], "title": "Message", "type": "string" }, "param": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The request field that caused the error, if applicable.", "examples": [ "idCountry" ], "title": "Param" }, "details": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional structured, machine-readable context for the error.", "examples": [ { "pendingConsultations": [ { "sessionId": "abc123", "url": "https://..." } ] } ], "title": "Details" }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Unique id for this request, identical to the X-Request-ID response header. Quote it when contacting support.", "examples": [ "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30" ], "title": "Requestid" } }, "required": [ "type", "code", "message" ], "title": "ErrorDetailWithRequestId", "type": "object" }, "ConsultationInput": { "properties": { "id": { "type": "string", "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]{1,128}$", "title": "Id", "description": "Your consultation id, the key for every follow-up GET and webhook.", "examples": [ "CONSULT-12345" ] }, "modality": { "anyOf": [ { "type": "string", "enum": [ "IN_PERSON", "TELEMEDICINE" ] }, { "type": "null" } ], "title": "Modality", "examples": [ "IN_PERSON" ] } }, "type": "object", "required": [ "id" ], "title": "ConsultationInput", "description": "The caller's consultation reference." }, "ContextInput": { "properties": { "notes": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ], "title": "Notes", "examples": [ "Patient reports headache since Monday." ] }, "pastMedicalHistory": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ], "title": "Pastmedicalhistory", "examples": [ "Hypertension diagnosed 2020." ] } }, "type": "object", "title": "ContextInput", "description": "Free-text context that feeds record generation." }, "PatientDocument": { "properties": { "country": { "$ref": "#/components/schemas/IdCountry", "examples": [ "BR" ] }, "type": { "$ref": "#/components/schemas/IdType", "examples": [ "CPF" ] }, "value": { "type": "string", "maxLength": 50, "minLength": 1, "title": "Value", "examples": [ "123.456.789-00" ] } }, "type": "object", "required": [ "country", "type", "value" ], "title": "PatientDocument", "description": "The patient's identity document (same enums and rules as the rest of the API)." }, "PatientInput": { "properties": { "id": { "anyOf": [ { "type": "string", "pattern": "^sp_[a-z0-9]{16}$" }, { "type": "null" } ], "title": "Id", "description": "Public id of an existing patient (sp_...). Mutually exclusive with the inline identity.", "examples": [ "sp_a1b2c3d4e5f6g7h8" ] }, "name": { "anyOf": [ { "type": "string", "maxLength": 500, "minLength": 1 }, { "type": "null" } ], "title": "Name", "examples": [ "John Doe" ] }, "document": { "anyOf": [ { "$ref": "#/components/schemas/PatientDocument" }, { "type": "null" } ] } }, "type": "object", "title": "PatientInput", "description": "An existing patient by public id xor the inline identity." }, "TemplateInput": { "properties": { "id": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Id", "description": "Public id of an existing template, self-describing by prefix: `mrc_` (medicalRecordConfiguration) or `ssc_` (scribeSessionConfiguration).", "examples": [ "mrc_a1b2c3d4e5f6g7h8" ] }, "sections": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Sections", "description": "Inline structured template keyed by section name (e.g. 'chiefComplaint'). Auto-persisted and deduplicated by content hash. Mutually exclusive with `id`." } }, "type": "object", "title": "TemplateInput", "description": "Template selection: an existing public id xor an inline structured template." } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API key passed as a Bearer token" } } }, "servers": [ { "url": "https://scribe-api.telepatia.ai", "description": "Production" } ], "security": [ { "BearerAuth": [] } ] }