API reference

Authentication

Your API key comes from the Trace Portal: shown once at registration, rotatable any time under API Keys. Your organization is derived from the key, so requests never need to state it.

curl https://aegara.ai/v1/stats \
  -H "Authorization: Bearer aegara_your_key_here"

Errors and limits

Ingest events

Submit one AI Action Event. Returns 202 once the event is durably queued.

Submit up to 500 events in one request as a bare JSON array: [ { ...event }, { ...event } ].

curl -X POST https://aegara.ai/v1/events \
  -H "Authorization: Bearer $AEGARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trace_id": "trace-checkout-4821",
    "ai_system_id": "support-agent",
    "ai_model_name": "gpt-4o",
    "capability_invoked": "chat.completions",
    "primitive_type": "CALL",
    "actor": { "trigger_type": "user", "user_id": "u-9214", "system_id": null },
    "resources_accessed": [ { "resource_type": "record", "resource_id": "acct-..." } ],
    "fields_accessed": ["plan_name", "renewal_date"],
    "fields_not_accessed": ["payment_method", "tax_id"],
    "systems_contacted": [ { "system_id": "billing-api", "direction": "outbound", "protocol": "https" } ],
    "actions_taken": ["lookup_account"],
    "outputs_generated": [ { "output_type": "ai_response" } ],
    "memory_activity": { "memory_written": false, "memory_read": false, "memory_keys": [] },
    "explicit_negatives": ["No payment data was read"],
    "risk_signals": { "data_sensitivity": "internal", "sensitive_domains": [], "potential_external_exposure": false },
    "schema_version": "1.0.0",
    "environment": "production"
  }'

Event schema

The six behavior primitives: READ, TRANSFORM, WRITE, CALL, STORE, ROUTE. Sensitivity levels: public, internal, confidential, restricted. Sensitive domains: finance, hr, customer_data, intellectual_property, legal, health, credentials, security.

Query events

Traces and stats

Reconstructs a full multi-step workflow in order.

Aggregate counts by primitive, sensitivity, and system.

Per-AI-system rollup: totals, first and last seen, unique users, primitive and sensitivity breakdowns, and edge_seen, whether that system has sent edge inspection verdicts.

Per-user activity rollup.

Sense

Sense infers sensitivity from behavioral metadata across five content-free layers, joined by optional Layer 0 verdicts computed in your environment.

Per-event reasoning: each signal names its layer, the pattern that matched, and the inferred sensitivity and domain.

Tell Sense it got one wrong, or set the classification explicitly. Overrides are append-only with full history.

Discovery

Every new ai_system_id that appears for your organization is registered and can be triaged.

Blocked systems are refused at ingestion.

Policies

Real-time rules evaluated against every event as it ingests.

curl -X POST https://aegara.ai/v1/policies \
  -H "Authorization: Bearer $AEGARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "External exposure of confidential data",
    "enabled": true,
    "severity": "critical",
    "conditions": [
      { "field": "data_sensitivity", "operator": "equals", "value": "confidential" },
      { "field": "potential_external_exposure", "operator": "is_true" }
    ],
    "webhook_url": "https://example.com/hooks/aegara"
  }'

Webhook delivery

When a rule with a webhook_url fires, Aegara POSTs the alert with three delivery attempts and backoff. Each request carries X-Aegara-Delivery-Id and, when a signing secret exists, X-Aegara-Signature: an HMAC-SHA256 of the raw body with your per-policy secret, returned once at policy creation. Verify the signature before trusting the payload.

Alerts

System-managed alerts (first-seen discovery, edge inspection policy notices) appear here beside your own rules' alerts.

API keys

Keys are listed masked and can be created and revoked per integration.

SDK

npm install @aegara/sdk. One wrap call instruments OpenAI, Anthropic, Gemini, Bedrock, Cohere, and Mistral clients via auto-detection, and a LangChain callback handler covers 30-plus providers. Full usage lives in the package README.

import { Aegara } from "@aegara/sdk";
const aegara = new Aegara({ apiKey: process.env.AEGARA_API_KEY });
const openai = aegara.wrap(new OpenAI({ apiKey: "sk-..." }), {
  ai_system_id: "support-agent",
  org_id: "org-...",
});

Edge value inspection