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).

Header	Required	Example
Authorization	Yes	Bearer eyJhbGciOi...
x-tenant-id	Yes	acme-prod
Content-Type	On write	application/json

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"
}

Field	Type	Meaning
decision	string	One of allow, warn, require_approval, block.
reasonCodes	string[]	Stable machine-readable codes explaining the outcome.
requiresDeskApproval	boolean	true only for require_approval; caller must pause and await a Decision Desk resolution.
decisionId	string	Identifier for this Decision Request, used to correlate the eventual approval.

Retrieve an Audit Proof

Retrieve the ledger proof for a given Lineage Record (trace). The proof lets you recompute the record's hash chain to confirm it is internally consistent with the root KLA reports. For independent, offline verification that does not rely on a live KLA response, export and verify a Sealed Evidence Bundle from the Evidence Room.

• 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 and compare it against the rootHash returned here to confirm the record's hash chain is internally consistent. Note: this endpoint's rootHash is reported by KLA; for offline, self-contained verification that does not require a live KLA connection, verify a Sealed Evidence Bundle from the Evidence Room with kla evidence verify.

Errors & status codes

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

Status	Code	When it happens
400	invalid_request	Malformed JSON or a failed schema validation.
401	unauthorized	Missing, expired, or invalid bearer token.
403	forbidden	Token valid but lacks permission for this tenant or action.
404	not_found	Unknown agentId, lineageId, or route.
409	conflict	Idempotency key reuse with a different payload, or a duplicate registration.
429	rate_limited	Rate limit exceeded; honor the Retry-After header.
5xx	internal_error	Transient server fault; retry with backoff.

{
  "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.