TerraLinkAPI v1.0

TerraLink API Documentation

Trust infrastructure for AI. Issue certificates for 6 types of RNA (Registered & Notarized & Attestable) Objects.

Proprietary Technology • Patents Pending

Fast Integration

3-line cURL command to issue your first certificate

Production Ready

Enterprise-grade trust infrastructure

6 Object Types

HUMAN, AI, CONTENT, SERVICE, INFRASTRUCTURE, HARDWARE

Base URL

All API requests should be made to: https://terralink-api.agent-genome.com

OpenAPI Specification

Full OpenAPI 3.0 specification for all endpoints. Import into Postman, Swagger UI, or code generators.

TerraLink API v1.0.0

OpenAPI 3.0 Specification

Swagger UI

https://terralink-api.agent-genome.com/api/openapi.json

OpenAPI Spec Previewyaml

openapi: 3.0.0
info:
  title: TerraLink API
  version: 1.0.0
  description: Trust infrastructure for AI - Issue certificates for RNA Objects
servers:
  - url: https://terralink-api.agent-genome.com
paths:
  /v1/rna/enroll:           # Unified enrollment (NEW)
  /v1/voice/enroll:         # Voice biometrics
  /v1/voice/verify:         # Voice verification
  /v1/agents:               # Agent CRUD
  /v1/agents/{id}/drift:    # Drift analytics
  /v1/certificates/*:       # Certificate operations
  /v1/liveness/*:           # Liveness system
  /v1/unified/verify:       # Unified verification
  /v1/witness:              # Physics anchoring
  /v1/organizations/*:      # Org stats & badges

📥 Import to Postman

Copy the openapi.json URL and import as "OpenAPI 3.0" collection

🔧 Generate SDK

Use openapi-generator to create TypeScript, Python, or Go clients

Security Model: Physical Zero-Trust

TerraLink introduces physically-bound certificates—digital identities that only work when the physical hardware device is present and active. This eliminates the entire attack surface of traditional certificate theft.

The Breakthrough

Traditional certificates = File on disk (anyone with the file = can use it)

TerraLink certificates = File + Physical Device Present (file alone = USELESS)

Traditional Certificate Theft (Broken Model)

Server Breach

Attackers copy certificate files from compromised servers

Leaked Backup

Certificates extracted from backup dumps

Insider Threat

Employees copy certificates to USB drives

Memory Extraction

Certificates dumped from running process memory

Phishing Attack

Admin tricked into uploading certificate files

Supply Chain

Compromised dependency steals certificates

Hardware-Bound Protection

Uncopyable

Certificate only works with that specific PUF fingerprint

Unfakeable

Hardware fingerprint cannot be synthesized

Continuous Liveness

Device must be plugged in (continuous heartbeat)

Instant Revocation

Unplug device → cert dies immediately (no CRL needed)

Compromise Detection

Trajectory proof validates hardware integrity <5s

Physical Security

Attacker needs physical possession to use identity

Attack Surface Comparison

Threat	Traditional Cert	Hardware-Bound Cert
Certificate file stolen	❌ Compromised	✅ Useless without device
Server hacked	❌ Attacker uses cert	✅ Device unplugged = invalid
Insider threat	❌ Employee copies cert	✅ Can't use without physical key
Supply chain attack	❌ Malware steals cert	✅ Hardware tamper-evident
CA compromise	❌ Fake certs issued	✅ PUF can't be forged
Memory dump	❌ Cert extracted	✅ Needs real-time device presence

Real-World Impact

🏦 Banking & Finance

"Even if hackers breach our servers, they can't sign transactions without physically stealing the TerraLink Key from our vault."

Perfect for: Wire transfer approval, trading desk operations, vault access

🏥 Healthcare

"Patient records are hardware-bound. If a laptop with certificates is stolen, the certs are useless."

Perfect for: Medical record access, prescription signing, HIPAA compliance

🏛️ Government

"Classified document signing requires physical possession of the hardware key. No remote compromise possible."

Perfect for: Document classification, diplomatic communications, defense operations

🏢 Enterprise

"Our CI/CD pipeline won't deploy unless the hardware attestation device is present in the secure room."

Perfect for: Code signing, deployment approvals, infrastructure access

How It Works

Every hardware key contains a Hardware PUF (Physically Unclonable Function)—a unique fingerprint derived from manufacturing variations at the silicon level.

// Traditional model
const canUseIdentity = hasCertificateFile();

// TerraLink model  
const canUseIdentity = hasCertificateFile() && 
                       physicalDevicePluggedIn() && 
                       heartbeatActive() &&
                       pufAttestationValid() &&
                       trajectoryProofClean();

Hardware Keys Available Q1 2026

TerraLink Keys (USB-C hardware attestation devices) will ship in Q1 2026. Learn more about hardware binding →

Quick Start

Issue your first certificate in under 60 seconds.

Step 1: Register an Object

curl -X POST https://terralink-api.agent-genome.com/v1/certificates/register-agent \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tlk_pro_c788e3b7866574f583a765eb41e74dfc86e13fec0c4447ca" \
  -d '{
    "agentId": "my-ai-agent",
    "name": "My AI Agent",
    "type": "AI",
    "organizationId": "demo-org"
  }'

Step 2: Issue an Identity Certificate

Issue Certificatebash

curl -X POST https://terralink-api.agent-genome.com/v1/certificates/my-ai-agent/issue \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tlk_pro_c788e3b7866574f583a765eb41e74dfc86e13fec0c4447ca" \
  -d '{
    "certificateType": "IDENTITY",
    "validityYears": 1
  }'

Step 3: Get Your Trust Badge

Display Badgehtml

<!-- Embed in your website -->
<img src="https://terralink-api.agent-genome.com/v1/certificates/my-ai-agent/badge.svg" alt="TerraLink Trust Badge" />

That's it!

Your object is now certified. The badge will automatically update based on liveness status.

Authentication

All API requests require an API key passed via the X-API-Key header.

Development API Key

Use this key for testing: tlk_pro_c788e3b7866574f583a765eb41e74dfc86e13fec0c4447ca

Request Format

curl https://terralink-api.agent-genome.com/v1/certificates?organizationId=demo-org \
  -H "X-API-Key: tlk_pro_c788e3b7866574f583a765eb41e74dfc86e13fec0c4447ca"

Error Responses

// Missing API Key
{
  "statusCode": 401,
  "message": "API key is required",
  "error": "Unauthorized"
}

// Invalid API Key
{
  "statusCode": 403,
  "message": "Invalid API key",
  "error": "Forbidden"
}

Unified RNA EnrollmentRECOMMENDED

Single atomic API call to enroll any RNA object. Replaces 5-7 separate API calls with one transaction.

80% Faster Integration

One API call instead of 5-7. Zero race conditions. Atomic transactions. All certificates returned together.

POST/v1/rna/enroll

Atomic enrollment for any RNA object type

Request Body

{
  "objectId": "my-ai-agent",
  "objectType": "AI",        // HUMAN | AI | CONTENT | SERVICE | INFRASTRUCTURE | HARDWARE
  "name": "My AI Agent",
  "organizationId": "demo-org",
  "description": "Customer support chatbot",
  "capabilities": {
    "identity": true,
    "behavioral": {
      "enabled": true,
      "driftTolerance": 15,      // ±15% drift allowed
      "observationPeriod": 30   // Days
    },
    "liveness": true,            // Heartbeat attestation
    "timestampAttestation": true,     // Physics-anchored proofs
    "trustBadge": true
  }
}

Response (201 Created)

{
  "rnaObject": {
    "id": "clz1234567890",
    "objectId": "my-ai-agent",
    "objectType": "AI",
    "name": "My AI Agent",
    "status": "ENROLLED",
    "enrolledAt": "2025-12-29T10:00:00Z"
  },
  "certificates": [
    {
      "type": "IDENTITY",
      "serialNumber": "TL-ID-2025-ABC123",
      "status": "ACTIVE",
      "validUntil": "2026-12-29"
    },
    {
      "type": "BEHAVIORAL",
      "serialNumber": "TL-BH-2025-DEF456",
      "status": "ACTIVE",
      "validUntil": "2026-01-28",
      "driftTolerance": 15
    }
  ],
  "attestation": {
    "attestationId": "att_xyz789",
    "status": "ALIVE",
    "heartbeatUrl": "https://terralink-api.agent-genome.com/v1/liveness/heartbeat",
    "heartbeatInterval": "60 seconds"
  },
  "attestationProof": {
    "entropyValue": standard,
    "attestationFingerprint": "0xabcdef...",
    "anchoredAt": "2025-12-29T10:00:00Z"
  },
  "trustBadge": {
    "badgeSvgUrl": "https://terralink-api.agent-genome.com/v1/certificates/my-ai-agent/badge.svg",
    "publicUrl": "https://terralink.agent-genome.com/verify/my-ai-agent",
    "embedCode": "<a href=...><img src=... /></a>"
  }
}

RNA Objects

TerraLink certifies 6 types of objects. 3 are available now, 3 require hardware integration (Q1 2026).

HUMAN

Voice biometric identity

Use Cases:

•KYC verification
•Call center auth
•Voice enrollment

Certificates:

IDENTITYLIVENESS

AI

AI agents with behavioral drift detection

Use Cases:

•Agent accountability
•Behavioral monitoring
•Drift detection

Certificates:

IDENTITYBEHAVIORAL

CONTENT

Content provenance & integrity

Use Cases:

•Document verification
•Media tracking
•Tamper detection

Certificates:

PROVENANCEINTEGRITY

SERVICE

API keys, OAuth tokens

Hardware Required

Use Cases:

•API key management
•Token rotation
•Credential tracking

Certificates:

IDENTITYLIVENESS

INFRASTRUCTURE

Servers, containers, databases

Hardware Required

Use Cases:

•Server attestation
•Container tracking
•Database integrity

Certificates:

IDENTITYINTEGRITY

HARDWARE

PUF-based physical chips

Hardware Required

Use Cases:

•Chip authentication
•Clone prevention
•Physical security

Certificates:

IDENTITYLIVENESSINTEGRITY

Hardware-Dependent Types

SERVICE, INFRASTRUCTURE, and HARDWARE types require FPGA PUF board integration (Q1 2026). The API accepts these types now, but certificate issuance will fail until hardware is available.

Voice Biometrics

Enroll and verify human identities using voice biometrics with anti-deepfake detection (RawNet3).

POST/v1/voice/enroll

Enroll a user's voice for future verification

Request (multipart/form-data)

curl -X POST https://terralink-api.agent-genome.com/v1/voice/enroll \
  -H "X-API-Key: tlk_pro_c788e3b7866574f583a765eb41e74dfc86e13fec0c4447ca" \
  -F "name=John Doe" \
  -F "externalId=user_12345" \
  -F "audio=@voice_sample.wav"

Response

{
  "success": true,
  "enrollmentId": "enr_abc123",
  "quality": {
    "snr_db": 28.5,
    "duration_sec": 5.2,
    "sample_rate": 16000
  },
  "embedding": {
    "dimension": 512,
    "version": "wav2vec2-base"
  }
}

GET/v1/challenges

Get a challenge phrase for voice verification

{
  "challenge_nonce": "ch_xyz789",
  "phrase": "The quick brown fox jumps over the lazy dog",
  "ttl_seconds": 300,
  "entropy_commitment": "0x1a2b3c4d..."
}

POST/v1/voice/verify

Verify a user's voice against their enrollment

Response

{
  "match": true,
  "confidence": 0.94,
  "processing_time_ms": 87,
  "anti_spoof": {
    "is_live": true,
    "spoof_score": 0.08,
    "technique": "RawNet3"
  },
  "voice_quality": {
    "snr_db": 26.3,
    "duration_sec": 4.8
  },
  "drift_analysis": {
    "kl_divergence": 0.12,
    "within_threshold": true,
    "threshold": 0.30
  }
}

Agent Management

Full CRUD operations for AI agents with behavioral signature tracking.

POST/v1/agents

Create a new AI agent with behavioral signature

Request Body

{
  "name": "CustomerSupportBot",
  "agentId": "agent_cs_001",
  "description": "AI assistant for customer support",
  "traits": {
    "logic": 0.85,
    "empathy": 0.72,
    "creativity": 0.45,
    "assertiveness": 0.60
  }
}

GET/v1/agents

List all agents in your organization

{
  "agents": [
    {
      "id": "agt_xyz123",
      "agentId": "agent_cs_001",
      "name": "CustomerSupportBot",
      "version": 2,
      "driftScore": 0.18,
      "isDrifting": false,
      "lastVerified": "2025-12-29T12:30:00Z"
    }
  ],
  "total": 1
}

GET/v1/agents/{'{agentId}'}

Get agent details

PATCH/v1/agents/{'{agentId}'}

Update agent configuration

DELETE/v1/agents/{'{agentId}'}

Delete an agent

POST/v1/agents/verify

Verify agent behavior matches registered signature

Request Body

{
  "agentId": "agent_cs_001",
  "conversationTokens": [
    {"role": "user", "content": "Hello, I need help"},
    {"role": "assistant", "content": "I'd be happy to help!"}
  ]
}

Response

{
  "authentic": true,
  "driftScore": 0.18,
  "klDivergence": 0.15,
  "threshold": 0.30,
  "dissonanceDetected": false,
  "processingTime": 45
}

Register Objects

Before issuing certificates, you must register your object. This creates an agent signature entry.

POST/v1/certificates/register-agent

Request Body

{
  "agentId": "string",          // Unique ID (e.g., "gpt-4-agent", "[email protected]")
  "name": "string",             // Display name
  "type": "AI",                 // HUMAN | AI | CONTENT | SERVICE | INFRASTRUCTURE | HARDWARE
  "organizationId": "string"   // Your org ID (e.g., "demo-org")
}

Response (201 Created)

{
  "id": "clz1234567890",
  "agentId": "gpt-4-agent",
  "name": "GPT-4 Agent",
  "type": "AI",
  "organizationId": "demo-org",
  "createdAt": "2025-12-28T12:00:00Z"
}

curl -X POST https://terralink-api.agent-genome.com/v1/certificates/register-agent \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tlk_pro_c788e3b7866574f583a765eb41e74dfc86e13fec0c4447ca" \
  -d '{
    "agentId": "gpt-4-agent",
    "name": "GPT-4 Agent",
    "type": "AI",
    "organizationId": "demo-org"
  }'

Agent ID Best Practices

Use domain names for services (e.g., api.acme.com), email addresses for humans (e.g., [email protected]), and descriptive names for AI agents (e.g., gpt-4-agent).

Issue Certificates

Once an object is registered, you can issue 5 types of certificates.

IDENTITY

Proves this is who/what it claims to be

Agent "gpt-4-agent" is certified as an OpenAI agent

LIVENESS

Proves this is happening now, not replayed

Voice sample captured within standards threshold

PROVENANCE

Tracks what this object creates

AI-generated content traced back to model

INTEGRITY

Verifies content is unmodified

Document hash matches original attestation

BEHAVIORAL

BETA

Proves behavior within drift tolerance

Agent behavior has <15% drift from baseline

POST/v1/certificates/{agentId}/issue

Issue IDENTITY, LIVENESS, PROVENANCE, or INTEGRITY certificate

Request Body

{
  "certificateType": "IDENTITY",  // IDENTITY | LIVENESS | PROVENANCE | INTEGRITY
  "validityYears": 1               // 1-5 years
}

Response (201 Created)

{
  "serialNumber": "F8E2C9D1A3B4C5D6...",
  "type": "IDENTITY",
  "status": "ACTIVE",
  "subject": {
    "agentId": "gpt-4-agent",
    "organizationId": "demo-org"
  },
  "issuer": {
    "commonName": "TerraLink Certificate Authority",
    "organizationId": "demo-org"
  },
  "validity": {
    "notBefore": "2025-12-28T12:00:00Z",
    "notAfter": "2026-12-28T12:00:00Z"
  },
  "agentType": "AI"
}

Example: Issue Identity Certificatebash

curl -X POST https://terralink-api.agent-genome.com/v1/certificates/gpt-4-agent/issue \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tlk_pro_c788e3b7866574f583a765eb41e74dfc86e13fec0c4447ca" \
  -d '{
    "certificateType": "IDENTITY",
    "validityYears": 1
  }'

POST/v1/certificates/{agentId}/issue-behavioralBETA

Issue BEHAVIORAL certificate (for AI agents with drift monitoring)

Request Body

{
  "driftTolerance": 15,      // Max allowed drift % (5-30)
  "observationPeriod": 30    // Days to observe behavior (7-90)
}

Response (201 Created)

{
  "serialNumber": "A3B4C5D6E7F8G9H0...",
  "type": "BEHAVIORAL",
  "status": "ACTIVE",
  "subject": {
    "agentId": "gpt-4-agent"
  },
  "behavioralMetrics": {
    "driftTolerance": 15,
    "observationPeriod": 30,
    "currentDrift": 8.2,
    "status": "WITHIN_TOLERANCE"
  }
}

Example: Issue Behavioral Certificatebash

curl -X POST https://terralink-api.agent-genome.com/v1/certificates/gpt-4-agent/issue-behavioral \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tlk_pro_c788e3b7866574f583a765eb41e74dfc86e13fec0c4447ca" \
  -d '{
    "driftTolerance": 15,
    "observationPeriod": 30
  }'

Multiple Certificates Per Object

You can issue multiple certificate types for the same object. For example, an AI agent can have both IDENTITY and BEHAVIORAL certificates.

List & Manage Certificates

Retrieve all certificates for your organization, including their status and metadata.

GET/v1/certificates?organizationId={orgId}

List all certificates for your organization

Query Parameters

• organizationId (required): Your org ID
• status (optional): Filter by ACTIVE | REVOKED | EXPIRED | DEAD
• type (optional): Filter by certificate type

Response (200 OK)

{
  "certificates": [
    {
      "serialNumber": "F8E2C9D1...",
      "type": "IDENTITY",
      "status": "ACTIVE",
      "subject": {
        "agentId": "gpt-4-agent"
      },
      "agentName": "GPT-4 Agent",
      "agentType": "AI",
      "validity": {
        "notBefore": "2025-12-28T12:00:00Z",
        "notAfter": "2026-12-28T12:00:00Z"
      }
    },
    {
      "serialNumber": "A3B4C5D6...",
      "type": "BEHAVIORAL",
      "status": "ACTIVE",
      "subject": {
        "agentId": "gpt-4-agent"
      },
      "behavioralMetrics": {
        "currentDrift": 8.2,
        "driftTolerance": 15,
        "status": "WITHIN_TOLERANCE"
      }
    }
  ],
  "total": 5,
  "summary": {
    "active": 4,
    "revoked": 0,
    "expired": 1,
    "total": 5
  }
}

Example: List All Certificatesbash

curl "https://terralink-api.agent-genome.com/v1/certificates?organizationId=demo-org" \
  -H "X-API-Key: tlk_pro_c788e3b7866574f583a765eb41e74dfc86e13fec0c4447ca"

DELETE/v1/certificates/{serialNumber}/revoke

Revoke a certificate

Response (200 OK)

{
  "serialNumber": "F8E2C9D1...",
  "status": "REVOKED",
  "revokedAt": "2025-12-28T15:30:00Z",
  "reason": "Manual revocation"
}

Example: Revoke Certificatebash

curl -X DELETE "https://terralink-api.agent-genome.com/v1/certificates/F8E2C9D1.../revoke" \
  -H "X-API-Key: tlk_pro_c788e3b7866574f583a765eb41e74dfc86e13fec0c4447ca"

Hardware Tampering Detection

Monitor hardware counter integrity over time. Detect clone attempts, replay attacks, and device tampering.

GET/v1/agents/{'{agentId}'}/drift?period=7d

Get drift analytics for an agent over time

Query Parameters

period: 24h | 7d | 30d | 90d

Response

{
  "agentId": "agent_cs_001",
  "period": "7d",
  "summary": {
    "avgDrift": 0.18,
    "maxDrift": 0.32,
    "minDrift": 0.08,
    "alertCount": 3,
    "verificationCount": 1247
  },
  "timeSeries": [
    {
      "timestamp": "2025-12-20T00:00:00Z",
      "driftScore": 0.15,
      "klDivergence": 0.12,
      "verificationCount": 178
    }
  ],
  "alerts": [
    {
      "id": "alt_123",
      "timestamp": "2025-12-25T14:30:00Z",
      "severity": "WARNING",
      "message": "Drift score exceeded 0.2 threshold",
      "driftScore": 0.23
    }
  ]
}

GET/v1/agents/{'{agentId}'}/thresholds

Get alert thresholds for an agent

{
  "agentId": "agent_cs_001",
  "thresholds": {
    "info": 0.15,
    "warning": 0.20,
    "critical": 0.35
  },
  "autoReject": true,
  "notificationEnabled": true
}

PATCH/v1/agents/{'{agentId}'}/thresholds

Update alert thresholds

Organization Stats

Get a breakdown of registered objects by type. Optimized endpoint that reduces data transfer by 99.5%.

GET/v1/organizations/{orgId}/object-stats

Get object count breakdown by type

Response (200 OK)

{
  "breakdown": {
    "HUMAN": 0,
    "AI": 5,
    "INFRASTRUCTURE": 0,
    "SERVICE": 0,
    "CONTENT": 2,
    "HARDWARE": 0
  },
  "totalObjects": 7,
  "hardwareReadyCount": 0,
  "organizationId": "demo-org",
  "timestamp": "2025-12-28T23:34:21.187Z"
}

Example: Get Object Statsbash

curl "https://terralink-api.agent-genome.com/v1/organizations/demo-org/object-stats" \
  -H "X-API-Key: tlk_pro_c788e3b7866574f583a765eb41e74dfc86e13fec0c4447ca"

Backend Fix Deployed (Dec 28, 2025)

The backend was updated to count by agentType (HUMAN, AI, etc.) instead of certificateType (IDENTITY, BEHAVIORAL, etc.). All existing data has been migrated.

Frontend Integration

// lib/api.ts
export interface ObjectStatsBreakdown {
  HUMAN: number;
  AI: number;
  INFRASTRUCTURE: number;
  SERVICE: number;
  CONTENT: number;
  HARDWARE: number;
}

export interface ObjectStatsResponse {
  breakdown: ObjectStatsBreakdown;
  totalObjects: number;
  hardwareReadyCount: number;
  organizationId: string;
  timestamp: string;
}

export async function getOrganizationObjectStats(
  orgId: string
): Promise<ObjectStatsResponse> {
  const response = await fetch(
    `/api/proxy/v1/organizations/${orgId}/object-stats`,
    {
      method: 'GET',
      headers: { 'X-API-Key': apiKey }
    }
  );

  if (!response.ok) {
    throw new Error('Failed to fetch object stats');
  }

  return response.json();
}

// Usage in Dashboard
const [objectStats, setObjectStats] = useState<ObjectStatsResponse | null>(null);

useEffect(() => {
  async function fetchData() {
    try {
      const stats = await getOrganizationObjectStats('demo-org');
      setObjectStats(stats);
    } catch (error) {
      console.error('Failed to fetch object stats:', error);
      // Fallback to manual calculation
    }
  }
  fetchData();
}, []);

Trust Badges

Embeddable SVG badges that update in real-time based on certificate and liveness status.

GET/v1/certificates/{agentId}/badge.svg

Get trust badge for a specific object

Badge Colors

Trusted (Green)

Active certs + alive

Partial (Yellow)

Missing certs

Expired (Orange)

Certs expired

Revoked/Dead (Red)

Revoked or failed liveness

Embed in HTML

<img 
  src="https://terralink-api.agent-genome.com/v1/certificates/gpt-4-agent/badge.svg" 
  alt="TerraLink Trust Badge" 
  width="120" 
  height="40" 
/>

GET/v1/organizations/{orgId}/badge.svg

Get trust badge for entire organization

<img 
  src="https://terralink-api.agent-genome.com/v1/organizations/demo-org/badge.svg" 
  alt="Organization Trust Badge" 
  width="120" 
  height="40" 
/>

Real-Time Updates

Badges are dynamically generated on each request. No caching required - they always reflect current status.

Liveness & Death Handler

TerraLink tracks liveness via heartbeats (heartbeat timeout). On failure, certificates are auto-revoked.

POST/v1/liveness/heartbeat

Send heartbeat to prove object is alive

Request Body

{
  "agentId": "gpt-4-agent",
  "timestamp": "2025-12-28T12:00:00Z"
}

Response (200 OK)

{
  "agentId": "gpt-4-agent",
  "alive": true,
  "lastHeartbeat": "2025-12-28T12:00:00Z",
  "nextExpected": "2025-12-28T12:00:0standardZ"
}

Example: Send Heartbeatbash

curl -X POST https://terralink-api.agent-genome.com/v1/liveness/heartbeat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tlk_pro_c788e3b7866574f583a765eb41e74dfc86e13fec0c4447ca" \
  -d '{
    "agentId": "gpt-4-agent",
    "timestamp": "2025-12-28T12:00:00Z"
  }'

Death Handler

If an object fails to send a heartbeat within standard seconds:

• Status updated to DEAD
• All certificates auto-revoked
• CRITICAL security event logged
• Trust badge turns red

Liveness Verification

GET/v1/liveness/verify?agentId={agentId}

Check if object is alive

Response (200 OK)

{
  "agentId": "gpt-4-agent",
  "alive": true,
  "lastHeartbeat": "2025-12-28T12:00:00Z",
  "attestationStatus": "VERIFIED",
  "timeSinceLastHeartbeat": "2.5s"
}

Example: Verify Livenessbash

curl "https://terralink-api.agent-genome.com/v1/liveness/verify?agentId=gpt-4-agent" \
  -H "X-API-Key: tlk_pro_c788e3b7866574f583a765eb41e74dfc86e13fec0c4447ca"

KYC Liveness with Hardware Attestation

Voice-based liveness verification with anti-deepfake detection. Proofs are now hardware-attested using Earth's electromagnetic conditions.

🌍

Hardware-Attested Proofs

Liveness proofs include real-time measurements of environmental entropy (standard frequency), entropy level (entropy index), and external entropy conditions (Bz field). These values change continuously, making timestamp forgery impossible.

GET/v1/identities/{'{id}'}/liveness/challenge

Get random phrase challenge for voice verification

Response (200 OK)

{
  "phrase": "sunset river dolphin",
  "challengeId": "ch_abc123",
  "expiresAt": "2025-12-29T16:37:45.604Z"
}

POST/v1/identities/{'{id}'}/liveness?challengeId={challengeId}

Verify voice liveness with anti-deepfake detection

Request Body

{
  "audio": "base64_encoded_audio_data",
  "antiDeepfake": true
}

Response (200 OK)

{
  "alive": true,
  "confidence": 0.94,
  "voiceMatch": 0.92,
  "antiDeepfake": {
    "isHuman": true,
    "spoofScore": 0.03,
    "method": "RawNet3"
  },
  "phraseMatch": {
    "matched": true,
    "confidence": 0.89
  },
  "proof": {
    "hash": "a1b2c3...",
    "timestamp": "2025-12-29T15:37:15.604Z",
    "expiresAt": "2025-12-29T15:42:15.604Z",
    "physics": {
      "entropy_value": 7.467,
      "entropy_index": 1.06,
      "bz": -2.19,
      "sferics": 43
    },
    "fingerprint": "74f954..."
  }
}

Attestation Parameters

• entropy_value: Earth's natural EM resonance (typically ~standard frequency)
• kp: Geomagnetic activity index (0-9, lower = quieter)
• bz: Solar wind magnetic field strength (nT)
• sferics: Atmospheric electrical discharge count
• fingerprint: Cryptographic hash of combined EM conditions

Unified Verification

Verify both human voice and AI agent in a single API call. Perfect for human-AI interactions.

POST/v1/unified/verify

Combined human + AI verification in one request

Request (multipart/form-data)

curl -X POST https://terralink-api.agent-genome.com/v1/unified/verify \
  -H "X-API-Key: tlk_pro_c788e3b7866574f583a765eb41e74dfc86e13fec0c4447ca" \
  -F "externalId=user_12345" \
  -F "agentId=agent_cs_001" \
  -F "audio=@voice_sample.wav" \
  -F 'conversationTokens=[{"role":"user","content":"Hello"}]' \
  -F "challengeNonce=ch_xyz789"

Response

{
  "unifiedAuthentic": true,
  "voiceResult": {
    "match": true,
    "confidence": 0.94,
    "anti_spoof": {
      "is_live": true,
      "spoof_score": 0.08
    },
    "drift_analysis": {
      "kl_divergence": 0.12,
      "within_threshold": true
    }
  },
  "agentResult": {
    "authentic": true,
    "driftScore": 0.18,
    "klDivergence": 0.15
  },
  "entropyChain": "0xabcdef1234567890...",
  "unifiedProof": "0x9876543210fedcba...",
  "timestamp": "2025-12-29T12:00:00Z"
}

Use Case: AI Customer Service

Verify the human caller is who they claim AND the AI agent responding is behaving authentically—all in one API call.

Timestamp Attestation

Anchor any hash to real-world electromagnetic conditions. Creates unforgeable timestamps.

GET/v1/witness

Get current physics state for manual anchoring

{
  "timestamp": "2025-12-29T10:00:00Z",
  "entropy": {
    "frequency": standard,
    "amplitude": 0.42
  },
  "entropyLevel": {
    "entropy_index": 2,
    "status": "quiet"
  },
  "externalEntropy": {
    "bz": -1.2,
    "speed": 380
  },
  "sferics": 1247,
  "fingerprint": "0xabcdef..."
}

POST/v1/witness

Anchor a hash to current physics state

Request Body

{
  "hash": "0x1234567890abcdef...",
  "metadata": {
    "type": "document",
    "description": "Contract v1.2"
  }
}

Response

{
  "proofId": "prf_xyz789",
  "anchoredAt": "2025-12-29T10:00:00Z",
  "physics": {
    "entropy_value": standard,
    "entropy_index": 2,
    "bz": -1.2,
    "sferics": 1247
  },
  "fingerprint": "0xabcdef...",
  "verificationUrl": "https://terralink-api.agent-genome.com/v1/witness/verify/prf_xyz789"
}

POST/v1/witness/verify

Verify a hardware-attested proof

{
  "proofId": "prf_xyz789",
  "valid": true,
  "anchoredAt": "2025-12-29T10:00:00Z",
  "attestationMatch": true,
  "hashMatch": true
}

Why Hardware Attestation?

Earth's electromagnetic conditions are unpredictable and globally verifiable via NASA/NOAA. This makes timestamp forgery mathematically impossible—the attacker would need to predict future physics to backdate a proof.

Hardware Integration [Q1 2026]

FPGA PUF board integration for SERVICE, INFRASTRUCTURE, and HARDWARE object types.

Hardware Required

Hardware Requirements

• FPGA PUF Board: Physical unclonable function chip
• <5s Compromise Detection: Real-time trajectory analysis
• 60s Liveness Proofs: Physics-based attestation
• 100% Clone Prevention: Hardware-bound secrets

Current Status:

Chip preparation in progress

View Full Roadmap

Beta Program

Error Reference

Standard HTTP status codes with structured error responses.

400

Bad Request

{
  "statusCode": 400,
  "message": "Invalid agent type. Must be one of: HUMAN, AI, CONTENT, SERVICE, INFRASTRUCTURE, HARDWARE",
  "error": "Bad Request"
}

401

Unauthorized

{
  "statusCode": 401,
  "message": "API key is required",
  "error": "Unauthorized"
}

403

Forbidden

{
  "statusCode": 403,
  "message": "Invalid API key",
  "error": "Forbidden"
}

404

Not Found

{
  "statusCode": 404,
  "message": "Agent not found: gpt-4-agent",
  "error": "Not Found"
}

500

Internal Server Error

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Internal Server Error",
  "requestId": "req_1234567890"
}

Code Examples

Complete workflows in multiple programming languages.

NEW API

Create AI Agent with Traits

Send personality traits (0.0-1.0 scale) and the server computes harmonic signatures automatically. No IP exposure in client code.

// Create AI Agent with Traits (Recommended)
const response = await fetch('https://terralink-api.agent-genome.com/v1/agents', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'tlk_pro_c788e3b7866574f583a765eb41e74dfc86e13fec0c4447ca'
  },
  body: JSON.stringify({
    agentId: 'emily-001',
    name: 'Emily',
    description: 'Customer support agent',
    traits: {
      logic: 0.8,        // 0.0 - 1.0 scale
      empathy: 0.7,
      creativity: 0.6,
      assertiveness: 0.5,
      curiosity: 0.6,    // optional
      precision: 0.7     // optional
    }
  })
});

const agent = await response.json();
// Server returns computed harmonics:
// {
//   harmonicTable: [{ frequency: standard, attribute: "Grounding", ... }],
//   baseValue: standard,
//   rejectionBandStart: 38,
//   _meta: { computedFromTraits: true }
// }

✓ No client-side frequency calculations✓ IP-protected harmonic computation✓ Backward compatible

Complete Example: Register + Issue + Verify

const API_BASE = 'https://terralink-api.agent-genome.com';
const API_KEY = 'tlk_pro_c788e3b7866574f583a765eb41e74dfc86e13fec0c4447ca';

// Step 1: Register Agent
async function registerAgent() {
  const response = await fetch(
    `${API_BASE}/v1/certificates/register-agent`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': API_KEY
      },
      body: JSON.stringify({
        agentId: 'my-ai-agent',
        name: 'My AI Agent',
        type: 'AI',
        organizationId: 'demo-org'
      })
    }
  );
  return response.json();
}

// Step 2: Issue Identity Certificate
async function issueCertificate(agentId) {
  const response = await fetch(
    `${API_BASE}/v1/certificates/${agentId}/issue`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': API_KEY
      },
      body: JSON.stringify({
        certificateType: 'IDENTITY',
        validityYears: 1
      })
    }
  );
  return response.json();
}

// Step 3: Get Trust Badge URL
function getBadgeUrl(agentId) {
  return `${API_BASE}/v1/certificates/${agentId}/badge.svg`;
}

// Run workflow
async function main() {
  try {
    const agent = await registerAgent();
    console.log('Agent registered:', agent);

    const cert = await issueCertificate(agent.agentId);
    console.log('Certificate issued:', cert);

    const badgeUrl = getBadgeUrl(agent.agentId);
    console.log('Badge URL:', badgeUrl);
  } catch (error) {
    console.error('Error:', error);
  }
}

main();

Need Help?

Check the OpenAPI spec for interactive API exploration, or visit our roadmap for upcoming features.