Miracle API v1

Autofill y workflows para aplicaciones cliente

Contrato publico para detectar campos, entrenar workflows en Neo4j y llenar UI desde una nota clinica organizada.

Modelo mental

El cliente detecta la UI y ejecuta el llenado. Miracle decide que valor de la nota corresponde a cada campo y guarda workflows aprendidos para reutilizar el mapa de la pantalla.

No hay control remoto del dispositivo. El backend devuelve matches y planes estructurados; la app cliente aplica esos resultados con sus propias validaciones.

Autenticacion

X-API-Key: <TU_API_KEY>

Todas las rutas bajo /api/v1 requieren API key permanente. Tambien se acepta Authorization: Bearer <TU_API_KEY>.

Detectar campos

Antes de llamar autofill, el cliente debe construir una lista de campos visibles y accionables.

Campo	Descripcion
`stepOrder`	Indice estable usado para devolver el match.
`actionType`	`input`, `select`, `click` o `navigation`.
`selector`	Selector que el cliente puede ejecutar despues.
`label`	Texto visible, aria-label, placeholder o nombre semantico.
`controlType`	Tipo de control: text, textarea, select, checkbox, date.
`allowedOptions`	Opciones disponibles para selects o radios.
`currentValue`	Valor actual para evitar sobrescribir sin necesidad.

Autofill directo

POST __BASE__/api/v1/autofill/match

{
  "session_id": "encounter-123",
  "page_url": "https://cliente.example/emr",
  "note_content": "## Historia\nPaciente con dolor de rodilla derecha...",
  "fields": [
    {
      "stepOrder": 1,
      "actionType": "input",
      "selector": "#chief-complaint",
      "label": "Chief complaint",
      "controlType": "text",
      "currentValue": ""
    }
  ],
  "already_fulfilled": []
}

{
  "autofill": {
    "matches": [
      {
        "stepOrder": 1,
        "value": "Dolor de rodilla derecha",
        "confidence": 0.91,
        "evidence": "dolor de rodilla derecha"
      }
    ],
    "ready_to_submit": false
  }
}

Entrenar workflows

1. Iniciar sesion

POST __BASE__/api/v1/learning/sessions

{
  "description": "Autofill intake note in Acme EMR",
  "app_id": "acme-emr",
  "source_url": "https://cliente.example/emr/intake",
  "source_origin": "https://cliente.example",
  "source_pathname": "/emr/intake",
  "source_title": "Intake",
  "context": { "surface": "expanded-emr" }
}

2. Registrar pasos

POST __BASE__/api/v1/learning/sessions/:id/steps

{
  "actionType": "input",
  "selector": "#chief-complaint",
  "label": "Chief complaint",
  "controlType": "text",
  "value": "Dolor de rodilla derecha",
  "semanticTarget": "chief complaint",
  "surfaceSection": "intake"
}

3. Adjuntar contexto opcional

POST __BASE__/api/v1/learning/sessions/:id/context-notes

{
  "note": {
    "role": "clinical_context",
    "transcript": "este workflow llena motivo de consulta, lateralidad y plan",
    "mode": "training"
  }
}

4. Finalizar

POST __BASE__/api/v1/learning/sessions/:id/finish

El backend persiste el workflow y devuelve workflow_id, summary y el workflow cuando este disponible.

Usar workflows aprendidos

GET  __BASE__/api/v1/workflows
GET  __BASE__/api/v1/workflows/:id
POST __BASE__/api/v1/workflows/:id/plan

{
  "variables": { "input_1": "Dolor de rodilla derecha" },
  "execution_intent": { "source": "autofill", "encounter_id": "enc-123" }
}

El plan devuelve pasos ejecutables. La app cliente decide como aplicarlos en su DOM, WebView, app nativa o automatizacion local.