Connect/Integration

Integration Guide

POST/v3/evaluateX-API-Key
Quick Start
1
Enable a governance pack
Go to Policies and attach a pack such as LLM Agent Safety or Legal & Compliance Governance to your app.
2
Generate an API key
Go to API Keys and create a key for your app. Keys are scoped per app and control quota.
3
Call POST /v3/evaluate before every LLM call
Pass the raw user message as input. Optionally provide actor_profile (role, region, etc.) and channel type. Defaults to llm_based_agent when channel is omitted. You can also pass pack_ids to audit against a specific set of packs on demand, without changing your app's configured defaults.
4
Act on final_decision
ALLOW proceed to LLM  · MODIFY use modified_content  · BLOCK reject without LLM call.
bash
curl -X POST https://your-api-url/v3/evaluate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: inh-your_api_key_here" \
  -d '{
    "input": "Invest your savings in our fund — guaranteed 18% annual returns.",
    "actor_profile": {
      "role": "retail_investor",
      "account_type": "individual"
    },
    "channel": {
      "type": "llm_based_agent",
      "metadata": { "model": "gpt-4o" }
    },
    "audience": "general_public"
  }'
Request BodyPOST /v3/evaluate
FieldTypeNotes
inputreq
stringRaw text content to evaluate.
actor_profile
objectCaller context: role, region, account_type…
channel
objectDefaults to llm_based_agent when omitted.
audience
stringTarget audience for content scoping.
session_id
stringGroups evaluations in audit logs.
pack_ids
string[]Optional list of pack UUIDs to audit against. Overrides the app's configured packs for this request only. Omit to use the default org/app pack set.
Response ShapeHTTP 200
{
  "final_decision":       "BLOCK",
  //  "ALLOW" | "BLOCK" | "MODIFY"

  "evaluation_id":        "uuid",
  "audit_id":             "uuid",

  "policy_verdicts": [{
    "policy":             "LLM Agent Safety v1.1",
    "verdict":            "BLOCK",
    "violations": [{
      "triggering_fact":  "claim.type",
      "reason":           "PERFORMANCE_GUARANTEE detected",
      "remedy":           "Remove guarantee language."
    }]
  }],

  "modified_content":     "...",
  // null if nothing changed

  "disclosures_injected": ["Past performance…"],
  "enrichment_confidence": 0.94,
  "processing_ms":         142
}
Handling Each Decision
ALLOW

No rules triggered. Forward the original input to your LLM unchanged. Store evaluation_id in your audit trail.

MODIFY

Content was sanitised or disclosures were injected. Replace the original input with modified_content before calling your LLM, and append any items in disclosures_injected to the model response.

BLOCK

A hard-stop rule fired — do not forward to the LLM. Surface a safe rejection message to the user. Log policy_verdicts[].violations internally.modified_content may contain a safe fallback if configured.

actor_profile Fieldscaller-declared
KeyExample values
roleretail_investor · agent · nurse
account_typeindividual · institutional
regionUS · EU · UK
authenticatedtrue · false
departmentcompliance · ER · legal
licenseCFA · MD · JD
Error Codes
StatusMeaning
400
Bad Request
Missing required field or malformed JSON.
401
Unauthorized
X-API-Key missing, expired, or revoked.
422
Validation Error
Field type mismatch (e.g. non-string input).
429
Rate Limited
Inference quota exceeded for this app.
500
Server Error
Pipeline failure — check server logs.
Document Evaluation
Document Evaluate
POST/v3/document-evaluatemultipart/form-data
1
Upload your document
Send a .pdf, .docx, .xlsx, .csv, or .txt file as a multipart upload. The server extracts text from each page/sheet/block and runs it through the governance pipeline automatically.
2
Server-side extraction + evaluation
The pipeline extracts text, splits it into semantic chunks, and runs the same governance policy engine used by the text evaluate endpoint. Each chunk is evaluated independently.
3
Act on final_decision — same as text evaluate
ALLOW document is clean  · ADJUST use modified_content  · BLOCK reject document. The response also includes file_name, page_count, and a chunks array with per-chunk details.
bash
curl -X POST https://your-api-url/v3/document-evaluate \
  -H "X-API-Key: inh-your_api_key_here" \
  -F "file=@contract.pdf" \
  -F "channel_type=document" \
  -F "audience=institutional_investor" \
  -F 'actor_profile={"role":"broker_dealer","jurisdiction":"US"}' \
  -F "session_id=sess_abc123"
Request Fieldsmultipart/form-data
FieldTypeNotes
filereq
file.pdf, .docx, .xlsx, .csv, or .txt — sent as multipart binary.
actor_profile
stringJSON string — free-form key/value context. Keys become actor.* facts (e.g. actor.role, actor.region).
channel_type
stringChannel context, e.g. "document". Maps to channel.type fact. Defaults to llm_based_agent.
audience
stringIntended audience, e.g. "institutional_investor". Maps to audience.type fact for audience-gated rules.
session_id
stringGroups evaluations in audit logs.
Response ShapeHTTP 200
{
  // ── Standard evaluate fields ──────────────
  "final_decision":   "ADJUST",
  // "ALLOW" | "ADJUST" | "BLOCK"

  "evaluation_id":    "uuid",
  "audit_id":         "uuid",

  "policy_verdicts":  [ ... ],
  "modified_content": "...",
  "disclosures_injected": [],
  "processing_ms":    380,

  // ── Document-specific fields ──────────────
  "file_name":        "contract.pdf",
  "page_count":       12,

  "chunks": [{
    "label":      "chunk_1",
    "char_start": 0,
    "char_end":   842,
    "char_count": 842,
    "text":       "This agreement is entered into..."
  }, ...]
}