Referencia de la API

KLA Control Plane expone una API REST para gobernar agentes de IA empresariales en su lugar de ejecución. Úsala para registrar los agentes que ya ejecutas, evaluar una decisión de política antes de que se ejecute una acción y obtener la prueba criptográfica de que una ejecución quedó registrada en el ledger a prueba de manipulaciones. Esta página documenta los tres endpoints principales, además de la autenticación, el manejo de errores y las cabeceras operativas. KLA Control Plane es la capa de seguridad, auditoría y gobernanza en tiempo de ejecución que convive con tus agentes existentes en lugar de reemplazarlos.

Todas las solicitudes están delimitadas por inquilino (tenant) y se realizan en JSON sobre HTTPS. La URL base es:

https://api.kla.digital/v1

Autenticación

Cada solicitud debe incluir un token de portador (bearer) y un identificador de inquilino. El token es un token de acceso OAuth 2.0 de corta duración; la cabecera de inquilino delimita la solicitud a tu organización. Consulta el documento de Autenticación para saber cómo emitir tokens (inicio de sesión PKCE en el navegador para usuarios, o un secreto de cliente de cuenta de servicio para el acceso por máquina).

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

Registrar un agente

Declara un agente para que KLA pueda rastrear su identidad, propiedad y versión en el Agent Registry. El registro devuelve un agentId estable y un hash de manifiesto firmado que puedes referenciar desde spans y decisiones de política.

• Endpoint: POST /agents

Cuerpo de la solicitud

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

Respuesta: 201 Created

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

Evaluar una decisión de política

Envía una acción de un agente y su contexto al motor de políticas. KLA evalúa tus políticas publicadas (YAML declarativo compilado en paquetes de políticas firmados) y devuelve uno de cuatro resultados, en orden de precedencia: allow, warn, require_approval, block. Una decisión require_approval pausa la ejecución y enruta una Escalation al Decision Desk para revisión humana, lo que la respuesta indica con requiresDeskApproval: true.

• Endpoint: POST /decisions.evaluate

Cuerpo de la solicitud

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

Respuesta: 200 OK

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

Obtener una prueba de auditoría

Verifica que una ejecución quedó anclada en el ledger criptográfico. KLA registra spans de OpenTelemetry, redacta los datos personales (PII) y los registra en un ledger de solo anexado (append-only) que produce pruebas Merkle. Este endpoint devuelve la prueba para un Lineage Record (traza) dado, lo que te permite confirmar de forma independiente que el registro no ha sido alterado.

• Endpoint: GET /lineage/{lineageId}/verify

Respuesta: 200 OK

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

Recalcula la raíz a partir del hash de la hoja y de merklePath, luego compárala con rootHash para verificar la integridad sin necesidad de confiar en KLA. Estas pruebas respaldan cada Sealed Evidence Bundle exportado desde el Evidence Room.

Errores y códigos de estado

Los errores devuelven un cuerpo JSON con code y message. Usa el estado HTTP para decidir el comportamiento de reintento.

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

Límites de tasa e idempotencia

Las solicitudes tienen un límite de tasa por inquilino; ante un 429, aplica backoff y reintenta después del valor de Retry-After. Para las llamadas de escritura (POST /agents, POST /decisions.evaluate), envía una cabecera Idempotency-Key con un valor único para que los reintentos sean seguros. Reproducir la misma clave devuelve el resultado original en lugar de crear un duplicado.