Documentation

RANKIGI Documentation

Everything you need to integrate the execution proof layer. Copy-paste ready.

Quickstart

First sealed event in under 10 minutes

Install the SDK

bash

npm install @rankigi/sdk

Issue a credential

bash

npx @rankigi/cli init
# Writes RANKIGI_CREDENTIAL and RANKIGI_CHAIN_ID to .env

Add your model key

bash

# Add to .env
ANTHROPIC_API_KEY=sk-ant-...

Wrap a call and seal an event

typescript

import "dotenv/config";
import { Rankigi } from "@rankigi/sdk";
import Anthropic from "@anthropic-ai/sdk";

const rk = Rankigi.fromEnv();
const anthropic = new Anthropic();

const { event_url } = await rk.wrapAnthropic(
  "first-event",
  { prompt: "Say hello" },
  () => anthropic.messages.create({
    model: "claude-sonnet-4-20250514",
    max_tokens: 64,
    messages: [{ role: "user", content: "Say hello" }],
  }),
);

console.log("Sealed event:", event_url);
await rk.close();

Core Concepts

How RANKIGI works

Event Logging

Every agent action is SHA-256 hashed and appended to a tamper-evident chain.

javascript

await rankigi.trackToolCall(
  "query_database",
  { query: "SELECT * FROM accounts" },
  { rows: 42 },
);

// Hash computed automatically:
// sha256("tool_call:query_database:1703...")
// = "a3f9b2c1d8e3f2a1b6c4d7e9"

Hash Chain

Each event references the previous event hash. Any modification breaks the chain instantly.

javascript

// Every event stores its own hash + the previous event hash
{
  "event_id":  "evt_9k2m",
  "hash":      "a3f9b2c1...",   // SHA-256 of this event
  "prev_hash": "7e4d1f8a...",   // SHA-256 of previous event
}

// Tamper detection: hash(event) !== stored_hash → chain broken
// Run GET /api/agents/{id}/verify to check integrity

Policy Enforcement

Define rules that evaluate synchronously before your agent proceeds.

javascript

// Policies evaluated synchronously before the agent proceeds
{
  "name":      "block_wire_transfers",
  "condition": "tool_invoked == 'send_wire'",
  "action":    "block",   // or "flag" / "alert"
  "alert":     true,
}

// Blocked actions return { allowed: false } to your sidecar

Compliance Reports

One-click exports mapped to EU AI Act, SOC 2, and HIPAA.

javascript

const report = await fetch("/api/reports/generate", {
  method: "POST",
  headers: { "Authorization": "Bearer " + apiKey },
  body: JSON.stringify({
    framework:  "EU_AI_ACT",  // or "SOC_2" / "HIPAA"
    agent_ids:  ["agent_123"],
    date_range: { from: "2024-01-01", to: "2024-12-31" },
  }),
});

Integrations

Works with every major framework

Integrate as callbacks, middleware, or direct HTTP, no lock-in.

LangChain (Node.js)

Full callback integration, every chain, tool call, and LLM invocation captured automatically.

LangChain (Python)

Drop-in callback handler for LangChain Python, zero changes to your agent code.

OpenAI Assistants

Wrap assistant runs to capture all tool invocations and model outputs.

AutoGen

Drop-in observability for multi-agent AutoGen conversations.

CrewAI

Monitor every task, crew action, and tool call across your CrewAI pipelines.

Custom HTTP

POST events directly from Python, Go, or any HTTP client, no SDK required.

API Reference

REST API

Base URL: https://rankigi.com/api

Auth header: Authorization: Bearer <API_KEY>

POST/api/ingest

Submit an event to the tamper-evident audit chain

curl

curl -X POST https://rankigi.com/api/ingest \
  -H "Authorization: Bearer RANKIGI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "your-agent-uuid",
    "action": "tool_call",
    "tool": "send_email",
    "severity": "info",
    "payload": {
      "input": { "to": "user@example.com" },
      "output": { "status": "sent" }
    }
  }'

GET/api/agents/{id}/events

Query the full event timeline for an agent

curl

