API Reference

Complete KTP Protocol API Documentation

Draft Specification

This API reference is a draft and subject to change as the protocol evolves. We're refining these endpoints based on early implementation feedback. Your input is valuable! Share questions, suggestions, or implementation challenges in GitHub Discussions.

This reference documents all KTP REST, gRPC, and WebSocket APIs. For integration guidance, see the Developer Guide.

Base URLs

Production:   https://oracle.{zone-id}.ktp
Development:  https://oracle-dev.{zone-id}.ktp
Local:        http://localhost:8080

Authentication

All API requests require mTLS (mutual TLS) authentication with valid agent credentials.

GET /api/v1/trust-proof
Host: oracle.yourzone.ktp
X-KTP-Agent-ID: agent:service-alpha
X-KTP-Zone-ID: blue:production
Authorization: Bearer {jwt-token}

Trust Oracle API

Request Trust Proof

Request a cryptographically signed trust proof for an agent.

REST

POST /api/v1/trust-proof
Content-Type: application/json

{
  "agent_id": "agent:service-alpha",
  "action": "database:read",
  "resource": "users-table",
  "context": {
    "ip_address": "10.0.1.42",
    "session_age": 3600
  }
}

Response (200 OK):

{
  "proof_id": "proof-uuid-12345",
  "agent_id": "agent:service-alpha",
  "trust_score": 72,
  "tier": "analyst",
  "e_base": 85,
  "e_trust": 72,
  "risk_factor": 0.15,
  "issued_at": "2026-01-02T14:30:00Z",
  "expires_at": "2026-01-02T14:30:30Z",
  "signature": "base64-encoded-signature",
  "oracle_quorum": ["oracle-1", "oracle-2", "oracle-3"]
}

gRPC

service TrustOracle {
  rpc RequestProof(TrustProofRequest) returns (TrustProof);
}

message TrustProofRequest {
  string agent_id = 1;
  string action = 2;
  string resource = 3;
  map<string, string> context = 4;
}

message TrustProof {
  string proof_id = 1;
  string agent_id = 2;
  int32 trust_score = 3;
  string tier = 4;
  int32 e_base = 5;
  int32 e_trust = 6;
  float risk_factor = 7;
  google.protobuf.Timestamp issued_at = 8;
  google.protobuf.Timestamp expires_at = 9;
  bytes signature = 10;
  repeated string oracle_quorum = 11;
}

Parameters:

Response Fields:

Error Codes:

Verify Trust Proof

Verify the authenticity and validity of a trust proof.

REST

POST /api/v1/trust-proof/verify
Content-Type: application/json

{
  "proof_id": "proof-uuid-12345",
  "signature": "base64-encoded-signature",
  "agent_id": "agent:service-alpha"
}

Response (200 OK):

{
  "valid": true,
  "reason": null,
  "signature_valid": true,
  "not_expired": true,
  "agent_match": true
}

gRPC

service TrustOracle {
  rpc VerifyProof(VerifyProofRequest) returns (VerifyProofResponse);
}

message VerifyProofRequest {
  string proof_id = 1;
  bytes signature = 2;
  string agent_id = 3;
}

message VerifyProofResponse {
  bool valid = 1;
  string reason = 2;
  bool signature_valid = 3;
  bool not_expired = 4;
  bool agent_match = 5;
}

Get Agent Trust Score

Retrieve the current trust score for an agent.

GET /api/v1/agent/{agent_id}/trust-score

Response (200 OK):
{
  "agent_id": "agent:service-alpha",
  "trust_score": 72,
  "tier": "analyst",
  "e_base": 85,
  "risk_factor": 0.15,
  "last_updated": "2026-01-02T14:30:00Z",
  "trajectory_hash": "sha256:abc123..."
}

Agent Registry API

Register Agent

Register a new agent with the KTP zone.

POST /api/v1/agents
Content-Type: application/json

{
  "agent_id": "agent:service-alpha",
  "name": "Alpha Microservice",
  "capabilities": ["read:data", "write:logs"],
  "metadata": {
    "version": "1.2.3",
    "environment": "production"
  },
  "sponsor": "agent:team-backend"
}

Response (201 Created):
{
  "agent_id": "agent:service-alpha",
  "registered_at": "2026-01-02T14:00:00Z",
  "initial_trust_score": 40,
  "tier": "analyst",
  "genesis_block": "hash:genesis-abc123"
}

Update Agent Metadata

PATCH /api/v1/agents/{agent_id}
Content-Type: application/json

{
  "metadata": {
    "version": "1.2.4"
  }
}

Response (200 OK):
{
  "agent_id": "agent:service-alpha",
  "updated_at": "2026-01-02T15:00:00Z"
}

Deregister Agent

DELETE /api/v1/agents/{agent_id}

Response (204 No Content)

Context Signals API

Submit Sensor Data

Submit real-time context data to the Oracle.

POST /api/v1/risk-factors
Content-Type: application/json

{
  "agent_id": "agent:service-alpha",
  "signals": {
    "body.hardware.cpu": 0.45,
    "body.hardware.memory": 0.67,
    "world.network.latency": 0.12
  },
  "timestamp": "2026-01-02T14:30:00Z"
}

