Riferimento API

KLA Control Plane espone una REST API per governare in loco gli agenti AI aziendali. Usala per registrare gli agenti che già esegui, valutare una decisione di policy prima che un'azione venga eseguita e recuperare la prova crittografica che un'esecuzione sia stata registrata nel registro a prova di manomissione. Questa pagina documenta i tre endpoint principali, oltre ad autenticazione, gestione degli errori e header operativi. KLA Control Plane è il livello di sicurezza, audit e governance a runtime che affianca i tuoi agenti esistenti invece di sostituirli.

Tutte le richieste sono delimitate per tenant e usano JSON su HTTPS. L'URL di base è:

https://api.kla.digital/v1

Autenticazione

Ogni richiesta deve includere un token bearer e un identificatore di tenant. Il token è un access token OAuth 2.0 di breve durata; l'header del tenant delimita la richiesta alla tua organizzazione. Consulta il documento Autenticazione per sapere come generare i token (accesso browser PKCE per gli utenti, oppure un client secret di un service account per l'accesso programmatico).

curl https://api.kla.digital/v1/agents \
  -H "Authorization: Bearer $KLA_ACCESS_TOKEN" \
  -H "x-tenant-id: acme-prod" \
  -H "Content-Type: application/json"

Registrare un agente

Dichiara un agente affinché KLA possa tracciarne identità, proprietà e versione nell'Agent Registry. La registrazione restituisce un agentId stabile e un hash firmato del manifest che puoi referenziare da span e decisioni di policy.

• Endpoint: POST /agents

Corpo della richiesta

{
  "name": "claims-triage",
  "description": "Triages inbound insurance claims",
  "model": "gpt-4.1",
  "temperature": 0.2,
  "tools": ["lookup_policy", "flag_for_review"]
}

Risposta: 201 Created

{
  "agentId": "agt_9f81a7",
  "manifestHash": "sha256:d8a29fbc81d293...",
  "registeredAt": "2026-06-01T10:48:00Z"
}

Valutare una decisione di policy

Invia un'azione di un agente e il relativo contesto al motore di policy. KLA valuta le tue policy pubblicate (YAML dichiarativo compilato in policy pack firmati) e restituisce uno tra quattro esiti, in ordine di precedenza: allow, warn, require_approval, block. Una decisione require_approval mette in pausa l'esecuzione e instrada un'Escalation al Decision Desk per la revisione umana, condizione che la risposta segnala con requiresDeskApproval: true.

• Endpoint: POST /decisions.evaluate

Corpo della richiesta

{
  "agentId": "agt_9f81a7",
  "action": "execute_refund",
  "context": {
    "amount": 1250.00,
    "user_id": "usr_22"
  }
}

Risposta: 200 OK

{
  "decision": "require_approval",
  "reasonCodes": ["AMOUNT_OVER_THRESHOLD"],
  "requiresDeskApproval": true,
  "decisionId": "dec_8f29e12"
}

Recuperare una prova di audit

Verifica che un'esecuzione sia stata ancorata nel registro crittografico. KLA registra gli span OpenTelemetry, oscura i dati personali (PII) e li scrive in modo permanente in un registro append-only che produce Merkle proof. Questo endpoint restituisce la prova per un determinato Lineage Record (trace), permettendoti di confermare in autonomia che il record non sia stato alterato.

• Endpoint: GET /lineage/{lineageId}/verify

Risposta: 200 OK

{
  "lineageId": "lr_99a1287fbc",
  "anchored": true,
  "ledgerIndex": 128994,
  "rootHash": "sha256:9f8d2e8ab219d...",
  "merklePath": [
    "sha256:bc892a76f...",
    "sha256:e829dc76a..."
  ]
}

Ricalcola la root a partire dall'hash della foglia e da merklePath, quindi confrontala con rootHash per verificare l'integrità senza fidarti di KLA. Queste prove sono alla base di ogni Sealed Evidence Bundle esportato dall'Evidence Room.

Errori e codici di stato

Gli errori restituiscono un corpo JSON con code e message. Usa lo stato HTTP per decidere il comportamento di retry.

{
  "code": "invalid_request",
  "message": "field 'amount' must be a number"
}

Limiti di frequenza e idempotenza

Le richieste sono soggette a un limite di frequenza per tenant; in caso di 429, applica un backoff e riprova dopo il valore di Retry-After. Per le chiamate in scrittura (POST /agents, POST /decisions.evaluate), invia un header Idempotency-Key con un valore univoco per rendere sicuri i retry. Riproporre la stessa chiave restituisce il risultato originale invece di creare un duplicato.