SDK Reference

from interven import Client

client = Client(
    api_key="iv_live_...",        # default: env INTERVEN_API_KEY
    gateway_url="https://...",    # default: env INTERVEN_GATEWAY_URL or hosted SaaS
    timeout=30.0,                 # seconds; default 30
    retries=2,                    # 5xx retries; default 2
    agent_id="...",               # default: env INTERVEN_AGENT_ID
    agent_name="...",             # default: env INTERVEN_AGENT_NAME
)

verdict = client.scan(
    method: str,                            # required — "POST", "GET", etc.
    url: str,                               # required — absolute upstream URL
    body: Any = None,                       # request body (dict, list, str)
    headers: dict | None = None,            # request headers
    agent_id: str | None = None,            # override default agent
    agent_name: str | None = None,
    runtime_type: str | None = None,        # "langchain", "langgraph", etc.
    context: str | None = None,             # conversation context for semantic engine
    env: str | None = None,                 # override environment binding
) -> ScanVerdict

client.scan_response(
    trace_id: str,                  # from the original scan
    response_body: Any,             # upstream response (object or text)
    response_status: int = 200,
) -> ScanResponseResult

final = client.wait_for_approval(
    approval_id: str,
    timeout: float = 60.0,          # seconds
    poll_interval: float = 2.0,     # seconds between polls
) -> ApprovalResult

result = client.mint_ephemeral_key(
    ttl_seconds: int = 600,
    max_uses: int = 1,
    scope: dict | None = None,      # {"tools": [...], "verbs": [...]}
    description: str | None = None,
) -> EphemeralKey

ok = client.health()  # -> bool

from interven import guard

@guard(
    api_key: str | None = None,           # default: env
    tool: str | None = None,              # default: auto-detect from function name + body
    operation: str | None = None,         # default: auto-detect
    on_block: Literal["raise", "return_none"] = "raise",
)
def your_function(...):
    ...

from interven import gate

result = gate(
    method: str,
    url: str,
    body: Any = None,
    headers: dict | None = None,
    api_key: str | None = None,
) -> ScanVerdict

import { IntervenClient } from '@interven/sdk-js';

const client = new IntervenClient({
  apiKey: 'iv_live_...',                  // default: env INTERVEN_API_KEY
  gatewayUrl: 'https://...',              // default: env INTERVEN_GATEWAY_URL or hosted
  timeoutMs: 30_000,                      // default 30s
  retries: 2,
  agentId: '...',
  agentName: '...',
});

const verdict = await client.scan({
  method: string,
  url: string,
  body?: unknown,
  headers?: Record<string, string>,
  agentId?: string,
  agentName?: string,
  runtimeType?: string,
  context?: string,
  env?: string,
});

{
  decision: 'ALLOW' | 'DENY' | 'SANITIZE' | 'REQUIRE_APPROVAL';
  risk_score: number;
  risk_band: 'LOW' | 'MED' | 'HIGH' | 'CRITICAL';
  reason_codes: string[];
  trace_id: string;
  tool_name: string;
  operation: string;
  classifications: string[];
  signals: Array<{ engine: string; score: number; details: any }>;
  sanitized_body?: unknown;
  approval_id?: string;
  policy_id?: string;
  policy_name?: string;
}

await client.scanResponse({
  traceId: string,
  responseBody: unknown,
  responseStatus?: number,
});

const final = await client.waitForApproval(approvalId, {
  timeoutMs: 60_000,
  pollIntervalMs: 2_000,
});
// -> { status: 'approved' | 'denied' | 'pending' | 'expired', ... }

const ek = await client.mintEphemeralKey({
  ttlSeconds: 600,
  maxUses: 1,
  scope: { tools: ['slack'], verbs: ['WRITE'] },
  description: 'One-shot Slack post',
});
// -> { key: 'iv_eph_...', ephemeralId, expiresAt, scope }

const ok = await client.health();  // boolean

import { guard } from '@interven/sdk-js';

const safe = guard(yourAsyncFn, {
  apiKey: 'iv_live_...',           // default: env
  tool: 'slack',                   // optional
  operation: 'post_message',       // optional
  onBlock: 'throw',                // 'throw' (default) or 'returnNull'
});

// throws GuardBlockedError on non-ALLOW (unless onBlock = 'returnNull')
await safe(args);

import { gate } from '@interven/sdk-js';

const result = await gate('POST', 'https://...', {
  body: { ... },
  apiKey: 'iv_live_...',
});

if (result.decision === 'ALLOW') {
  // forward result.body to upstream
}

import type {
  Decision,
  RiskBand,
  ScanResponse,
  GateResult,
  IntervenClientOptions,
  GuardOptions,
  EphemeralKeyOptions,
  ApprovalStatus,
} from '@interven/sdk-js';