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

Récupérez la preuve du registre associée à un Lineage Record (trace) donné. La preuve vous permet de recalculer la chaîne de hachages de l'enregistrement afin de confirmer qu'elle est cohérente en interne avec la racine que KLA rapporte. Pour une vérification indépendante et hors ligne qui ne dépend pas d'une réponse en direct de KLA, exportez et vérifiez un Sealed Evidence Bundle depuis l'Evidence Room.

• 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 au rootHash renvoyé ici afin de confirmer que la chaîne de hachages de l'enregistrement est cohérente en interne. Remarque : le rootHash de ce point de terminaison est rapporté par KLA ; pour une vérification hors ligne et autonome qui ne nécessite pas de connexion active à KLA, vérifiez un Sealed Evidence Bundle de l'Evidence Room avec kla evidence verify.

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.