Navige Technical Reference

Quick Start

The fastest path is the drop-in proxy — change one environment variable and every OpenAI or Anthropic call is governed automatically.

Option A — OpenAI proxy (no code change)

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-openai-key",
    base_url="https://api.navige.ai/v1",        # ← only change needed
    default_headers={"x-api-key": "tl_your_key"}     # ← add TrustLoop auth
)
# Everything else is identical to normal OpenAI usage

Option B — Python SDK (explicit intercept)

pip install trustloop-sdk

from trustloop import TrustLoop

tl = TrustLoop(api_key="tl_your_key", agent_name="my-agent")

# Option 1: explicit intercept
result = tl.intercept("send_email", {"to": "user@example.com"})
if result["allowed"]:
    send_email(...)

# Option 2: decorator — wraps a function, blocks it if not allowed
@tl.guard()
def delete_records(table: str, where: dict):
    ...

Authentication

All authenticated endpoints require your Navige API key. Pass it as a header:

x-api-key: tl_your_key_here

Keys are created when you sign up at navige.ai/signup. Each key belongs to a tenant and carries all associated limits and rules. Retrieve a lost key via POST /api/resend-key with your email.

OpenAI Drop-in Proxy

Endpoint: POST /v1/chat/completions Requires x-api-key

A transparent proxy to the OpenAI Chat Completions API. Set this as your client's base_url. Your OpenAI key goes in the standard Authorization: Bearer header. Navige API key goes in x-api-key.

Headers

Python

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-openai-key",
    base_url="https://api.navige.ai/v1",
    default_headers={
        "x-api-key": "tl_your_key",
        "x-agent-name": "finance-agent"  # optional
    }
)

Node.js

const { OpenAI } = require('openai')

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: 'https://api.navige.ai/v1',
  defaultHeaders: {
    'x-api-key': process.env.TRUSTLOOP_API_KEY,
    'x-agent-name': 'my-agent'
  }
})

Anthropic Drop-in Proxy

Endpoint: POST /proxy/anthropic/v1/messages Requires x-api-key

Transparent proxy to the Anthropic Messages API. Intercepts tool_use content blocks before returning the response to your agent. Same governance pipeline as the OpenAI proxy.

Headers

Python

import anthropic

client = anthropic.Anthropic(
    api_key="sk-ant-your-key",
    base_url="https://api.navige.ai/proxy/anthropic",
    default_headers={
        "x-api-key": "tl_your_key",
        "x-agent-name": "my-claude-agent"
    }
)

Python SDK

pip install trustloop-sdk                      # sync (requests)
pip install "trustloop-sdk[async]"             # + async (httpx)
pip install "trustloop-sdk[langchain]"         # + LangChain helpers
pip install "trustloop-sdk[crewai]"            # + CrewAI helpers
pip install "trustloop-sdk[all]"               # everything

Core client

from trustloop import TrustLoop, TrustLoopBlockedError

tl = TrustLoop(api_key="tl_xxx", agent_name="my-agent")

# Explicit intercept
result = tl.intercept("send_email", {"to": "...", "subject": "..."})
if result["allowed"]:
    send_email(...)

# Guard decorator — raises TrustLoopBlockedError if blocked
@tl.guard("delete_records")
def delete_records(table: str, where: dict):
    ...

# LangChain integration
from trustloop.integrations.langchain import wrap_tools
governed_tools = wrap_tools(tl, tools)

# CrewAI integration
from trustloop.integrations.crewai import governed_tool

@governed_tool(tl)
class SendEmailTool(BaseTool):
    ...

Node.js SDK

npm install trustloop

const { TrustLoop } = require('trustloop')

const tl = new TrustLoop({ apiKey: process.env.TRUSTLOOP_API_KEY, agentName: 'my-agent' })

const result = await tl.intercept('send_email', { to: 'user@example.com' })
if (result.allowed) {
  await sendEmail(...)
}

MCP — Claude Desktop

Connect Claude Desktop by adding Navige as an MCP server in your config. Every tool call Claude makes passes through Navige's governance pipeline.

{
  "mcpServers": {
    "trustloop": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.navige.ai/sse?api_key=tl_xxx"]
    }
  }
}

REST Intercept

Use the REST endpoint when you want explicit control — call it before any sensitive action in your own code, no SDK needed.

POST /api/intercept POST Auth

Evaluates a tool call against your governance rules. Call this before executing any sensitive action. Optionally, include forward_to to have Navige execute the tool on your behalf after approval — single round trip, actual response returned.

Request body

forward_to object

result = requests.post("https://api.navige.ai/api/intercept",
  headers={"x-api-key": "tl_xxx"},
  json={
    "tool_name": "send_email",
    "arguments": {"to": "user@example.com", "subject": "Hello"},
    "agent_name": "my-agent",
    "reason": "User requested a welcome email after completing onboarding",
    "forward_to": {
      "url": "https://api.resend.com/emails",
      "method": "POST",
      "headers": {"Authorization": "Bearer re_xxx"}
    }
  }
).json()
# result → { "allowed": true, "forwarded": true, "status_code": 200, "result": {...} }
# If blocked → { "allowed": false, "decision": "BLOCKED" } — forward_to is never called

