Quick Start

Quick Start (Direct API)

The SDKs are thin wrappers over one endpoint. If you prefer to call it directly, this is the whole contract.

Authorise an action

PythonJavaScriptcURL

import requests

API_KEY = "xb_your_api_key_here"

response = requests.post(
    "https://www.xybern.com/api/v1/enforce/intercept",
    headers={"X-API-Key": API_KEY},
    json={
        "agent_id": "agent_crewai_001",
        "action_type": "send_email",
        "action_content": "Send the Q4 report to cfo@company.com",
        "metadata": {"to": "cfo@company.com", "recipient_external": False,
                     "task": "financial_reporting", "session": "sess_abc123"},
    },
)

result = response.json()
print(result["decision"])    # allow | block | escalate | terminate
print(result["reasoning"])

const API_KEY = "xb_your_api_key_here";

const response = await fetch("https://www.xybern.com/api/v1/enforce/intercept", {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    agent_id: "agent_autogen_001",
    action_type: "write_file",
    action_content: "Write /reports/q4.csv",
    metadata: { path: "/reports/q4.csv", task: "report_generation" },
  }),
});

const result = await response.json();
console.log(result.decision);   // allow | block | escalate | terminate

curl -X POST https://www.xybern.com/api/v1/enforce/intercept \
  -H "X-API-Key: xb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_langgraph_001",
    "action_type": "query_database",
    "action_content": "SELECT * FROM customers",
    "metadata": {"table": "customers", "task": "data_analysis"}
  }'

Response

{
  "ok": true,
  "decision": "escalate",
  "decision_id": "enf_9f2c…",
  "escalation_id": "esc_41aa…",
  "decision_path": "standard",
  "reasoning": "Mandate FIN-004: payments above SAR 500,000 require approval",
  "policies_triggered": [{"name": "…", "decision": "escalate", "reason": "…"}],
  "risk_verdict": {"…": "…"},
  "vault_entry_id": "ve_…",
  "latency_ms": 41
}

decision	What your code must do
allow	Execute the action.
block	Do not execute. reasoning explains which mandate refused it.
escalate	Hold the action. Poll GET /v1/enforce/escalations/{escalation_id}/status (or use the SDK's wait_for_escalation) and execute only when it returns "decision": "allow". Approvals are valid for a short window, a stale approval reads as block.
terminate	The agent's runtime session was killed or exhausted its budget. Stop the whole run.

Fields

Field	Required	Meaning
action_type	yes	What the agent wants to do, for example send_email, payment.execute, tool.execute. Mandates match on this.
action_content	no	Human-readable intent. Content-pattern and semantic mandates evaluate it, so send it. If raw content must never leave your network, run a self-hosted relay or a dedicated deployment; hashing it (XYBERN_REDACT=1 in the SDK) blinds those mandates.
metadata	no	Anything a mandate may evaluate: amount, currency, classification, region, recipient_external, on_behalf_of…
agent_id	no	The registered agent (principal). Strongly recommended.
session_id	no	A runtime session id for live budgets and the kill switch.
grant_id	no	A delegation grant when acting on behalf of another agent.
contract_id	no	An approved intent contract for the fast in-plan path.

Every decision is sealed to the Provenance Vault and can be fetched as an offline-verifiable receipt: GET /v1/enforce/decisions/{decision_id}/receipt.