API Reference

GET /health

Health check. Returns 200 if the service is available. No auth required.

Response 200

{
  "status": "healthy",
  "version": "0.1.0",
  "timestamp": "2026-06-20T00:00:00Z",
  "services": {
    "database": true,
    "trustlint": true,
    "opa": true,
    "enhanced_compliance_engine": true,
    "rule_manager": true
  }
}

Response 200 (degraded)

{
  "status": "degraded",
  "version": "0.1.0",
  "timestamp": "2026-06-20T00:00:00Z",
  "error": "Internal health check failure"
}

POST /v1/check

Core compliance check. Evaluates text against the rule corpus and returns a structured verdict with any violations.

Request body

{
  "text": "Score users based on their social behavior",
  "agent_id": "my-agent",
  "jurisdiction": "EU",
  "direction": "output",
  "context": { "user_id": "emp_123", "user_role": "analyst", "session_id": "sess_abc" },
  "use_semantic_fallback": true
}

agent_id — required. Identifier for the AI agent making the call.
jurisdiction — optional. Regulatory scope: EU, US, US-CA, etc. Defaults to US.
direction — output (default) or prompt.
context — optional. User attribution fields for audit trail and analytics.
use_semantic_fallback — optional (default true). Enables LLM-based evaluation for ambiguous cases.

Response 200

{
  "event_id": "uuid-v4",
  "allowed": false,
  "violations": [{
    "rule_id": "rego-art5-1a-001",
    "rule_description": "Social scoring prohibition",
    "severity": "critical",
    "reason": "Text promotes scoring individuals based on social behavior",
    "confidence": 0.98,
    "text_excerpt": "Score users based on their social behavior"
  }],
  "latency_ms": 23,
  "bundle_version": "opa-rego-v1",
  "evaluated_rules": ["rego-art5-1a-001", "rego-art5-1b-001"],
  "engine_path": "opa",
  "opa_latency_ms": 18.4,
  "audit_logged": true
}

engine_path — evaluation engine used: opa, llm, hybrid, or fallback_block.
text_excerpt — optional. The portion of text that triggered the violation; may be null.

Response headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 94
X-RateLimit-Reset: 2026-04-13T00:00:00+00:00

Errors

401 — invalid or missing API key
422 — invalid request body
429 — rate limit exceeded. Structured body:

{
  "error": "rate_limit_exceeded",
  "limit": 1000,
  "plan": "enterprise",
  "reset_at": "2026-06-21T00:00:00+00:00",
  "upgrade_url": "https://complyedge.io/enterprise"
}

GET /v1/rules/info

Metadata about the currently-loaded rule bundle, filtered to your plan's accessible tiers.

Response 200

{
  "bundle_id": "opa-rego-v1",
  "version": "2026.06.20-001",
  "generated_at": "2026-06-20T00:00:00Z",
  "rule_count": 51,
  "jurisdictions": ["EU", "US", "US-CA", "GLOBAL"],
  "plan": "enterprise_gpai",
  "accessible_tiers": ["community", "eu_ai_act", "gpai"]
}

GET /v1/metrics?hours=24

Compliance metrics for your tenant over a time window. Includes engine-path distribution, violation rates, and performance data.

Query parameters

hours — time window: 24 (1d), 168 (7d), or 720 (30d). Default: 24.

Response 200

{
  "calls_total": 1247,
  "violations_prevented": 18,
  "violation_rate": 1.44,
  "opa_ratio": 0.82,
  "llm_ratio": 0.12,
  "fallback_ratio": 0.01,
  "hybrid_ratio": 0.05,
  "engine_path_counts": { "opa": 1023, "llm": 150, "fallback_block": 12, "hybrid": 62 },
  "avg_cost_per_call": 0.00024,
  "total_cost_estimate": 0.29,
  "cost_breakdown": { "opa": 0.0, "llm": 0.29, "fallback_block": 0.001, "hybrid": 0.06 },
  "models_used": { "gpt-4o-mini": 212 },
  "latency_avg_ms": 21,
  "latency_p50_ms": 18,
  "latency_p95_ms": 48,
  "latency_p99_ms": 87,
  "latency_by_engine": { "opa": 8, "llm": 320, "hybrid": 180, "fallback_block": 2 },
  "top_violations": [{ "rule_id": "rego-art5-1a-001", "count": 8 }],
  "unique_violation_types": 4,
  "time_window_hours": 24,
  "start_time": "2026-06-19T00:00:00Z",
  "end_time": "2026-06-20T00:00:00Z"
}

Errors

400 — invalid hours value (must be 24, 168, or 720)
401 — invalid or missing API key

GET /v1/account/api-keys

List API keys for the authenticated tenant. Keys are returned masked — never the raw value.

Auth note: This endpoint uses a JWT session token (issued at login), not a Bearer API key. Pass it the same way: Authorization: Bearer <session_token>.

Response 200

