Skip to main content

​
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: 
"data_fields_accessed": ["email", "phone", "ssn"]
Fields are auto-classified against 51 predefined sensitive field names.

​
Classification Levels

ClassificationDescriptionRisk Weight
publicPublic data1.0×
internalInternal business data1.3×
piiPersonal data (name, email, phone)2.5×
pii_sensitiveSensitive PII (SSN, passport, tax ID)2.5×
financialFinancial data (credit card, bank account)2.5×
healthHealth/medical data2.5×
authAuthentication credentials3.5×
legalLegal documents2.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.