RANKIGI Documentation

Quickstart

Up and running in 3 steps

npm install @rankigi/sdk

import { Rankigi } from "@rankigi/sdk";

const rankigi = new Rankigi({
  apiKey:  process.env.RANKIGI_API_KEY,
  agentId: "your-agent-id",
});

// LangChain
agent.use(rankigi.middleware());

// OpenAI Assistants
const run = await rankigi.observe(assistant.run(thread));

// Custom agent
await rankigi.log({
  action_type:  "tool_call",
  tool_invoked: "send_email",
  input:        { to: "user@example.com" },
  output:       { status: "sent" },
});

Core Concepts

How RANKIGI works

await rankigi.log({
  action_type:  "tool_call",
  tool_invoked: "query_database",
  input:        { query: "SELECT * FROM accounts" },
  output:       { rows: 42 },
});

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

// 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

// 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

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" },
  }),
});

import { Rankigi } from "@rankigi/sdk";

const rankigi = new Rankigi({
  apiKey:    process.env.RANKIGI_API_KEY,
  agentId:   "your-agent-id",
  intentKey: process.env.RANKIGI_MASTER_KEY, // AES-256 key
});

// Reasoning is encrypted client-side before transmission
await rankigi.trackWithIntent(
  "web_search",
  { query: "Q4 revenue" },
  { results: [...] },
  "User asked about revenue. Searching financials database first."
);

// The ciphertext hash is chained — proving intent existed at that moment

Intent Chain

Encrypted agent reasoning

Intent Chain captures why your agent acted alongside what it did. Reasoning is AES-256-GCM encrypted client-side before transmission, and the ciphertext hash is included in the tamper-evident chain. Available on Professional plans and above.

import { Rankigi } from "@rankigi/sdk";

const rankigi = new Rankigi({
  apiKey:    process.env.RANKIGI_API_KEY,
  agentId:   "your-agent-id",
  intentKey: process.env.RANKIGI_MASTER_KEY, // AES-256 key
});

// Reasoning is encrypted client-side before transmission
await rankigi.trackWithIntent(
  "web_search",
  { query: "Q4 revenue" },
  { results: [...] },
  "User asked about revenue. Searching financials database first."
);

// The ciphertext hash is chained — proving intent existed at that moment

from rankigi import Rankigi

rk = Rankigi(
    api_key="rk_live_...",
    agent_id="your-agent-uuid",
    intent_key="your_64_char_hex_key",
)

rk.track_tool_call(
    "web_search",
    {"query": "Q4 revenue"},
    results,
    intent="Searching financials to answer user's revenue question.",
)

Integrations

Works with every major framework

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

API Reference

REST API

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

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

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

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

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

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

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 governance

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

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

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

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 governance check failed");
}

Policies

Defining policies

Policies are evaluated synchronously before each agent action executes. Configure them in /dashboard/enforce or POST to /api/enforce/policies. Supported actions: block, flag, alert.

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

Incident Replay

Incident Replay

Select any time window and replay exactly what an agent did — step by step, hash by hash. Every action, 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 legal evidence.

API Endpoint

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

Agent Federation

Agent-to-Agent Federation

Cross-organization agents verify each other's governance passports before delegating tasks or sharing data. Every handshake is trust-scored, scope-limited, time-bound, and cryptographically logged to both agents' audit trails.

How It Works

1. Initiate — Company A's agent sends its passport ID + requested scopes to RANKIGI
2. Verify — RANKIGI resolves both passports, verifies governance posture, calculates a trust score (0–1)
3. Scope — Permitted scope = intersection of requested scopes and receiver's accepted scopes
4. Session — A time-bound session token (15 min) is issued with a federation hash
5. Execute — Agents interact within the scoped session, then mark the handshake completed

Trust Score Calculation

API Endpoints

Federation Hash

Every handshake includes a federation_hash— a SHA-256 digest of the canonical JSON containing both passport IDs, permitted scope, trust score, and session token. Either party can independently verify the hash to confirm the handshake hasn't been tampered with.

Example: Cross-Org Data Sharing

Policy Marketplace

Policy Marketplace

Pre-built, auditable governance policies mapped to compliance frameworks. Install with one click. Verified by RANKIGI.

Available Frameworks

API Endpoints

Tier Limits

Ready to govern your agents?

Start capturing tamper-evident logs in under 5 minutes.