{ "openapi": "3.1.0", "info": { "title": "Scribe Public API", "description": "API REST externa para integraci\u00f3n con la plataforma Telepatia. Autent\u00edquese con claves API, establezca el contexto de consulta y consulte sesiones de scribe.", "version": "0.1.0" }, "paths": { "/v1/auth/login": { "post": { "tags": [ "Authentication" ], "summary": "Iniciar sesi\u00f3n", "description": "Iniciar sesi\u00f3n mediante clave API. Devuelve un c\u00f3digo de verificaci\u00f3n y una URL de redirecci\u00f3n.", "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": "Respuesta exitosa", "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": "Solicitud incorrecta \u2014 par\u00e1metros inv\u00e1lidos, fallos de validaci\u00f3n o campos faltantes.", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Establecer contexto de consulta", "description": "Establece el contexto de consulta para una sesi\u00f3n de paciente.", "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": "Respuesta exitosa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetConsultationContextResponse" }, "example": { "consultationInternalId": "CONSULT-12345", "success": true } } } }, "400": { "description": "Solicitud incorrecta \u2014 par\u00e1metros inv\u00e1lidos, fallos de validaci\u00f3n o campos faltantes.", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "No encontrado \u2014 el recurso solicitado no existe.", "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": "Conflicto \u2014 el recurso ya existe o est\u00e1 en estado conflictivo.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Consultar sesi\u00f3n de Scribe", "description": "Consulta una sesi\u00f3n de scribe por 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": "La sesi\u00f3n a buscar \u2014 su consultationInternalId, o el id de la sesi\u00f3n (ss_...) que la API devuelve.", "examples": [ "CONSULT-12345", "ss_sa98vgqyra91q5b8" ], "title": "Id" }, "description": "La sesi\u00f3n a buscar \u2014 su consultationInternalId, o el id de la sesi\u00f3n (ss_...) que la API devuelve." } ], "responses": { "200": { "description": "Respuesta exitosa", "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": "Solicitud incorrecta \u2014 par\u00e1metros inv\u00e1lidos, fallos de validaci\u00f3n o campos faltantes.", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "No encontrado \u2014 el recurso solicitado no existe.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Listar documentos de historia cl\u00ednica", "description": "Lista los documentos de historia cl\u00ednica producidos para una sesi\u00f3n de scribe.\n\nUn informe dictado (`purpose` 'report') tambi\u00e9n incluye `reportState`, que indica si el radi\u00f3logo lo firm\u00f3. Los dem\u00e1s registros no tienen flujo de trabajo, por lo que su `reportState` es null. Verifica `reportState.lifecycleStatus` antes de usar un informe: un `draft` no est\u00e1 completo y el radi\u00f3logo a\u00fan puede cambiarlo.", "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": "La sesi\u00f3n a buscar \u2014 su consultationInternalId, o el id de la sesi\u00f3n (ss_...) que la API devuelve.", "examples": [ "CONSULT-12345", "ss_sa98vgqyra91q5b8" ], "title": "Id" }, "description": "La sesi\u00f3n a buscar \u2014 su consultationInternalId, o el id de la sesi\u00f3n (ss_...) que la API devuelve." }, { "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": "Respuesta exitosa", "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": "Solicitud incorrecta \u2014 par\u00e1metros inv\u00e1lidos, fallos de validaci\u00f3n o campos faltantes.", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "Prohibido \u2014 la clave API no puede realizar esta operaci\u00f3n.", "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": "No encontrado \u2014 el recurso solicitado no existe.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Aceptar una alerta de CDSS", "description": "Registra la decisi\u00f3n del m\u00e9dico de aceptar una alerta de soporte a la decisi\u00f3n cl\u00ednica. El cambio aceptado se aplica a la historia cl\u00ednica de forma as\u00edncrona, por lo que una respuesta exitosa significa que la decisi\u00f3n se registr\u00f3, no que la historia ya se actualiz\u00f3.", "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": "Respuesta exitosa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CdssDecisionResponse" }, "example": { "elementId": "IBUPROFEN", "id": "cfa_bXJkLWFiYy0xMjMfSUJVUFJPRkVO", "status": "accepted" } } } }, "400": { "description": "Solicitud incorrecta \u2014 par\u00e1metros inv\u00e1lidos, fallos de validaci\u00f3n o campos faltantes.", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "Prohibido \u2014 la clave API no puede realizar esta operaci\u00f3n.", "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": "No encontrado \u2014 el recurso solicitado no existe.", "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": "Conflicto \u2014 el recurso ya existe o est\u00e1 en estado conflictivo.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Registrar decisiones para varias alertas de CDSS", "description": "Acepta o rechaza varias alertas de soporte a la decisi\u00f3n cl\u00ednica en una sola llamada. Cada alerta se valida antes de registrar cualquier decisi\u00f3n, por lo que un lote que contenga una alerta inutilizable no cambia nada. Los cambios aceptados se aplican a la historia cl\u00ednica de forma as\u00edncrona.", "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": "Respuesta exitosa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CdssDecisionsResponse" }, "example": { "decisions": [ { "elementId": "IBUPROFEN", "id": "cfa_bXJkLWFiYy0xMjMfSUJVUFJPRkVO", "status": "accepted" } ] } } } }, "400": { "description": "Solicitud incorrecta \u2014 par\u00e1metros inv\u00e1lidos, fallos de validaci\u00f3n o campos faltantes.", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "Prohibido \u2014 la clave API no puede realizar esta operaci\u00f3n.", "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": "No encontrado \u2014 el recurso solicitado no existe.", "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": "Conflicto \u2014 el recurso ya existe o est\u00e1 en estado conflictivo.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Rechazar una alerta de CDSS", "description": "Registra la decisi\u00f3n del m\u00e9dico de rechazar una alerta de soporte a la decisi\u00f3n cl\u00ednica. La historia cl\u00ednica no se modifica.", "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": "Respuesta exitosa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CdssDecisionResponse" }, "example": { "elementId": "IBUPROFEN", "id": "cfa_bXJkLWFiYy0xMjMfSUJVUFJPRkVO", "status": "accepted" } } } }, "400": { "description": "Solicitud incorrecta \u2014 par\u00e1metros inv\u00e1lidos, fallos de validaci\u00f3n o campos faltantes.", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "Prohibido \u2014 la clave API no puede realizar esta operaci\u00f3n.", "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": "No encontrado \u2014 el recurso solicitado no existe.", "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": "Conflicto \u2014 el recurso ya existe o est\u00e1 en estado conflictivo.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Listar configuraciones de sesi\u00f3n de scribe", "description": "Lista todas las configuraciones de sesi\u00f3n de scribe de la cuenta autenticada.", "operationId": "api_scribe_session_configurations_listed_v1_scribe_session_configurations_get", "responses": { "200": { "description": "Respuesta exitosa", "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": "Solicitud incorrecta \u2014 par\u00e1metros inv\u00e1lidos, fallos de validaci\u00f3n o campos faltantes.", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Crear una Smart Template", "description": "Registra una Smart Template (configuraci\u00f3n de historia cl\u00ednica). Idempotente por hash de contenido: configuraciones id\u00e9nticas para la misma cuenta devuelven el id existente con `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": "Respuesta exitosa", "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": "Solicitud incorrecta \u2014 par\u00e1metros inv\u00e1lidos, fallos de validaci\u00f3n o campos faltantes.", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "Conflicto \u2014 el recurso ya existe o est\u00e1 en estado conflictivo.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Listar Smart Templates", "description": "Lista las Smart Templates visibles para el llamador autenticado, paginadas.", "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": "Respuesta exitosa", "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": "Solicitud incorrecta \u2014 par\u00e1metros inv\u00e1lidos, fallos de validaci\u00f3n o campos faltantes.", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Consultar una Smart Template por ID", "description": "Consulta una Smart Template por su identificador p\u00fablico.", "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": "Respuesta exitosa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MrcDetailResponse" } } } }, "401": { "description": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "No encontrado \u2014 el recurso solicitado no existe.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Eliminar una Smart Template", "description": "Elimina de forma l\u00f3gica una Smart Template por su identificador p\u00fablico. La plantilla desaparece de la lista por defecto; las consultas hist\u00f3ricas que la referenciaron no se ven afectadas. Se bloquea con un 409 mientras una sesi\u00f3n de scribe vinculada sigue en proceso.", "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": "Solicitud incorrecta \u2014 par\u00e1metros inv\u00e1lidos, fallos de validaci\u00f3n o campos faltantes.", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "Prohibido \u2014 la clave API no puede realizar esta operaci\u00f3n.", "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": "No encontrado \u2014 el recurso solicitado no existe.", "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": "Conflicto \u2014 el recurso ya existe o est\u00e1 en estado conflictivo.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Agendar una cita", "description": "Crea una consulta agendada (idempotente por consultationInternalId). Devuelve la cita con su id p\u00fablico estable (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": "Respuesta exitosa", "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": "Solicitud incorrecta \u2014 par\u00e1metros inv\u00e1lidos, fallos de validaci\u00f3n o campos faltantes.", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "Prohibido \u2014 la clave API no puede realizar esta operaci\u00f3n.", "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": "No encontrado \u2014 el recurso solicitado no existe.", "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": "Conflicto \u2014 el recurso ya existe o est\u00e1 en estado conflictivo.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Listar citas (agenda)", "description": "Lista las citas visibles para el llamador, ordenadas por hora de inicio, con filtros de rango de inicio y estado, paginadas.", "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": "Respuesta exitosa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentListResponse" } } } }, "400": { "description": "Solicitud incorrecta \u2014 par\u00e1metros inv\u00e1lidos, fallos de validaci\u00f3n o campos faltantes.", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Consultar una cita por ID", "description": "Consulta una cita por su id p\u00fablico (apt_) o el consultationInternalId que enviaste al crearla.", "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": "Respuesta exitosa", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "No encontrado \u2014 el recurso solicitado no existe.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Actualizar una cita", "description": "Cancela una reserva o la marca como ausencia, o repara un enlace de sesi\u00f3n perdido. Solo cancelled y noshow son configurables por el cliente.", "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": "Respuesta exitosa", "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": "Solicitud incorrecta \u2014 par\u00e1metros inv\u00e1lidos, fallos de validaci\u00f3n o campos faltantes.", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "Prohibido \u2014 la clave API no puede realizar esta operaci\u00f3n.", "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": "No encontrado \u2014 el recurso solicitado no existe.", "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": "Conflicto \u2014 el recurso ya existe o est\u00e1 en estado conflictivo.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Crear un paciente", "description": "Crea un paciente a partir de los mismos campos de identidad usados por set-consultation-context. Devuelve el paciente con su id p\u00fablico estable.", "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": "Respuesta exitosa", "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": "Solicitud incorrecta \u2014 par\u00e1metros inv\u00e1lidos, fallos de validaci\u00f3n o campos faltantes.", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "Conflicto \u2014 el recurso ya existe o est\u00e1 en estado conflictivo.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Listar pacientes", "description": "Lista los pacientes visibles para el llamador autenticado, paginados.", "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": "Respuesta exitosa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientListResponse" } } } }, "400": { "description": "Solicitud incorrecta \u2014 par\u00e1metros inv\u00e1lidos, fallos de validaci\u00f3n o campos faltantes.", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Consultar un paciente por ID", "description": "Consulta un paciente por su identificador p\u00fablico.", "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": "Respuesta exitosa", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "No encontrado \u2014 el recurso solicitado no existe.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Actualizar un paciente", "description": "Actualiza el nombre o el internalCode de un paciente. La identidad nacional no es editable aqu\u00ed.", "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": "Respuesta exitosa", "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": "Solicitud incorrecta \u2014 par\u00e1metros inv\u00e1lidos, fallos de validaci\u00f3n o campos faltantes.", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "Prohibido \u2014 la clave API no puede realizar esta operaci\u00f3n.", "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": "No encontrado \u2014 el recurso solicitado no existe.", "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": "Conflicto \u2014 el recurso ya existe o est\u00e1 en estado conflictivo.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Eliminar un paciente", "description": "Elimina un paciente por su id p\u00fablico o internalCode (derecho al olvido). Devuelve 204.", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "Prohibido \u2014 la clave API no puede realizar esta operaci\u00f3n.", "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": "No encontrado \u2014 el recurso solicitado no existe.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Listar las sesiones de scribe de un paciente", "description": "Lista las sesiones de scribe de un paciente, paginadas. El id del paciente puede ser el id p\u00fablico (sp_...) o el internalCode que definiste para tu instituci\u00f3n.", "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": "Respuesta exitosa", "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": "Solicitud incorrecta \u2014 par\u00e1metros inv\u00e1lidos, fallos de validaci\u00f3n o campos faltantes.", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "No encontrado \u2014 el recurso solicitado no existe.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Consultar la auditor\u00eda de una sesi\u00f3n", "description": "Devuelve la auditor\u00eda de calidad de una sesi\u00f3n de scribe: la puntuaci\u00f3n (0..1), la calificaci\u00f3n y el desglose por secciones.", "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": "La sesi\u00f3n a buscar \u2014 su consultationInternalId, o el id de la sesi\u00f3n (ss_...) que la API devuelve.", "examples": [ "CONSULT-12345", "ss_sa98vgqyra91q5b8" ], "title": "Id" }, "description": "La sesi\u00f3n a buscar \u2014 su consultationInternalId, o el id de la sesi\u00f3n (ss_...) que la API devuelve." } ], "responses": { "200": { "description": "Respuesta exitosa", "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": "Solicitud incorrecta \u2014 par\u00e1metros inv\u00e1lidos, fallos de validaci\u00f3n o campos faltantes.", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "Prohibido \u2014 la clave API no puede realizar esta operaci\u00f3n.", "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": "No encontrado \u2014 el recurso solicitado no existe.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Solicitud incorrecta \u2014 par\u00e1metros inv\u00e1lidos, fallos de validaci\u00f3n o campos faltantes.", "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": "No autorizado \u2014 clave API faltante o inv\u00e1lida.", "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": "Prohibido \u2014 la clave API no puede realizar esta operaci\u00f3n.", "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": "No encontrado \u2014 el recurso solicitado no existe.", "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": "Conflicto \u2014 el recurso ya existe o est\u00e1 en estado conflictivo.", "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": "Servicio no disponible \u2014 una dependencia externa no est\u00e1 disponible.", "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": "Declaraci\u00f3n de una lista de c\u00f3digos dentro de un objeto. Conserva system, los nombres de origen hermanos y maxOptions. Esta API no persiste maxItems." }, "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": "Declaraci\u00f3n de un c\u00f3digo de cat\u00e1logo dentro de un objeto. Conserva system, los nombres de origen hermanos y maxOptions para la resoluci\u00f3n posterior a la generaci\u00f3n." }, "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": "Cuerpo de solicitud para registrar una configuraci\u00f3n de historia cl\u00ednica \u2014 un mapa de clave de secci\u00f3n a definici\u00f3n de secci\u00f3n.", "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": "Cuerpo de respuesta al registrar una configuraci\u00f3n de historia cl\u00ednica.", "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": "Detalle del error con c\u00f3digos legibles por m\u00e1quina y mensaje legible por humanos.", "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": "Tipos de documento de identificaci\u00f3n de paciente soportados." }, "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": "Cuerpo de solicitud de inicio de sesi\u00f3n.", "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": "Respuesta de inicio de sesi\u00f3n con c\u00f3digo de verificaci\u00f3n y URL de redirecci\u00f3n.", "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": "Esquema recursivo de plantilla devuelto por GET, con propiedades anidadas, elementos de array y configuraci\u00f3n de codificaci\u00f3n. Los nombres de origen se devuelven como lista." }, "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": "Modalidades de sesi\u00f3n de scribe soportadas." }, "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": "Cuerpo de respuesta para la consulta de sesi\u00f3n de scribe.", "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": "Cuerpo de solicitud para establecer el contexto de consulta.", "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": "Cuerpo de respuesta para establecer el contexto de consulta.", "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": "Envoltorio estandarizado de respuesta de error.", "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": "Clave API enviada como token Bearer" } } }, "servers": [ { "url": "https://scribe-api.telepatia.ai", "description": "Production" } ], "security": [ { "BearerAuth": [] } ] }