Référence de l'API | Developer Docs

KLA Control Plane expose deux transports HTTP sous le chemin de base /v1 :

Les procédures tRPC générées utilisent un nom d'opération avec des points, comme agents.create. La CLI expose toutes les opérations du catalogue de control plane généré.
Les routes REST couvrent l'export Evidence, le transport de fichiers, le registre des politiques, la télémétrie et d'autres surfaces propres aux services.

Utilisez la CLI pour les procédures tRPC et kla api rest ou curl pour les routes REST. L'hôte API des exemples est l'API dev déployée :

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

Le catalogue est généré depuis l'AppRouter du serveur. Le nombre d'opérations évolue avec les procédures. Exécutez kla api list pour consulter le nombre actuel et kla api doctor pour comparer le catalogue intégré au serveur configuré.

Authentification et en-têtes de tenant

Chaque requête porte un jeton bearer OAuth 2.0 à courte durée de vie. Le claim de tenant vérifié fournit le tenant par défaut. Conservez les jetons et les secrets client dans l'environnement du service appelant.

En-tête	Obligatoire	Sémantique
`Authorization`	Oui	`Bearer <access token>` authentifie l'appelant.
`x-kla-tenant-external-id`	Non	Sélectionne un tenant par son identifiant externe lorsque le sujet authentifié y possède une adhésion active. Une sélection sans adhésion renvoie `403`.
`x-kla-tenant-id`	Non	UUID interne du tenant. L’authentification et l’appartenance vérifiée déterminent le tenant.
`Content-Type`	Pour les écritures JSON	`application/json`.

La CLI envoie son KLA_TENANT_ID configuré comme x-kla-tenant-id. Les commandes avec une sélection explicite, comme kla evidence export --tenant <external-id>, utilisent x-kla-tenant-external-id et exigent une adhésion active.

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"

Procédures tRPC

Le gestionnaire tRPC est monté sur /v1. Le chemin HTTP d'une procédure est /v1/<procedure> :

Type de procédure	Méthode HTTP	Exemple
Mutation	`POST`	`POST /v1/agents.create`
Query	`GET`	`GET /v1/approvals.getPending`
Subscription	Realtime/WebSocket	`traces.stream`

Le catalogue généré et le serveur valident la même entrée Zod. Découvrez les schémas d'entrée avec :

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

Enregistrer un agent

agents.create accepte le manifeste de l'agent sous forme de chaîne YAML. La commande organisée appelle la même procédure que la commande générique :

Point de terminaison : 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 réponse contient l'identifiant de l'agent enregistré. Une liaison de politique approuvée et un release sont nécessaires avant qu'executions.execute puisse exécuter l'agent.

Démarrer et inspecter une exécution

La procédure d'exécution renvoie 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"}'

Lire et résoudre les approbations en attente

approvals.getPending liste les Decision Requests en attente pour le tenant actuel. approvals.decide accepte approve, reject ou escalate et exige une justification.

Point de terminaison : GET /v1/approvals.getPending
Point de terminaison : 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 applique les permissions du tenant et les règles maker-checker à la décision. Un reviewer ne peut pas approuver une demande créée par sa propre identité lorsque la politique du tenant exige une séparation des tâches.

Inspecter et vérifier les traces

traces.getTrace renvoie les spans d'une trace. Les valeurs sensibles restent masquées, sauf si l'appelant possède la permission distincte de démasquage et fournit une justification.

Point de terminaison : GET /v1/traces.getTrace
Point de terminaison : 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 exige la permission trace:verify. Son entrée contient toujours tenant ; les champs de preuve sont fournis lorsque l'enregistrement d'audit correspondant les contient.

Routes REST Evidence

L'export Evidence utilise un travail REST asynchrone de l'API. La requête accepte une fenêtre temporelle et des indicateurs pour les proofs et les payloads bruts. evidence:export crée un travail et lit les travaux du même acteur. evidence:list lit les travaux de tout le tenant. evidence:read lit le manifeste et l'archive scellés.

Créer un export

Point de terminaison : 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 réponse contient exportId, status et pollTimeoutMs. Le sondage se termine avec completed, completed_with_omissions, failed ou canceled.

Sonder, lire le manifeste et télécharger l'archive

Point de terminaison : GET /v1/evidence/factory/jobs/$EXPORT_ID
Point de terminaison : GET /v1/evidence/factory/jobs/$EXPORT_ID/manifest
Point de terminaison : 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'archive est un paquet scellé de type evidence-room-bundle-v1. Vérifiez-le hors ligne avec :

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

La commande kla evidence export crée le travail à POST /v1/evidence/export-jobs, sonde GET /v1/evidence/factory/jobs/:exportId, puis lit le manifeste et télécharge depuis les routes canoniques Evidence Factory. Elle conserve l'origine API, la sélection du tenant et l'identifiant dans le contexte CLI sélectionné.

Comportement et erreurs des requêtes REST

Les réponses REST utilisent JSON pour les métadonnées et application/zip pour les téléchargements d'archives. Les codes de statut courants sont :

Statut	Signification
`400`	Échec de validation de la requête ou contexte de tenant incomplet.
`401`	Le jeton bearer est absent, expiré ou invalide.
`403`	L'appelant n'a pas la permission requise ou l'adhésion au tenant.
`404`	La ressource ou la route n'existe pas pour le tenant sélectionné.
`409`	La requête entre en conflit avec l'état actuel de la ressource.
`429`	La limite de débit du tenant est dépassée.
`5xx`	Défaillance transitoire d'un service ou d'une dépendance.

Traitez une décision de politique échouée, une autorisation d'approbation échouée ou un preflight Evidence échoué comme une opération échouée. Ne relancez que lorsque la réponse identifie une défaillance transitoire et que l'opération peut être répétée sans risque.