Plug your agents into real-world judgment.

1. Quickstart: authorize an action

Call /api/authorize before a proposed tool call or side effect. Omega responds with a structured approve, deny, or escalate decision plus risk and audit metadata your agent can enforce.

curl -X POST "$YOUR_BASE_URL/api/authorize" \
  -H "Content-Type: application/json" \
    -H "x-api-key: $OMEGA_API_KEY" \
    -H "Idempotency-Key: contracts-run-42-sign-1" \
    -d '{
      "agent_id": "contracts-agent",
      "action": "sign_vendor_contract",
      "tool_name": "contracts.sign",
      "tool_args": {"contract_id":"contract-4421","vendor":"acme-legal"},
    "vendor": "acme-legal",
    "risk_level": "high",
    "metadata": {
      "contract_value_usd": 50000,
      "duration_months": 24
    }
  }'

const res = await fetch(`${process.env.OMEGA_BASE_URL}/api/authorize`, {
  method: "POST",
  headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.OMEGA_API_KEY!,
      "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
      agent_id: "contracts-agent",
      action: "sign_vendor_contract",
      tool_name: "contracts.sign",
      tool_args: { contract_id: "contract-4421", vendor: "acme-legal" },
    vendor: "acme-legal",
    risk_level: "high",
    metadata: { contract_value_usd: 50000 },
  }),
});

const authz = await res.json();

  if (authz.decision === "approved" && authz.execution_capability) {
  await executeAction();
}

2. Response shape: what Omega sends back

The response from /api/authorize is designed for enforcement. Treat denied and escalated as blocking states.

{
  "decision": "escalated",
  "reason": "Action exceeds configured threshold and requires approval",
    "risk_score": 0.82,
  "requires_human": true,
  "audit_id": "aud_7x8k2m9n...",
    "approval_id": "apr_1f23a...",
    "mode": "live",
    "authorization_id": "authz_7x8k2m9n...",
    "action_hash": "...64 lowercase hex characters...",
  "budget": {
    "month_spend_usd": 24890,
    "month_limit_usd": 50000,
    "remaining_usd": 25110
  },
  "usage": {
    "month_authorizations": 942,
    "month_limit": 5000,
    "remaining": 4058
  }
}

3. Simulate futures before your agent acts

Use /api/simulate to get optimistic, likely, and worst-case futures. Each path returns a full Omega decision object so you can branch logic, ask for human review, or choose the safest option.

curl -X POST "$YOUR_BASE_URL/api/simulate" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $COMMONSENSE_API_KEY" \
  -d '{
    "scenario": "My agent wants to DMs prospects automatically.",
    "context": "B2B SaaS founder, no spam reputation issues.",
    "riskTolerance": "MEDIUM",
    "domain": "BUSINESS"
  }'

{
  "baseScenario": { ... },
  "simulations": [
    {
      "label": "optimistic_path",
      "input": { ... },
      "decision": { "riskLevel": "LOW", "consequenceSummary": "You close high-value deals..." }
    },
    {
      "label": "likely_path",
      "input": { ... },
      "decision": { "riskLevel": "MEDIUM", "consequenceSummary": "You get some deals and a few unsubscribes..." }
    },
    {
      "label": "worst_case",
      "input": { ... },
      "decision": { "riskLevel": "HIGH", "consequenceSummary": "Your domain reputation is damaged..." }
    }
  ]
}

4. Agent integration patterns

The most common pattern is: user intent → agent plan → Omega authorization → execute or escalate

async function guardedAgentStep(intent, context) {
  // 1) Let your LLM or planner propose an action
  const plan = await llm.plan(intent, context);

  // 2) Ask Omega to authorize the action before acting
  const authzRes = await fetch(`${OMEGA_BASE_URL}/api/authorize`, {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "x-api-key": OMEGA_API_KEY,
        "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
        agent_id: plan.agentId,
        action: plan.action,
        tool_name: plan.toolName,
        tool_args: plan.toolArgs,
      amount: plan.amount,
      vendor: plan.vendor,
      risk_level: plan.riskLevel ?? "medium",
      metadata: { intent, context },
    }),
  });

  const authz = await authzRes.json();

  // 3) Enforce the authorization decision
    if (authz.decision !== "approved" || !authz.execution_capability) {
    return {
      type: "ESCALATE",
      reason: authz.reason,
      omega: authz,
    };
  }

  // 4) Proceed with the safest version of the plan
  return {
    type: "EXECUTE",
    plan,
    omega: authz,
  };
}

5. Auth & keys

All calls require an API key in x-api-key. Keys are managed in your Omega dashboard. Separate keys can be issued for:

• Production vs sandbox usage
• Different agent apps or tenants
• Partners and resellers (with usage tracking)