Events

Event ingestion and real-time risk scoring

Event Ingestion

The events API is the primary entry point for scoring agent actions. Events are validated, persisted, and scored through the 4-layer pipeline in a single synchronous request.

Endpoints

POST /events

Score a single agent event synchronously. Returns the full score response.

POST /events/batch

Submit up to 1,000 events for async processing. Returns event IDs immediately.

Event Schema

Every event must include an action in canonical domain:scope:verb format:

{
  "event_id": "evt-unique-id",
  "action": "mcp:github:pr.create",
  "timestamp": "2026-02-26T10:00:00Z",
  "agent": {
    "agent_id": "code-review-bot",
    "agent_type": "code_review",
    "framework": "langchain",
    "model": "claude-sonnet-4-5-20250929"
  },
  "session": {
    "session_id": "sess-123",
    "user_id": "user-456",
    "started_at": "2026-02-26T09:00:00Z"
  },
  "target": {
    "resource_type": "repository",
    "resource_id": "org/repo-name",
    "sensitivity_level": 2
  },
  "mcp_context": {
    "server_name": "github-mcp",
    "server_id": "srv-789",
    "transport": "stdio",
    "is_verified": true,
    "tool_name": "create_pull_request"
  },
  "data_fields_accessed": [
    {"field": "source_code", "classification": "internal"},
    {"field": "branch_config", "classification": "public"}
  ],
  "preceding_actions": [
    "mcp:github:repo.read",
    "tool:code:lint.execute"
  ],
  "parameters": {
    "title": "Fix authentication bug",
    "base_branch": "main"
  }
}

Scoring Flow

1. Validate API key, check rate limit by customer_id and model_tier
2. Persist event as AgentEvent in PostgreSQL
3. Score with GraphReasoner (forward-chaining + optional GNN + optional Memgraph enrichment)
4. LLM fallback if confidence < 0.8: retrieve RAG context from Memgraph, call Gemini with compliance grounding
5. Save Score record with full decomposition
6. Return EventResponse with score, risk_level, violations, compliance_refs, mitigations

Data Field Classification

Data fields can be submitted as strings or classified objects:

Simple strings

"data_fields_accessed": ["email", "phone", "ssn"]

Fields are auto-classified against 51 predefined sensitive field names.

Classified objects

"data_fields_accessed": [
  {"field": "email", "classification": "pii"},
  {"field": "ssn", "classification": "pii_sensitive"},
  {"field": "credit_card", "classification": "financial"}
]

Explicit classification takes precedence over auto-detection.

Classification Levels

Classification	Description	Risk Weight
public	Public data	1.0×
internal	Internal business data	1.3×
pii	Personal data (name, email, phone)	2.5×
pii_sensitive	Sensitive PII (SSN, passport, tax ID)	2.5×
financial	Financial data (credit card, bank account)	2.5×
health	Health/medical data	2.5×
auth	Authentication credentials	3.5×
legal	Legal documents	2.5×

Batch Processing

For high-volume ingestion, use the batch endpoint:

curl -X POST https://api-production-56df.up.railway.app/events/batch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-ent-20b322cc26bd4d0e" \
  -d '{
    "events": [
      {"event_id": "evt-001", "action": "mcp:github:repo.read", "timestamp": "2026-02-26T10:00:00Z"},
      {"event_id": "evt-002", "action": "mcp:slack:message.send", "timestamp": "2026-02-26T10:01:00Z"}
    ]
  }'

Response (202 Accepted):

{
  "event_ids": ["evt-001", "evt-002"],
  "count": 2
}

Batch events are processed asynchronously by the orchestrator. Use the Scores API to retrieve results.