Referencia de la API | Developer Docs

KLA Control Plane expone dos transportes HTTP bajo la ruta base /v1:

Los procedimientos tRPC generados usan un nombre de operación con puntos, como agents.create. La CLI expone todas las operaciones del catálogo de control plane generado.
Las rutas REST cubren la exportación de Evidence, el transporte de archivos, el registro de políticas, la telemetría y otras superficies propias de cada servicio.

Usa la CLI para los procedimientos tRPC y kla api rest o curl para las rutas REST. El host de API de los ejemplos es la API dev desplegada:

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

El catálogo se genera desde el AppRouter del servidor. El número de operaciones cambia cuando cambian los procedimientos. Ejecuta kla api list para consultar el número actual y kla api doctor para comparar el catálogo integrado con el servidor configurado.

Autenticación y cabeceras de tenant

Cada solicitud lleva un token bearer OAuth 2.0 de corta duración. El claim de tenant verificado proporciona el tenant predeterminado. Conserva los tokens y secretos de cliente en el entorno del servicio que realiza la llamada.

Cabecera	Obligatoria	Semántica
`Authorization`	Sí	`Bearer <access token>` autentica al llamante.
`x-kla-tenant-external-id`	No	Selecciona un tenant por su ID externo cuando el sujeto autenticado tiene una membresía activa en ese tenant. Una selección sin membresía devuelve `403`.
`x-kla-tenant-id`	No	UUID interno del tenant. La autenticación y la pertenencia verificada determinan el tenant.
`Content-Type`	En escrituras JSON	`application/json`.

La CLI envía su KLA_TENANT_ID configurado como x-kla-tenant-id. Los comandos con una selección explícita, como kla evidence export --tenant <external-id>, usan x-kla-tenant-external-id y requieren una membresía activa.

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"

Procedimientos tRPC

El controlador tRPC está montado en /v1. La ruta HTTP de un procedimiento es /v1/<procedure>:

Tipo de procedimiento	Método HTTP	Ejemplo
Mutation	`POST`	`POST /v1/agents.create`
Query	`GET`	`GET /v1/approvals.getPending`
Subscription	Realtime/WebSocket	`traces.stream`

El catálogo generado y el servidor validan la misma entrada Zod. Descubre los esquemas de entrada con:

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

Registrar un agente

agents.create acepta el manifiesto del agente como una cadena YAML. El comando curado llama al mismo procedimiento que el comando genérico:

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 respuesta incluye el identificador del agente registrado. Se necesitan una vinculación de política aprobada y un release antes de que executions.execute pueda ejecutar el agente.

Iniciar e inspeccionar una ejecución

El procedimiento de ejecución devuelve 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"}'

Leer y resolver aprobaciones pendientes

approvals.getPending enumera las Decision Requests pendientes del tenant actual. approvals.decide acepta approve, reject o escalate y requiere un motivo.

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

La API aplica permisos de tenant y reglas maker-checker a la decisión. Un reviewer no puede aprobar una solicitud creada por su misma identidad cuando la política del tenant exige separación de funciones.

Inspeccionar y verificar traces

traces.getTrace devuelve los spans de un trace. Los valores sensibles permanecen enmascarados, salvo que el llamante tenga el permiso independiente de desenmascarado y proporcione una justificación.

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 requiere el permiso trace:verify. Su entrada siempre incluye tenant; los campos de proof se proporcionan cuando el registro de auditoría correspondiente los contiene.

Rutas REST de Evidence

La exportación de Evidence usa un trabajo REST asíncrono de la API. La solicitud acepta una ventana temporal y flags de proofs o payloads sin procesar. evidence:export crea un trabajo y lee trabajos del mismo actor. evidence:list lee trabajos de todo el tenant. evidence:read lee el manifiesto y archivo sellados.

Crear una exportación

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 respuesta contiene exportId, status y pollTimeoutMs. El sondeo termina con completed, completed_with_omissions, failed o canceled.

Consultar, leer el manifiesto y descargar el archivo

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"

El archivo es un paquete sellado de tipo evidence-room-bundle-v1. Verifícalo sin conexión con:

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

El comando kla evidence export crea el trabajo en POST /v1/evidence/export-jobs, consulta GET /v1/evidence/factory/jobs/:exportId y lee el manifiesto y descarga desde las rutas canónicas de Evidence Factory. Usa el origen de API, la selección de tenant y la credencial del contexto de CLI seleccionado.

Comportamiento y errores de las solicitudes REST

Las respuestas REST usan JSON para los metadatos y application/zip para las descargas de archivos. Los códigos de estado habituales son:

Estado	Significado
`400`	Falló la validación de la solicitud o falta el contexto de tenant.
`401`	Falta el token bearer, ha caducado o no es válido.
`403`	Faltan el permiso requerido o la membresía de tenant.
`404`	El recurso o la ruta no existe para el tenant seleccionado.
`409`	La solicitud entra en conflicto con el estado actual del recurso.
`429`	Se superó el límite de tasa del tenant.
`5xx`	Fallo transitorio del servicio o de una dependencia.

Trata una decisión de política fallida, una autorización de aprobación fallida o un preflight de Evidence fallido como una operación fallida. Reintenta solo cuando la respuesta identifica un fallo transitorio y la operación se puede repetir con seguridad.