API-Referenz

Die KLA Control Plane stellt zwei HTTP-Transporte unter dem Basispfad /v1 bereit:

• Generierte tRPC-Prozeduren verwenden einen Namen mit Punkten wie agents.create. Die CLI stellt jede Operation aus dem generierten Control-Plane-Katalog bereit.
• REST-Routen decken den Evidence-Export, den Dateitransport, die Policy Registry, Telemetrie und weitere servicespezifische Oberflächen ab.

Verwenden Sie die CLI für tRPC-Prozeduren und kla api rest oder curl für REST-Routen. Der API-Host in den Beispielen ist die bereitgestellte Dev-API:

export KLA_API_URL='https://api.dev.kla.digital'
export KLA_ACCESS_TOKEN='<short-lived access token>'
export KLA_TENANT_ID='<tenant external ID>'

# Build the repository CLI while the package is private, then expose it in this shell.
corepack enable
pnpm install --frozen-lockfile
pnpm kla --help
KLA_REPO_ROOT="$(git rev-parse --show-toplevel)"
kla() { KLA_CLI_CWD="$PWD" pnpm --dir "$KLA_REPO_ROOT" --silent kla "$@"; }

Der Katalog wird aus dem Server-AppRouter generiert. Die Anzahl seiner Operationen ändert sich, wenn Prozeduren hinzukommen oder entfernt werden. Führen Sie kla api list aus, um die aktuelle Anzahl zu prüfen, und kla api doctor, um den eingebetteten Katalog mit dem konfigurierten Server zu vergleichen.

Authentifizierung und Tenant-Header

Jede Anfrage enthält ein kurzlebiges OAuth-2.0-Bearer-Token. Der verifizierte Tenant-Claim liefert den Standard-Tenant. Bewahren Sie Token und Client-Secrets in der Umgebung des aufrufenden Dienstes auf.

Header	Erforderlich	Semantik
Authorization	Ja	Bearer <access token> authentifiziert den Aufrufer.
x-kla-tenant-external-id	Nein	Wählt einen Tenant anhand der externen ID aus, wenn der authentifizierte Subject eine aktive Mitgliedschaft in diesem Tenant hat. Die Auswahl eines Tenants ohne Mitgliedschaft liefert 403.
x-kla-tenant-id	Nein	Interne UUID des Mandanten. Authentifizierung und bestätigte Mitgliedschaft bestimmen den Mandanten.
Content-Type	Bei JSON-Schreibvorgängen	application/json.

Die CLI sendet ihre konfigurierte KLA_TENANT_ID als x-kla-tenant-id. Befehle mit einer ausdrücklichen Tenant-Auswahl, etwa kla evidence export --tenant <external-id>, verwenden x-kla-tenant-external-id und erfordern eine aktive Mitgliedschaft.

kla auth test

curl -sS "$KLA_API_URL/v1/tenants.current" \
  -H "Authorization: Bearer $KLA_ACCESS_TOKEN" \
  -H "x-kla-tenant-external-id: $KLA_TENANT_ID"

tRPC-Prozeduren

Der tRPC-Handler ist unter /v1 eingebunden. Der HTTP-Pfad einer Prozedur lautet /v1/<procedure>:

Prozedurtyp	HTTP-Methode	Beispiel
Mutation	POST	POST /v1/agents.create
Query	GET	GET /v1/approvals.getPending
Subscription	Realtime/WebSocket	traces.stream

Der generierte Katalog und der Server validieren dieselbe Zod-Eingabe. Ermitteln Sie Eingabeschemas mit:

kla api list --prefix agents.
kla api describe agents.create
kla api describe approvals.decide

Einen Agenten registrieren

agents.create akzeptiert das Agenten-Manifest als YAML-String. Der kuratierte Befehl ruft dieselbe Prozedur wie der generische Befehl auf:

• Endpunkt: POST /v1/agents.create

kla agent create --file /tmp/claims-triage.yaml
# Equivalent generated procedure command:
kla api agents create --input "$(jq -Rs '{yaml: .}' /tmp/claims-triage.yaml)"

Die Antwort enthält die ID des registrierten Agenten. Eine genehmigte Policy-Bindung und ein Release sind erforderlich, bevor executions.execute den Agenten ausführen kann.

Eine Ausführung starten und prüfen

Die Ausführungsprozedur liefert eine executionId:

kla agent run AGENT_UUID \
  --environment sandbox \
  --input '{"claim_id":"clm_9921","requested_refund":1250.00}'

kla api executions get --input '{"id":"EXECUTION_UUID"}'
kla api executions getEvents --input '{"id":"EXECUTION_UUID"}'

Dauerhafte externe Eingabe

kla input übermittelt ein benutzerdefiniertes externes Ereignis und verwendet kataloggestützte Prozeduren, um receipts zu lesen, waits zu prüfen, einen wait abzubrechen und eine blockierte Auflösung erneut zu versuchen. Die API erzwingt bei jeder Mutation den authentifizierten Tenant, Ressourcenberechtigungen und die erwartete Revision.

kla input submit --input @examples/durable-inputs/customer-operated-input-bridge/input-event.json
kla input receipt EXECUTION_UUID RECEIPT_UUID
kla input wait inspect EXECUTION_UUID
kla input wait cancel EXECUTION_UUID WAIT_UUID --expected-revision 3 --reason 'Closed'
kla input resolution retry EXECUTION_UUID RESOLUTION_UUID --expected-revision 4 --reason 'Recovered'

POST /v1/input-events gibt 202 accepted oder 202 duplicate mit einer receipt-ID zurück. accepted bestätigt die Aufnahme in die dauerhafte Inbox. Der Zustand accepted der receipt bestätigt eine Übereinstimmung. Zustellung und Anwendung bleiben getrennte Zustände. 409 event_conflict bedeutet, dass die Idempotenzidentität einen anderen Fingerprint hatte. wait_terminal ist ein terminaler 409-Ausgang für einen abgebrochenen wait. Verwenden Sie für eine bewusste Wiederholung denselben Idempotenzschlüssel. Nach einem unbekannten SMTP-Ausgang darf nicht automatisch erneut gesendet werden.

Die Node- und Python-Quellbäume der Governance SDKs exportieren DurableInputClient. Ihre Ergänzungen für dauerhafte Eingaben sind nicht auf npm oder PyPI veröffentlicht. Die bestehenden generierten Prozeduräquivalente bleiben executions.inputEvents.get, executions.inputWaits.list, executions.inputWaits.cancel und executions.inputResolutions.retry.

Ausstehende Genehmigungen lesen und auflösen

approvals.getPending listet ausstehende Decision Requests für den aktuellen Tenant auf. approvals.decide akzeptiert approve, reject oder escalate und erfordert eine Begründung.

• Endpunkt: GET /v1/approvals.getPending
• Endpunkt: POST /v1/approvals.decide

kla api approvals getPending --input '{"limit":20}'
export KLA_REVIEWER_ACCESS_TOKEN='<reviewer short-lived access token>'
cat > /tmp/approval-decision.json <<'JSON'
{
  "approvalId": "APPROVAL_UUID",
  "decision": "approve",
  "decisionAcknowledged": true,
  "reason": "Reviewed the claim evidence and authorized the refund."
}
JSON
KLA_ACCESS_TOKEN="$KLA_REVIEWER_ACCESS_TOKEN" \
  kla api approvals decide --input @/tmp/approval-decision.json

Die API wendet Tenant-Berechtigungen und Maker-Checker-Regeln auf die Entscheidung an. Ein Reviewer darf eine Anfrage derselben Identität nicht genehmigen, die sie erstellt hat, wenn die Policy des Tenants eine Aufgabentrennung verlangt.

Traces prüfen und verifizieren

traces.getTrace liefert die Spans eines einzelnen Traces. Sensible Werte bleiben maskiert, sofern der Aufrufer nicht über die gesonderte Unmask-Berechtigung verfügt und eine Begründung angibt.

• Endpunkt: GET /v1/traces.getTrace
• Endpunkt: GET /v1/traces.verify

kla api traces getTrace \
  --input '{"traceId":"TRACE_ID","tenantId":"TENANT_EXTERNAL_ID","includeSensitiveData":false}'

kla api traces verify \
  --input '{"tenant":"TENANT_EXTERNAL_ID","auditId":"AUDIT_ID","date":"PROOF_DATE","nonce":"PROOF_NONCE","merkleRoot":"MERKLE_ROOT"}'