Response

{ "allowed": true, "decision": "ALLOWED" }

{ "allowed": true, "decision": "ALLOWED", "forwarded": true, "status_code": 200, "result": { "..." } }

{ "allowed": false, "decision": "BLOCKED", "message": "Blocked by governance rule: ..." }

{ "allowed": false, "decision": "ESCALATED", "status": "pending_approval", "approval_id": "uuid", "payload_hash": "sha256hex", "expires_at": "2026-07-22T14:30:00.000Z" }

After the human approves, retry with approval_id and approved_hash (the value of payload_hash above). Navige verifies the approval and that the payload hasn't changed before allowing.

GET /api/logs GET Auth

Returns the last 100 tool call records for your account, newest first.

Query params

GET /api/stats GET Auth

Returns aggregate counts for the current month plus per-agent breakdown.

{
  "total": 1842,
  "allowed": 1790,
  "blocked": 48,
  "pending": 4,
  "usage": { "plan": "growth", "used": 1842, "limit": 1000000 },
  "agents": {
    "used": 3, "limit": 10,
    "breakdown": [
      { "name": "finance-agent", "total": 920, "allowed": 898, "blocked": 22 }
    ]
  }
}

Approval Rules Auth

Kill-Switch Auth

Tool Registry Auth

Register your real tools so Navige's MCP server advertises them to Claude Desktop instead of the default demo set. Each tool can include a forward_url — when a call is ALLOWED, Navige calls that endpoint and returns the real response.

requests.post("https://api.navige.ai/api/tools",
  headers={"x-api-key": "tl_xxx"},
  json={
    "tool_name": "send_email",
    "description": "Send a transactional email",
    "input_schema": {
      "type": "object",
      "properties": {
        "to": {"type": "string"},
        "subject": {"type": "string"},
        "body": {"type": "string"}
      },
      "required": ["to", "subject", "body"]
    },
    "forward_url": "https://api.resend.com/emails",
    "forward_headers": {"Authorization": "Bearer re_xxx"}
  }
)

Credential Storage

Store an encrypted API key for a tool. Navige injects it automatically into forward_to requests — the agent never holds the credential directly. Credentials are encrypted with AES-256-GCM at rest and never returned by the API.

Pending Approvals Auth

Governance Pipeline

Every call to /api/intercept or through the proxy runs this pipeline in order. The first rule that matches stops evaluation and returns a decision.

AI Rule Caching

To keep latency low, Navige uses two caches:

• Rules cache — governance rules per account, refreshed regularly. Invalidated immediately when you create or delete a rule.
• Decision cache — AI evaluation result per unique tool call pattern, short TTL. Invalidated when rules change. In practice this achieves ~90%+ cache hit rate for agents with consistent calling patterns.

PII & Compliance

Before any tool call is written to the audit log, Navige's compliance middleware automatically:

• Masks PII — emails, phone numbers, card numbers, names, national IDs replaced with [PII MASKED]
• Redacts secrets — API keys, passwords, tokens, bearer credentials replaced with [REDACTED]
• Scores risk — each tool call assigned LOW / MEDIUM / HIGH risk based on tool name and argument patterns

Additional compliance endpoints:

• GET /api/compliance/stats — PII masked count, secrets redacted count, risk breakdown
• GET /api/compliance/dsar — Full GDPR Art. 15 / CCPA data subject access request export (JSON)
• DELETE /api/logs/purge?days=N — Delete logs older than N days (data retention)

Blockchain Anchoring

Every hour, Navige hashes all tool call logs from the previous hour and records the hash on the Polygon Mainnet via a smart contract at 0xd2544fc3164ac0eBfb6B7A2c193800F9651Fc46F.

This creates an independently verifiable tamper-evident record. If any logs are deleted or modified in Supabase, recomputing the hash from the remaining records will not match what's on-chain.

Anchor records are stored alongside your audit logs. Use the Blockchain tab in your dashboard to see every anchor with a direct Polygonscan link, or query the API below to verify programmatically.

GET /api/blockchain/anchors GET Auth

Returns the list of blockchain anchor records for your account. Each record includes the batch hash, Polygon transaction hash, and a pre-computed Polygonscan link so you can verify without any blockchain tooling.

Query params

{
  "contract_address": "0xd2544fc3164ac0eBfb6B7A2c193800F9651Fc46F",
  "anchors": [
    {
      "id": "uuid",
      "log_hash": "0xabc123...",
      "tx_hash": "0xdef456...",
      "log_count": 142,
      "created_at": "2026-07-22T14:00:00.000Z",
      "polygonscan_url": "https://polygonscan.com/tx/0xdef456..."
    }
  ]
}

How to verify a batch independently

1. Export your audit log for the batch's time window
2. Recompute: ethers.keccak256(ethers.toUtf8Bytes(JSON.stringify(records))) over id, tenant_id, tool_name, status, created_at ordered by created_at ascending
3. Compare to log_hash above
4. Open the polygonscan_url → More details → Input data — the same hash is written on-chain

Plan Limits

Limits are enforced at the intercept point. When a limit is exceeded, the API returns HTTP 429 with a clear error message. Usage resets on the 1st of each calendar month.