Référence de l'API

KLA Control Plane expose une API REST pour gouverner en place les agents IA d'entreprise. Utilisez-la pour enregistrer les agents que vous exécutez déjà, évaluer une décision de politique avant qu'une action ne s'exécute et récupérer la preuve cryptographique qu'une exécution a bien été consignée dans le registre infalsifiable. Cette page documente les trois points de terminaison principaux ainsi que l'authentification, la gestion des erreurs et les en-têtes opérationnels. KLA Control Plane est la couche de sécurité, d'audit et de gouvernance d'exécution qui s'adosse à vos agents existants plutôt que de les remplacer.

Toutes les requêtes sont délimitées par locataire (tenant-scoped) et utilisent JSON sur HTTPS. L'URL de base est :

https://api.kla.digital/v1

Authentification

Chaque requête doit porter un jeton bearer ainsi qu'un identifiant de locataire. Le jeton est un jeton d'accès OAuth 2.0 à courte durée de vie ; l'en-tête de locataire restreint la requête à votre organisation. Consultez le document Authentification pour savoir comment émettre des jetons (connexion navigateur PKCE pour les utilisateurs, ou secret client de compte de service pour l'accès machine).

curl https://api.kla.digital/v1/agents \
  -H "Authorization: Bearer $KLA_ACCESS_TOKEN" \
  -H "x-tenant-id: acme-prod" \
  -H "Content-Type: application/json"

Enregistrer un agent

Déclarez un agent afin que KLA puisse suivre son identité, sa propriété et sa version dans l'Agent Registry. L'enregistrement renvoie un agentId stable ainsi qu'un hachage de manifeste signé que vous pouvez référencer depuis les spans et les décisions de politique.

• Point de terminaison : POST /agents

Corps de la requête

{
  "name": "claims-triage",
  "description": "Triages inbound insurance claims",
  "model": "gpt-4.1",
  "temperature": 0.2,
  "tools": ["lookup_policy", "flag_for_review"]
}

Réponse : 201 Created

{
  "agentId": "agt_9f81a7",
  "manifestHash": "sha256:d8a29fbc81d293...",
  "registeredAt": "2026-06-01T10:48:00Z"
}

Évaluer une décision de politique

Soumettez une action d'agent et son contexte au moteur de politique. KLA évalue vos politiques publiées (YAML déclaratif compilé en policy packs signés) et renvoie l'un des quatre résultats possibles, par ordre de priorité : allow, warn, require_approval, block. Une décision require_approval met l'exécution en pause et achemine une Escalation vers le Decision Desk pour examen humain, ce que la réponse signale par requiresDeskApproval: true.

• Point de terminaison : POST /decisions.evaluate

Corps de la requête

{
  "agentId": "agt_9f81a7",
  "action": "execute_refund",
  "context": {
    "amount": 1250.00,
    "user_id": "usr_22"
  }
}

Réponse : 200 OK

{
  "decision": "require_approval",
  "reasonCodes": ["AMOUNT_OVER_THRESHOLD"],
  "requiresDeskApproval": true,
  "decisionId": "dec_8f29e12"
}

Récupérer une preuve d'audit

Vérifiez qu'une exécution a bien été ancrée dans le registre cryptographique. KLA enregistre les spans OpenTelemetry, expurge les données personnelles (PII) et les inscrit dans un registre en ajout seul (append-only) qui produit des Merkle proofs. Ce point de terminaison renvoie la preuve associée à un Lineage Record (trace) donné, vous permettant de confirmer en toute indépendance que l'enregistrement n'a pas été altéré.

• Point de terminaison : GET /lineage/{lineageId}/verify

Réponse : 200 OK

{
  "lineageId": "lr_99a1287fbc",
  "anchored": true,
  "ledgerIndex": 128994,
  "rootHash": "sha256:9f8d2e8ab219d...",
  "merklePath": [
    "sha256:bc892a76f...",
    "sha256:e829dc76a..."
  ]
}

Recalculez la racine à partir du hachage de feuille et de merklePath, puis comparez-la à rootHash pour vérifier l'intégrité sans avoir à faire confiance à KLA. Ces preuves sous-tendent chaque Sealed Evidence Bundle exporté depuis l'Evidence Room.

Erreurs et codes de statut

Les erreurs renvoient un corps JSON contenant code et message. Utilisez le statut HTTP pour décider du comportement de relance.

{
  "code": "invalid_request",
  "message": "field 'amount' must be a number"
}

Limites de débit et idempotence

Les requêtes sont soumises à une limite de débit par locataire ; en cas de 429, temporisez et relancez après la valeur indiquée par Retry-After. Pour les appels en écriture (POST /agents, POST /decisions.evaluate), envoyez un en-tête Idempotency-Key avec une valeur unique afin de rendre les relances sûres. Rejouer la même clé renvoie le résultat d'origine au lieu de créer un doublon.