curl https://rankigi.com/api/agents/agent_123/events \
  -H "Authorization: Bearer $RANKIGI_API_KEY"

GET/api/agents/{id}/verify

Verify hash chain integrity, returns any broken events

curl

curl https://rankigi.com/api/agents/agent_123/verify \
  -H "Authorization: Bearer $RANKIGI_API_KEY"

# Response: { "valid": true, "broken_events": [] }

POST/api/snapshots/run

Generate a cryptographic point-in-time snapshot

curl

curl -X POST https://rankigi.com/api/snapshots/run \
  -H "Authorization: Bearer $RANKIGI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "agent_123" }'

GET/api/reports

List all generated compliance reports

curl

curl https://rankigi.com/api/reports \
  -H "Authorization: Bearer $RANKIGI_API_KEY"

GET/api/passport/verify/{passportId}

Publicly verify a passport's audit status, no auth required

curl

curl https://rankigi.com/api/passport/verify/{passportId}

# No authentication required, fully public endpoint
# Response: { ok, result, passport, governance, verified_by }

Public Verification

Verifiable agent audit

Any third party can verify an agent's audit status without a RANKIGI account. Share the verification link or call the API directly.

Shareable links

Every passport has a public verification URL:

url

https://rankigi.com/verify/{passportId}

The page displays agent name, passport status, scope, chain integrity, compliance score, and drift status. Organization name is only shown when the org has enabled their public profile in Settings.

API endpoint

No authentication required. Rate limited to 60 requests/minute per IP.

GET/api/passport/verify/{passportId}

json

// Response schema
{
  "ok": true,
  "result": "pass",
  "passport": {
    "id": "...",
    "agent_name": "payments-processor",
    "version": 3,
    "status": "active",
    "risk_score": 97,
    "authorized_tools": ["stripe_refund", "db_read"]
  },
  "governance": {
    "chain_verified": true,
    "compliance_score": 99,
    "total_governed_events": 12847,
    "drift_status": "nominal"
  },
  "organization": { "name": "Acme Corp" },
  "verified_by": "RANKIGI Open Agent Governance Standard v1.0",
  "verify_url": "https://rankigi.com/verify/..."
}

Integration example

Verify an agent's audit status from your backend before granting access.

javascript

const res = await fetch(
  "https://rankigi.com/api/passport/verify/" + passportId
);
const { result, governance } = await res.json();

if (result !== "pass" || !governance.chain_verified) {
  throw new Error("Agent audit check failed");
}

Policies

Policy enforcement

Define rules that evaluate before an agent action proceeds. Block, flag, or alert on tool invocations, time windows, or custom conditions. Every policy decision is a signed event on the same tamper-evident chain.

json

{
  "policies": [
    {
      "name":      "block_financial_tools",
      "condition": "tool_invoked IN ['send_wire', 'transfer_funds']",
      "action":    "block",
      "alert":     true
    },
    {
      "name":      "off_hours_restriction",
      "condition": "hour(timestamp) NOT IN [9..17]",
      "action":    "flag",
      "alert":     true
    }
  ]
}

SDK Reference

SDK Documentation

Full reference documentation for each SDK.

Node.js SDK

TypeScript/JavaScript SDK with buffer, retry, and Ed25519 signing.

View docs →

Python SDK

Python SDK with daemon-thread transport, async support, and context managers.

View docs →

LangChain Integration

Callback handlers for LangChain (Node.js & Python). Zero-config agent audit.

View docs →

Incident Replay

Select any time window and replay exactly what an agent did - step by step, hash by hash. Recorded actions, input hash, output hash, intent reasoning, and policy flag in chronological order. The forensic record CISOs and auditors actually need.

Dashboard Replay

Navigate to any agent's detail page and click View Replay. Set a start and end time, then hit Replay. Events flow as a timeline - click any event to expand full hashes, intent reasoning, and policy flags. Use the Export button to download the replay as a signed JSON artifact for audit review records.

API Endpoint

GET/api/agents/{id}/replay

Query parameters:

start	ISO 8601 timestamp - beginning of replay window
end	ISO 8601 timestamp - end of replay window (max 24h)
include_intent	boolean - decrypt intent reasoning (Pro+ only)

