AI Pilot API

Maintainer: Aether365 Team Destinatari: Sviluppatori Ambito: Endpoint di remediation di AI Pilot - generare, esaminare e applicare correzioni automatiche

AI Pilot trasforma i risultati falliti delle scansioni Compliance ed Exposure in correzioni automatiche. Tramite l'API puoi generare un piano di remediation per una scansione, esaminare le modifiche proposte e applicare quelle che approvi. Applicare una correzione è sempre una chiamata esplicita da parte tua: nulla viene modificato finché non lo richiedi.

Requisiti

Gli endpoint di AI Pilot richiedono l'abilitazione AI Pilot (Pro o Enterprise) e una connessione Microsoft 365 collegata in modalità AI Pilot (write-consent). Una connessione di sola lettura può generare e leggere i piani, ma non può applicare correzioni. Le chiamate restituiscono 403 AUTH_INSUFFICIENT_SCOPE quando l'abilitazione è assente.

Elencare i check correggibili automaticamente

Restituisce gli ID dei check che AI Pilot sa correggere automaticamente. Usalo per decidere, controllo per controllo, se è disponibile una correzione automatica.

GET /tenants/me/remediation/capabilities

Esempio di risposta

{
  "success": true,
  "data": { "autoRemediableTestIds": ["AE.1068", "CIS.M365.5.1.2.3", "AE.1102"] }
}

---

Generare un piano di remediation

Costruisce un piano di remediation per una scansione completata: un elemento per ogni controllo fallito correggibile, ciascuno con il valore attuale, il valore sicuro proposto e l'impostazione a cui punta. La lettura del valore attuale usa l'ambito di lettura della connessione AI Pilot; non viene scritta alcuna modifica.

POST /tenants/me/scans/{scanId}/remediation-plan

Esempio di richiesta

curl -X POST https://api.aether365.io/tenants/me/scans/scan_abc123/remediation-plan \
  -H "Authorization: Bearer ak_live_..."

Esempio di risposta

{
  "success": true,
  "data": {
    "id": "plan_abc123",
    "scanId": "scan_abc123",
    "msTenantId": "00000000-0000-0000-0000-000000000000",
    "status": "pending",
    "createdAt": "2026-06-17T09:00:00Z",
    "items": [
      {
        "id": "item_1",
        "testId": "AE.1068",
        "coveredTestIds": ["AE.1068", "CIS.M365.5.1.2.3"],
        "actionKey": "require_mfa_admins",
        "title": "Require MFA for administrator roles",
        "settingKey": "conditionalAccess.requireMfaAdmins",
        "currentValue": false,
        "proposedValue": true,
        "status": "pending",
        "appliedBy": null,
        "appliedAt": null,
        "error": null
      }
    ]
  }
}

---

Elencare i piani di remediation

Restituisce i piani di remediation del tenant, dal più recente al più vecchio, ciascuno con i propri elementi e uno stato aggregato.

GET /tenants/me/remediation-plans

Valori di stato del piano

Stato	Significato
pending	Generato, ancora nulla applicato
completed	Ogni elemento applicato e verificato
partially_applied	Alcuni elementi applicati, altri falliti o ancora in attesa
failed	Nessun elemento ha potuto essere applicato

---

Recuperare un piano di remediation

GET /tenants/me/remediation-plans/{planId}

Restituisce un singolo piano (con i suoi elementi) limitato al tuo tenant. Un piano che appartiene a un altro tenant restituisce 404 NOT_FOUND.

---

Applicare un piano di remediation

Applica gli elementi selezionati tramite la connessione AI Pilot: ogni impostazione viene scritta tramite Microsoft Graph e poi riletta per confermare che la modifica abbia avuto effetto. Gli elementi che non elenchi restano invariati, e un elemento già verificato non viene mai riapplicato.

POST /tenants/me/remediation-plans/{planId}/apply

Corpo della richiesta

Campo	Tipo	Descrizione
itemIds	string[]	ID degli elementi del piano da applicare

Esempio di richiesta

curl -X POST https://api.aether365.io/tenants/me/remediation-plans/plan_abc123/apply \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "itemIds": ["item_1", "item_2"] }'

Esempio di risposta

Viene restituito il piano completo, ogni elemento con il proprio status aggiornato e, in caso di errore, un error che ne spiega il motivo.

{
  "success": true,
  "data": {
    "id": "plan_abc123",
    "status": "partially_applied",
    "items": [
      {
        "id": "item_1",
        "title": "Require MFA for administrator roles",
        "status": "verified",
        "appliedAt": "2026-06-17T09:05:00Z",
        "error": null
      },
      {
        "id": "item_2",
        "title": "Disable legacy authentication",
        "status": "failed",
        "error": "Write consent is missing or has expired"
      }
    ]
  }
}

Valori di stato degli elementi

Stato	Significato
verified	Applicato e confermato da una rilettura
applied	Applicato; Microsoft non ha ancora confermato la propagazione (ricontrollato in seguito)
failed	Non è stato possibile applicarlo - vedi error (es. write-consent assente)
pending	Non applicato in questa chiamata

L'approvazione umana è preservata

Non esiste alcuna scorciatoia del tipo "applica tutto". Sei tu a scegliere il piano e gli elementi esatti da applicare, così un flusso di lavoro automatizzato mantiene comunque una persona (o una decisione consapevole) nel processo.