traces.verify erfordert die Berechtigung trace:verify. Seine Eingabe enthält immer tenant; die Proof-Felder werden angegeben, wenn der zugehörige Audit-Datensatz sie enthält.

Evidence-REST-Routen

Der Evidence-Export verwendet einen asynchronen REST-Job der API. Die Anfrage akzeptiert ein Zeitfenster sowie Flags für Proofs und Rohdaten. evidence:export erstellt einen Job und liest Jobs desselben Akteurs. evidence:list liest Jobs des gesamten Tenants. evidence:read liest das versiegelte Manifest und Archiv.

Einen Export erstellen

• Endpunkt: POST /v1/evidence/export-jobs

EXPORT_JOB=$(curl -sS -X POST "$KLA_API_URL/v1/evidence/export-jobs" \
  -H "Authorization: Bearer $KLA_ACCESS_TOKEN" \
  -H "x-kla-tenant-external-id: $KLA_TENANT_ID" \
  -H 'Content-Type: application/json' \
  -d '{"startDate":"2026-07-01T00:00:00.000Z","endDate":"2026-07-31T00:00:00.000Z","includeProofs":true}')
echo "$EXPORT_JOB"

Die Antwort enthält exportId, status und pollTimeoutMs. Polling endet bei completed, completed_with_omissions, failed oder canceled.

Pollen, Manifest lesen und Archiv herunterladen

• Endpunkt: GET /v1/evidence/factory/jobs/$EXPORT_ID
• Endpunkt: GET /v1/evidence/factory/jobs/$EXPORT_ID/manifest
• Endpunkt: GET /v1/evidence/factory/jobs/$EXPORT_ID/download

EXPORT_ID=$(jq -r '.exportId' <<<"$EXPORT_JOB")

curl -sS "$KLA_API_URL/v1/evidence/factory/jobs/$EXPORT_ID" \
  -H "Authorization: Bearer $KLA_ACCESS_TOKEN" \
  -H "x-kla-tenant-external-id: $KLA_TENANT_ID" | jq

curl -sS "$KLA_API_URL/v1/evidence/factory/jobs/$EXPORT_ID/manifest" \
  -H "Authorization: Bearer $KLA_ACCESS_TOKEN" \
  -H "x-kla-tenant-external-id: $KLA_TENANT_ID" | jq

curl -sS -f "$KLA_API_URL/v1/evidence/factory/jobs/$EXPORT_ID/download" \
  -H "Authorization: Bearer $KLA_ACCESS_TOKEN" \
  -H "x-kla-tenant-external-id: $KLA_TENANT_ID" \
  -o "./evidence-$EXPORT_ID.zip"

Das Archiv ist ein versiegeltes Paket vom Typ evidence-room-bundle-v1. Verifizieren Sie es offline mit:

kla evidence verify --bundle "./evidence-$EXPORT_ID.zip" --out ./evidence-report

Der Befehl kla evidence export erstellt den Job über POST /v1/evidence/export-jobs, pollt GET /v1/evidence/factory/jobs/:exportId und liest Manifest und Archiv über die kanonischen Evidence-Factory-Routen. Er verwendet den API-Ursprung, die Tenant-Auswahl und das Zugangstoken aus dem ausgewählten CLI-Kontext.

Verhalten und Fehler bei REST-Anfragen

REST-Antworten verwenden JSON für Metadaten und application/zip für Archiv-Downloads. Häufige Statuscodes sind:

Status	Bedeutung
400	Request-Validierung fehlgeschlagen oder Tenant-Kontext unvollständig.
401	Bearer-Token fehlt, ist abgelaufen oder ungültig.
403	Dem Aufrufer fehlen die erforderliche Berechtigung oder Tenant-Mitgliedschaft.
404	Ressource oder Route existiert für den ausgewählten Tenant nicht.
409	Die Anfrage steht im Konflikt mit dem aktuellen Ressourcenstatus.
429	Das Tenant-Rate-Limit wurde überschritten.
5xx	Vorübergehender Fehler eines Dienstes oder einer Abhängigkeit.

Behandeln Sie eine fehlgeschlagene Policy-Entscheidung, eine fehlgeschlagene Genehmigungsautorisierung oder einen fehlgeschlagenen Evidence-Preflight als fehlgeschlagene Operation. Wiederholen Sie nur, wenn die Antwort einen vorübergehenden Fehler nennt und die Operation sicher wiederholt werden kann.