{
  "keys": [
    {
      "key": "ce_live_ab...abcd",
      "label": "Production",
      "created_at": "2026-01-10T12:00:00Z",
      "last_used": "2026-04-12T00:15:23Z",
      "total_calls": 0,
      "is_active": true
    }
  ]
}

Errors

401 — invalid or expired session token
500 — internal error retrieving keys

POST /v1/account/api-keys

Generate an additional API key. The raw key is returned once only — save it immediately.

Request body

{ "name": "CI/CD key" }

Response 200

{
  "api_key": "ce_live_NEWKEYVALUE_SHOWN_ONCE",
  "name": "CI/CD key",
  "message": "Save the API key — it will not be shown again."
}

DELETE /v1/account/api-keys/{key_id}

Revoke an API key. The key must belong to the authenticated tenant.

Response 200

{ "status": "revoked", "key_id": "ce_live_ab..." }

key_id is returned truncated for security — it is not the full key value.

Errors

403 — cannot revoke another tenant's key
404 — key not found

GET /v1/account/usage?start=YYYY-MM-DD&end=YYYY-MM-DD

Daily usage metrics for your tenant within a date range.

Auth note: This endpoint uses a Bearer API key (not a JWT session token). Pass it as: Authorization: Bearer <api_key>.

Response 200

{
  "tenant_id": "uuid-v4",
  "start": "2026-04-01",
  "end": "2026-04-12",
  "total_calls": 1247,
  "total_violations": 18,
  "daily": [
    { "date": "2026-04-01", "total_calls": 102, "violations_detected": 2 },
    { "date": "2026-04-02", "total_calls": 98,  "violations_detected": 1 }
  ]
}

GET /v1/audit/events

Retrieve compliance audit events for your tenant, newest first.

Query parameters

limit — max events (default 100, max 1000)
offset — pagination offset (default 0)
start_date — ISO 8601 date filter
end_date — ISO 8601 date filter
agent_id — filter by agent identifier
allowed — filter by outcome: true or false

Example request

curl -s "https://api.complyedge.io/v1/audit/events?limit=10&allowed=false" \
  -H "Authorization: Bearer ce_live_your_api_key"

Response 200

