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"}'

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.