Response (202 Accepted):
{
  "submission_id": "cs-uuid-67890",
  "accepted_signals": 3,
  "rejected_signals": 0
}

Get Context Signals

Retrieve the current Risk Factors for an agent.

GET /api/v1/risk-factors/{agent_id}

Response (200 OK):
{
  "agent_id": "agent:service-alpha",
  "risk_factors": {
    "adversarial_pressure": 0.05,
    "attestation_coverage": 0.18,
    "evidence_density": 0.56,
    "moment_criticality": 0.10,
    "trust_trend": 0.23,
    "update_resistance": 0.15
  },
  "soul": { "soul": 0, "constraint_type": null },
  "r": 0.15,
  "last_updated": "2026-01-02T14:30:00Z"
}

Policy Enforcement API

Enforce Decision

Make an authorization decision based on a trust proof.

POST /api/v1/enforce
Content-Type: application/json

{
  "proof_id": "proof-uuid-12345",
  "action": {
    "type": "database:read",
    "resource": "users-table",
    "risk_level": 45
  }
}

Response (200 OK):
{
  "decision": "allow",
  "reason": "trust_score >= risk_level (72 >= 45)",
  "audit_id": "audit-uuid-99999",
  "recorded_at": "2026-01-02T14:30:01Z"
}

Decision Values:

• allow: Action permitted
• deny: Action denied (trust insufficient)
• veto: Silent veto (Soul constraint triggered)

Audit API (Flight Recorder)

Query Audit Logs

GET /api/v1/audit/logs?agent_id={agent_id}&from={timestamp}&to={timestamp}

Response (200 OK):
{
  "total": 1247,
  "logs": [
    {
      "record_id": "audit-uuid-99999",
      "timestamp": "2026-01-02T14:30:01Z",
      "agent_id": "agent:service-alpha",
      "action": "database:read",
      "decision": "allow",
      "trust_score": 72,
      "risk_level": 45,
      "chain_hash": "sha256:prev-abc123"
    }
  ]
}

Get Decision Geometry

Retrieve detailed decision context for forensics.

GET /api/v1/audit/{record_id}/geometry

Response (200 OK):
{
  "record_id": "audit-uuid-99999",
  "timestamp": "2026-01-02T14:30:01Z",
  "agent": {
    "id": "agent:service-alpha",
    "e_base": 85,
    "e_trust": 72,
    "tier": "analyst"
  },
  "environment": {
    "risk_factors": { "evidence_density": 0.56, "trust_trend": 0.23, "adversarial_pressure": 0.10 },
    "risk_factor": 0.15
  },
  "decision": {
    "outcome": "allow",
    "reason": "trust_score >= risk_level",
    "constraint": null
  }
}

WebSocket API (Real-Time)

Subscribe to Trust Updates

const ws = new WebSocket('wss://oracle.yourzone.ktp/api/v1/stream');

ws.send(JSON.stringify({
  type: 'subscribe',
  agent_id: 'agent:service-alpha',
  events: ['trust_score', 'veto', 'zone_alert']
}));

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  switch(data.type) {
    case 'trust_score':
      console.log(`Score: ${data.old_score} → ${data.new_score}`);
      break;
    case 'veto':
      console.log(`VETO: ${data.reason}`);
      break;
    case 'zone_alert':
      console.log(`ALERT: ${data.message}`);
      break;
  }
};

Event Types:

Rate Limits

Exceeding rate limits returns 429 Too Many Requests.

Data Models

Trust Proof Schema

{
  "proof_id": "string (uuid)",
  "agent_id": "string",
  "trust_score": "integer (0-100)",
  "tier": "enum(observer|analyst|operator|admin)",
  "e_base": "integer (0-100)",
  "e_trust": "integer (0-100)",
  "risk_factor": "float (0.0-1.0)",
  "issued_at": "timestamp (ISO 8601)",
  "expires_at": "timestamp (ISO 8601)",
  "signature": "string (base64)",
  "oracle_quorum": "array[string]"
}

Risk Factors Schema

{
  "agent_id": "string",
  "dimensions": {
    "soul": { "value": "float", "weight": "float" },
    "body": { "value": "float", "weight": "float" },
    "world": { "value": "float", "weight": "float" },
    "time": { "value": "float", "weight": "float" },
    "relational": { "value": "float", "weight": "float" },
    "signal": { "value": "float", "weight": "float" }
  },
  "risk_factor": "float (0.0-1.0)",
  "last_updated": "timestamp (ISO 8601)"
}

SDK Code Generation

Generate client code from our OpenAPI spec:

# Download the OpenAPI spec
curl -O https://oracle.yourzone.ktp/api/v1/openapi.json

# Generate Python client
openapi-generator-cli generate \
  -i openapi.json \
  -g python \
  -o ./ktp-client-python

# Generate TypeScript client
openapi-generator-cli generate \
  -i openapi.json \
  -g typescript-fetch \
  -o ./ktp-client-ts

Or use our official SDKs from SDKs & Libraries.

Related Resources

---

Step-by-step integration tutorial.

---

Working code samples for all endpoints.

---

Protocol specification and transport details.

---

Cryptographic primitives and signature schemes.