API-Referenz

Die KLA Control Plane stellt eine REST API bereit, um unternehmensweite KI-Agents direkt im laufenden Betrieb zu steuern. Nutzen Sie sie, um die Agents zu registrieren, die Sie bereits betreiben, eine Policy-Entscheidung auszuwerten, bevor eine Aktion ausgeführt wird, und den kryptografischen Nachweis abzurufen, dass eine Ausführung im manipulationssicheren Ledger erfasst wurde. Diese Seite dokumentiert die drei Kern-Endpunkte sowie Authentifizierung, Fehlerbehandlung und betriebliche Header. Die KLA Control Plane ist die Schicht für Laufzeitsicherheit, Audit und Governance, die neben Ihren bestehenden Agents arbeitet, anstatt sie zu ersetzen.

Alle Anfragen sind mandantenbezogen und erfolgen als JSON über HTTPS. Die Basis-URL lautet:

https://api.kla.digital/v1

Authentifizierung

Jede Anfrage muss ein Bearer-Token und eine Mandantenkennung enthalten. Das Token ist ein kurzlebiges OAuth 2.0 Access Token; der Mandanten-Header schränkt die Anfrage auf Ihre Organisation ein. Im Dokument Authentifizierung ist beschrieben, wie Sie Tokens erzeugen (Browser-PKCE-Anmeldung für Benutzer oder ein Service-Account-Client-Secret für den Maschinenzugriff).

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

Einen Agent registrieren

Deklarieren Sie einen Agent, damit KLA dessen Identität, Eigentümerschaft und Version in der Agent Registry verfolgen kann. Die Registrierung liefert eine stabile agentId und einen signierten Manifest-Hash zurück, auf den Sie aus Spans und Policy-Entscheidungen verweisen können.

• Endpunkt: POST /agents

Request-Body

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

Antwort: 201 Created

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

Eine Policy-Entscheidung auswerten

Übermitteln Sie eine Agent-Aktion und ihren Kontext an die Policy Engine. KLA wertet Ihre veröffentlichten Policies (deklaratives YAML, kompiliert zu signierten Policy Packs) aus und liefert eines von vier Ergebnissen zurück, in Vorrangreihenfolge: allow, warn, require_approval, block. Eine require_approval-Entscheidung hält die Ausführung an und leitet eine Escalation an das Decision Desk zur menschlichen Prüfung weiter, was die Antwort mit requiresDeskApproval: true signalisiert.

• Endpunkt: POST /decisions.evaluate

Request-Body

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

Antwort: 200 OK

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

Einen Audit-Nachweis abrufen

Rufen Sie den Ledger-Proof für einen bestimmten Lineage Record (Trace) ab. Der Proof erlaubt es Ihnen, die Hash-Kette des Datensatzes neu zu berechnen, um zu bestätigen, dass sie intern konsistent mit dem von KLA gemeldeten Root ist. Für eine unabhängige, offline durchgeführte Verifizierung, die nicht auf eine Live-Antwort von KLA angewiesen ist, exportieren und verifizieren Sie ein Sealed Evidence Bundle aus dem Evidence Room.

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

Antwort: 200 OK

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

Berechnen Sie den Root aus dem Leaf-Hash und merklePath neu und vergleichen Sie ihn mit dem hier zurückgelieferten rootHash, um zu bestätigen, dass die Hash-Kette des Datensatzes intern konsistent ist. Hinweis: Der rootHash dieses Endpunkts wird von KLA gemeldet; für eine offline durchführbare, in sich abgeschlossene Verifizierung, die keine Live-Verbindung zu KLA erfordert, verifizieren Sie ein Sealed Evidence Bundle aus dem Evidence Room mit kla evidence verify. Diese Anker belegen jedes Sealed Evidence Bundle, das aus dem Evidence Room exportiert wird.

Fehler und Statuscodes

Fehler liefern einen JSON-Body mit code und message zurück. Verwenden Sie den HTTP-Status, um über das Wiederholungsverhalten zu entscheiden.

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

Rate-Limits und Idempotenz

Anfragen sind pro Mandant ratenbegrenzt; bei 429 warten Sie ab und versuchen es nach dem Wert von Retry-After erneut. Senden Sie bei Schreibaufrufen (POST /agents, POST /decisions.evaluate) einen Idempotency-Key-Header mit einem eindeutigen Wert, um Wiederholungen sicher zu machen. Das erneute Senden desselben Keys liefert das ursprüngliche Ergebnis zurück, anstatt ein Duplikat zu erzeugen.