Verifying the Replay Hash

Every replay response includes a replay_hash - a SHA-256 digest of the entire payload (excluding the hash itself). To verify independently: remove the replay_hashfield, JSON-stringify the remaining object, and compute SHA-256. The result must match. This proves the exported replay file hasn't been tampered with after export.

Example Use Case

“Show me exactly what this agent did during the outage.”

Open the agent's profile in the RANKIGI dashboard
Click View Replay
Set the time window to cover the outage period
Review each step: tool calls, hashes, intent reasoning, policy flags
Click Export to download the replay as a JSON evidence artifact
Share the file with your auditor - the replay_hash proves integrity

Multi-agent chains

Multi-agent federation

Capture deliberation across multi-agent systems. Proposer, validator, and arbiter votes are sealed as separate chain events so the full deliberation record is independently verifiable.

Policy Marketplace

Pre-built policy templates

Import policy templates mapped to common compliance frameworks (SOC 2, EU AI Act, HIPAA) and customize the conditions for your org. Each imported template is versioned and signed on the chain.

Ready to govern your agents?

Start capturing tamper-evident logs in under 5 minutes.

Request access View full API reference

Security Architecture

An audit platform must be held to the same standards it enforces. Here is exactly how RANKIGI is built.

The hash-only storage principle

Every piece of sensitive content your agent handles, inputs, outputs, reasoning, decisions, is converted into a cryptographic hash before it reaches RANKIGI’s infrastructure. A hash is a fixed-length fingerprint of data. Given the hash, it is computationally infeasible to reconstruct the original content.

This means RANKIGI stores proof that something happened without storing what happened. If RANKIGI’s database were compromised tomorrow, the attacker would find a sequence of SHA-256 hashes. Nothing sensitive. Nothing readable. Nothing actionable.

This is not a policy decision. It is an architectural constraint. Your data cannot be exfiltrated from RANKIGI because your data was never stored in RANKIGI.

input_hash  = SHA-256(canonical_json(input_payload))
output_hash = SHA-256(canonical_json(output_payload))
event_hash  = SHA-256(canonical_json(all_event_fields))

Canonical JSON: alphabetically sorted keys, no whitespace, UTF-8.
Deterministic. Reproducible. Independently verifiable.

The hash chain

Every event RANKIGI records includes the hash of the previous event. This forms a chain where each link depends on every link before it. To modify any record you must recompute every hash in the chain from the modified point forward.

This is detectable. RANKIGI’s verification endpoint recomputes every hash on demand and reports the first broken link. The chain is append-only. No UPDATE or DELETE operations on event records.

event_hash_n = SHA-256(canonical_json({
  event_id, agent_id, timestamp, action_type,
  tool_invoked, input_hash, output_hash,
  decision_metadata, execution_result,
  previous_event_hash: event_hash_(n-1),
  chain_index: n
}))

Agent identity: Ed25519 passports

RANKIGI issues Ed25519 passports to every verified agent. Ed25519 is an elliptic curve signature scheme that provides 128-bit security with fast signing and verification. Passport signatures are verified on every federation handshake and every certificate issuance. The public key is published at rankigi.com/.well-known/jwks.json for independent verification.

Intent chain encryption (roadmap)

Client-side AES-256-GCM encryption of agent reasoning is on the roadmap. The design holds the encryption key in your environment, transmits only ciphertext, and chains the ciphertext hash. Track at rankigi.com/changelog.

Infrastructure security

TLS 1.3 for all data in transit.
All data encrypted at rest (AES-256).
API key authentication with SHA-256 hashing. Raw keys never stored.
Role-based access control with immutable audit logging.
Rate limiting on all public endpoints.
Security review completed. Responsible disclosure contact: security@rankigi.com.
Security headers: CSP, HSTS, X-Frame-Options, nosniff, Referrer-Policy.
Dependency vulnerability scanning on every deploy.

Responsible disclosure

Found a vulnerability? Email security@rankigi.com. We respond within 24 hours and will publicly acknowledge responsible disclosures.