API Reference

The KLA Control Plane exposes a REST API for governing enterprise AI agents in place. Use it to register the agents you already run, evaluate a policy decision before an action executes, and retrieve the cryptographic proof that an execution was recorded in the tamper-evident ledger. This page documents the three core endpoints plus authentication, error handling, and operational headers. KLA Control Plane is the runtime safety, audit, and governance layer that sits alongside your existing agents rather than replacing them.

All requests are tenant-scoped and JSON over HTTPS. The base URL is:

https://api.kla.digital/v1

Authentication

Every request must carry a bearer token and a tenant identifier. The token is a short-lived OAuth 2.0 access token; the tenant header scopes the request to your organization. See the Authentication doc for how to mint tokens (browser PKCE sign-in for users, or a service-account client secret for machine access).

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

Register an Agent

Declare an agent so KLA can track its identity, ownership, and version in the Agent Registry. Registration returns a stable agentId and a signed manifest hash you can reference from spans and policy decisions.

• Endpoint: POST /agents

Request body

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

Response: 201 Created

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

Evaluate a Policy Decision

Submit an agent action and its context to the policy engine. KLA evaluates your published policies (declarative YAML compiled into signed policy packs) and returns one of four outcomes, in precedence order: allow, warn, require_approval, block. A require_approval decision pauses execution and routes an Escalation to the Decision Desk for human review, which the response signals with requiresDeskApproval: true.

• Endpoint: POST /decisions.evaluate

Request body

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

Response: 200 OK

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

Retrieve an Audit Proof

Verify that an execution was anchored in the cryptographic ledger. KLA records OpenTelemetry spans, redacts PII, and commits them to an append-only ledger that produces Merkle proofs. This endpoint returns the proof for a given Lineage Record (trace), letting you independently confirm the record has not been altered.

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

Response: 200 OK

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

Recompute the root from the leaf hash and merklePath, then compare against rootHash to verify integrity without trusting KLA. These proofs back every Sealed Evidence Bundle exported from the Evidence Room.

Errors & status codes

Errors return a JSON body with code and message. Use the HTTP status to decide retry behavior.

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

Rate limits & idempotency

Requests are rate-limited per tenant; on 429, back off and retry after the Retry-After value. For write calls (POST /agents, POST /decisions.evaluate), send an Idempotency-Key header with a unique value to make retries safe. Replaying the same key returns the original result rather than creating a duplicate.