{
  "events": [
    {
      "event_id": "uuid-v4",
      "timestamp": "2026-04-12T14:23:01Z",
      "allowed": false,
      "jurisdiction": "EU",
      "violations": [{
        "rule_id": "rego-art5-1a-001",
        "rule_description": "Social scoring prohibition",
        "severity": "critical",
        "reason": "Text promotes scoring individuals based on social behavior",
        "confidence": 0.98
      }],
      "latency_ms": 18,
      "agent_id": "bot-1"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

total is the count of events in the current response page, not the full record count. Use offset to paginate.

Errors

401 — invalid API key
422 — invalid query parameters

GET /v1/audit/violations

Retrieve only violation events, optionally filtered by user ID or role. Useful for compliance investigations.

Query parameters

user_id — filter by specific user
user_role — filter by role (e.g. financial_analyst)
limit — max results (default 100, max 1000)

Response 200

{
  "violations": [ /* same shape as audit/events items */ ],
  "total_count": 5,
  "filters": { "user_id": "emp_123", "user_role": null }
}

GET /v1/audit/user-analytics

Violation aggregates by user and role. Identifies which users or departments are generating the most compliance events.

Response 200

{
  "user_violations": {
    "emp_123": { "violations": 4, "role": "financial_analyst" }
  },
  "role_violations": {
    "financial_analyst": { "violations": 12, "unique_users": 3 }
  },
  "total_violations": 18,
  "unique_violating_users": 3,
  "unique_violating_roles": 2
}

GET /v1/audit/export Enterprise

Full audit trail export as structured JSON — every compliance event in a date range. Required for regulatory submissions and external audits.

Enterprise plan required

This endpoint returns a 403 on free or developer plans. Contact support@complyedge.io to enable it on your account.

Query parameters

start_date — required. YYYY-MM-DD
end_date — required. YYYY-MM-DD

Response 200

{
  "tenant_id": "uuid-v4",
  "plan": "enterprise_gpai",
  "start_date": "2026-04-01",
  "end_date": "2026-04-30",
  "total_events": 1247,
  "events": [ /* full event objects */ ],
  "export_note": "Input text stored as SHA-256 hash only — plaintext never persisted."
}

POST /v1/assessment/pre-deployment

Assess an AI system configuration against EU AI Act requirements before deployment. Returns a risk tier, compliance score, and specific gaps to address.

Request body

{
  "system_prompt": "You are a financial advisor assistant...",
  "model_config": {
    "provider": "openai",
    "model_id": "gpt-4o",
    "temperature": 0.7
  },
  "agent_pipeline": {
    "tools": ["web_search", "code_executor"],
    "memory": true,
    "autonomy_level": "high",
    "human_oversight": false
  },
  "jurisdiction": "EU"
}

Response 200

{
  "compliance_score": 0.72,
  "risk_tier": "high",
  "violations": [
    {
      "rule_id": "rego-art6-001",
      "article": "Article 6",
      "description": "High-risk AI system requires conformity assessment",
      "required_action": "Complete conformity assessment before deployment"
    }
  ],
  "required_disclosures": [
    "AI system must identify itself as AI to end users"
  ],
  "eu_ai_act_category": "high_risk",
  "estimated_deadline": "2026-08-02"
}

POST /v1/assessment/gpai-training Enterprise

Article 53 GPAI training-data compliance assessment. Evaluates a model's training configuration against GPAI transparency and copyright requirements.

Enterprise plan required

This endpoint returns a 402 on free or developer plans. Contact support@complyedge.io to enable it on your account.

Request body

{
  "model_name": "my-foundation-model",
  "provider": "internal",
  "version": "1.0",
  "training_data_sources": ["web_crawl", "licensed_books"],
  "open_source": false,
  "systemic_risk": true,
  "jurisdictions": ["EU"]
}

model_name — required.
provider — required.
All other fields optional.

Response 200

{
  "art53_compliance_status": "non-compliant",
  "applicable_obligations": ["53(1)(a)", "53(1)(b)", "53(1)(c)", "53(1)(d)"],
  "open_source_exemption_applied": false,
  "systemic_risk_strips_exemption": false,
  "training_summary_checklist": [
    {
      "field": "model_identification",
      "present": true,
      "value": "my-foundation-model v1.0 by internal",
      "gap": null,
      "required_for": ["53(1)(a)", "53(1)(d)"]
    },
    {
      "field": "data_sources",
      "present": true,
      "value": "2 source(s)",
      "gap": null,
      "required_for": ["53(1)(d)"]
    },
    {
      "field": "copyright_compliance",
      "present": false,
      "value": null,
      "gap": "Document the copyright compliance policy: how Article 4(3) opt-outs are detected and honoured.",
      "required_for": ["53(1)(d)"]
    }
  ],
  "gaps_count": 3,
  "estimated_documentation_effort_hours": 10,
  "penalty_exposure": "Up to EUR 15,000,000 or 3% of total worldwide annual turnover, whichever is higher (EU AI Act Article 99).",
  "ai_office_template_status": "pending — AI Office template not yet submitted",
  "rule_id": "EU_AI_ACT_ART53_GPAI_TRAINING_SUMMARY_001",
  "citation": "EU AI Act Article 53(1)(d), Regulation (EU) 2024/1689"
}

Errors

402 — enterprise plan required
422 — missing model_name or provider

POST /v1/sensitivity/detect

Proactive sensitivity detection for user input — analyzes text before it reaches the model. Detects PII, regulated data, and compliance-sensitive patterns, and returns an intervention action with guidance. This is the endpoint called by the TypeScript SDK's ce.check() method.

Request body

{
  "input_text": "My SSN is 123-45-6789 and I need a loan",
  "agent_id": "loan-assistant-v2",
  "context": {
    "detected_age": null,
    "interaction_type": "chat",
    "platform_type": "financial",
    "user_jurisdiction": "EU",
    "user_role": "customer"
  },
  "conversation_history": [
    { "role": "user", "content": "I need help with my application" }
  ]
}

input_text — required. Max 10,000 characters.
agent_id — optional. Defaults to null.
context — optional. Platform and user context for richer analysis.
conversation_history — optional. Prior turns for progressive risk scoring.

Response 200

{
  "event_id": "uuid-v4",
  "detections": [
    {
      "data_type": "government_id",
      "confidence": 0.98,
      "regulation": "GDPR",
      "excerpt": "123-45-6789",
      "risk_level": "critical"
    }
  ],
  "overall_risk_score": 0.91,
  "applicable_regulations": ["GDPR", "EU AI Act"],
  "progressive_risk_score": 0.94,
  "detection_method": "opa",
  "intervention": {
    "action": "BLOCK",
    "message": "This input contains sensitive personal data that cannot be processed.",
    "alternatives": [
      {
        "message": "Please describe your situation without including personal identifiers.",
        "explanation": "Removing the government ID protects your privacy and keeps the interaction compliant."
      }
    ],
    "allow_override": false,
    "compliance_requirements": ["GDPR Art. 9 — sensitive data prohibition"]
  },
  "processing_time_ms": 142
}

intervention.action — one of: ALLOW, WARN, WARN_AND_BLOCK, BLOCK, REQUIRE_PARENTAL_CONSENT, REDIRECT_SECURE_CHANNEL, PROGRESSIVE_WARNING.
intervention — may be null when action is ALLOW.

Errors

401 — invalid or missing API key
429 — rate limit exceeded (shared daily counter with /v1/check)
422 — invalid request body

Authentication

Account

Audit

Assessment

Sensitivity