API Reference | TRA-CE.ai

Base URL

https://tra-ce.ai/api/v1

All API endpoints are relative to this base URL. Responses are JSON unless otherwise noted.

Authentication

Authenticate every request by including your API key in the X-API-Key header.

Header

X-API-Key: your_api_key_here

API keys are generated during onboarding or via the admin panel. Keys are scoped to a specific tenant and can be rotated at any time.

Rate Limits

Standard plans: 100 requests/minute
Enterprise plans: 1,000 requests/minute

Rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response. Exceeding limits returns HTTP 429.

Key Endpoints

POST /events Ingest security events

Submit one or more security events for causal analysis. Events are normalized, enriched, and added to the causal graph.

Request Body

{
  "events": [
    {
      "event_type": "authentication",
      "source": "okta",
      "timestamp": "2026-03-06T14:30:00Z",
      "actor": "user@company.com",
      "action": "login.failed",
      "target": "admin-portal",
      "metadata": {"ip": "203.0.113.42", "user_agent": "..."}
    }
  ]
}

POST /causal/analyze Run causal chain analysis

Analyze ingested events and build causal chains. Returns chains with confidence grading (PROVABLE, MIXED, INFERRED).

Response

{
  "chains": [
    {
      "chain_id": "ch-abc123",
      "confidence": "PROVABLE",
      "nodes": [...],
      "edges": [...],
      "mitre_techniques": ["T1566.001", "T1003.001"]
    }
  ]
}

GET /causal/live Real-time chain updates (SSE)

Server-Sent Events stream of live causal chain updates. Connect and receive real-time notifications as new chains are built or updated.

POST /ai/investigate AI investigation analysis

Submit a causal chain for AI-powered investigation. Returns a narrative summary, root cause analysis, and recommended actions.

POST /ai/triage AI alert prioritization

Submit alerts for AI-ranked prioritization with causal context. Returns severity scores and recommended investigation order.

Code Examples

curl

curl -X POST https://tra-ce.ai/api/v1/events \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "event_type": "authentication",
      "source": "okta",
      "timestamp": "2026-03-06T14:30:00Z",
      "actor": "user@company.com",
      "action": "login.failed"
    }]
  }'

Python

import httpx

client = httpx.Client(
    base_url="https://tra-ce.ai/api/v1",
    headers={"X-API-Key": "your_api_key_here"},
)

# Ingest events
resp = client.post("/events", json={
    "events": [{
        "event_type": "authentication",
        "source": "okta",
        "timestamp": "2026-03-06T14:30:00Z",
        "actor": "user@company.com",
        "action": "login.failed",
    }]
})
print(resp.json())

# Analyze causal chains
chains = client.post("/causal/analyze").json()
for chain in chains["chains"]:
    print(f"{chain['chain_id']}: {chain['confidence']}")