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

Überprüfen Sie, dass eine Ausführung im kryptografischen Ledger verankert wurde. KLA erfasst OpenTelemetry-Spans, anonymisiert PII und schreibt sie in ein Append-only-Ledger fest, das Merkle-Proofs erzeugt. Dieser Endpunkt liefert den Nachweis für einen bestimmten Lineage Record (Trace) zurück und ermöglicht es Ihnen, unabhängig zu bestätigen, dass der Datensatz nicht verändert wurde.

• 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 dann mit rootHash, um die Integrität zu überprüfen, ohne KLA vertrauen zu müssen. Diese Nachweise 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.