Riferimento API

KLA Control Plane espone due trasporti HTTP sotto il percorso base /v1:

• Le procedure tRPC generate usano un nome di operazione con punti, come agents.create. La CLI espone ogni operazione del catalogo control plane generato.
• Le route REST coprono l'esportazione Evidence, il trasporto dei file, il registro delle policy, la telemetria e altre superfici gestite dai servizi.

Usa la CLI per le procedure tRPC e kla api rest o curl per le route REST. L'host API negli esempi è l'API dev distribuita:

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 "$@"; }

Il catalogo viene generato dall'AppRouter del server. Il numero di operazioni cambia quando cambiano le procedure. Esegui kla api list per vedere il numero attuale e kla api doctor per confrontare il catalogo integrato con il server configurato.

Autenticazione e header tenant

Ogni richiesta include un bearer token OAuth 2.0 di breve durata. Il tenant claim verificato fornisce il tenant predefinito. Conserva token e client secret nell'ambiente del servizio chiamante.

Header	Obbligatorio	Semantica
Authorization	Sì	Bearer <access token> autentica il chiamante.
x-kla-tenant-external-id	No	Seleziona un tenant tramite l'ID esterno quando il soggetto autenticato ha un'appartenenza attiva a quel tenant. Una selezione senza appartenenza restituisce 403.
x-kla-tenant-id	No	UUID interno del tenant. L’autenticazione e l’appartenenza verificata determinano il tenant.
Content-Type	Per scritture JSON	application/json.

La CLI invia il proprio KLA_TENANT_ID configurato come x-kla-tenant-id. I comandi con una selezione esplicita, come kla evidence export --tenant <external-id>, usano x-kla-tenant-external-id e richiedono un'appartenenza attiva.

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"

Procedure tRPC

Il gestore tRPC è montato su /v1. Il percorso HTTP di una procedura è /v1/<procedure>:

Tipo di procedura	Metodo HTTP	Esempio
Mutation	POST	POST /v1/agents.create
Query	GET	GET /v1/approvals.getPending
Subscription	Realtime/WebSocket	traces.stream

Il catalogo generato e il server validano lo stesso input Zod. Scopri gli schemi di input con:

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

Registrare un agente

agents.create accetta il manifest dell'agente come stringa YAML. Il comando curato usa la stessa procedura del comando generico:

• Endpoint: 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)"

La risposta include l'identificatore dell'agente registrato. Prima che executions.execute possa eseguire l'agente servono un binding di policy approvato e un release.

Avviare e ispezionare un'esecuzione

La procedura di esecuzione restituisce un 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"}'

Input esterno durevole

kla input invia un evento esterno personalizzato e usa procedure supportate dal catalogo per leggere i receipts, ispezionare i waits, annullare un wait e ritentare una risoluzione bloccata. L’API applica il tenant autenticato, le autorizzazioni della risorsa e la revisione prevista a ogni mutazione.

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 restituisce 202 accepted o 202 duplicate con un ID di receipt. accepted conferma l’ammissione nella casella in entrata durevole. Lo stato accepted del receipt conferma una corrispondenza. La consegna e l’applicazione restano stati separati. 409 event_conflict indica che l’identità di idempotenza aveva un fingerprint diverso. wait_terminal è un risultato 409 terminale per un wait annullato. Usa la stessa chiave di idempotenza per una ripetizione intenzionale. Non reinviare automaticamente dopo un risultato SMTP sconosciuto.

Gli alberi sorgente degli SDK di governance Node e Python esportano DurableInputClient. Le loro aggiunte per input durevoli non sono pubblicate su npm o PyPI. Gli equivalenti delle procedure generate esistenti restano executions.inputEvents.get, executions.inputWaits.list, executions.inputWaits.cancel e executions.inputResolutions.retry.

Leggere e risolvere le approvazioni in sospeso

approvals.getPending elenca le Decision Requests in sospeso per il tenant corrente. approvals.decide accetta approve, reject o escalate e richiede una motivazione.

• Endpoint: GET /v1/approvals.getPending
• Endpoint: 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

L'API applica le autorizzazioni tenant e le regole maker-checker alla decisione. Un reviewer non può approvare una richiesta creata dalla propria identità quando la policy del tenant richiede la separazione dei compiti.

Ispezionare e verificare le tracce

traces.getTrace restituisce gli span di una trace. I valori sensibili restano mascherati, a meno che il chiamante disponga del permesso separato di unmask e fornisca una motivazione.

• Endpoint: GET /v1/traces.getTrace
• Endpoint: 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 richiede il permesso trace:verify. Il suo input include sempre tenant; i campi proof vengono forniti quando il record di audit corrispondente li contiene.

Route REST Evidence

L'esportazione Evidence usa un job REST asincrono dell'API. La richiesta accetta una finestra temporale e flag per proofs e payload grezzi. evidence:export crea un job e legge job dello stesso attore. evidence:list legge job dell'intero tenant. evidence:read legge il manifest e l'archivio sigillati.

Creare un'esportazione

• Endpoint: 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"

La risposta contiene exportId, status e pollTimeoutMs. Il polling termina con completed, completed_with_omissions, failed o canceled.

Eseguire il polling, leggere il manifest e scaricare l'archivio

• Endpoint: GET /v1/evidence/factory/jobs/$EXPORT_ID
• Endpoint: GET /v1/evidence/factory/jobs/$EXPORT_ID/manifest
• Endpoint: 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"

L'archivio è un pacchetto sigillato di tipo evidence-room-bundle-v1. Verificalo offline con:

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

Il comando kla evidence export crea il job in POST /v1/evidence/export-jobs, esegue il polling di GET /v1/evidence/factory/jobs/:exportId e legge il manifest e scarica dalle route canoniche di Evidence Factory. Mantiene l'origine API, la selezione del tenant e la credenziale nel contesto CLI selezionato.

Comportamento ed errori delle richieste REST

Le risposte REST usano JSON per i metadati e application/zip per i download degli archivi. I codici di stato comuni sono:

Stato	Significato
400	Validazione della richiesta fallita o contesto tenant incompleto.
401	Il bearer token manca, è scaduto o non è valido.
403	Il chiamante non dispone del permesso richiesto o dell'appartenenza al tenant.
404	La risorsa o la route non esiste per il tenant selezionato.
409	La richiesta è in conflitto con lo stato corrente della risorsa.
429	Il rate limit del tenant è stato superato.
5xx	Errore transitorio del servizio o di una dipendenza.

Considera una decisione di policy fallita, un'autorizzazione dell'approvazione fallita o un preflight Evidence fallito come un'operazione fallita. Ripeti la richiesta solo quando la risposta identifica un errore transitorio e l'operazione può essere ripetuta in sicurezza.