API Reference

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"
}

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-1c-001",
    "rule_description": "Regulation (EU) 2024/1689, Article 5(1)(c): Prohibits AI systems that evaluate or classify natural persons based on their social behaviour or personal characteristics, with the social score leading to detrimental or unfavourable treatment.",
    "severity": "critical",
    "reason": "Remove any social scoring, citizen ranking, or behaviour-based classification that leads to detrimental treatment.",
    "confidence": 1.0,
    "text_excerpt": "Score users based on their social behavior"
  }],
  "latency_ms": 91,
  "bundle_version": "opa-rego-v1",
  "evaluated_rules": ["rego-art5-1c-001", "rego-art5-1a-001", "rego-art5-1b-001"],
  "engine_path": "opa",
  "opa_latency_ms": 79.2,
  "audit_logged": true
}

• rule_description — the verbatim legal citation: regulation, article, and paragraph (e.g. "Regulation (EU) 2024/1689, Article 5(1)(c): …"). Audit-grade reasoning, not a short label — this is what you show a regulator.
• confidence — 1.0 for deterministic OPA decisions; only < 1.0 on the opt-in Layer 2 LLM path.
• engine_path — evaluation engine used: opa, llm, hybrid, or fallback_block.
• opa_latency_ms — server-side deterministic evaluation time. latency_ms is the total including audit write.
• 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"
}

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"]
}

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

Due-diligence exhibit: public trust snapshot plus full per-tenant stats (engine paths, violations, latency). API key required.

Response 200 (excerpt)

{
  "tenant_id": "uuid-v4",
  "plan": "enterprise_gpai",
  "time_window_hours": 24,
  "trust": {
    "enforcement_active": true,
    "checks_24h": 42,
    "articles_enforced": ["Article 5", "Article 50"],
    "last_decision_at": "2026-04-17T12:00:00Z",
    "display_name": "Acme Corp"
  },
  "calls_total": 42,
  "violations_prevented": 3,
  "violation_rate": 7.14,
  "block_rate": 7.14,
  "engine_path_counts": { "opa": 35, "llm": 7 },
  "top_violations": [{ "rule_id": "rego-art5-1c-001", "count": 2 }],
  "latency_avg_ms": 24,
  "latency_p95_ms": 51
}

Public-safe enforcement stats for trust pages and badges. No API key. Tenant must opt in via PATCH /v1/tenant/trust. Returns 404 if slug is unknown or not enabled.

Response 200

{
  "enforcement_active": true,
  "checks_24h": 42,
  "articles_enforced": ["Article 5", "Article 50"],
  "last_decision_at": "2026-04-17T12:00:00Z",
  "display_name": "Acme Corp"
}

No tenant_id, email, or plaintext. Cached max-age=300. Rate-limited per IP. Contract: docs/architecture/trust-surface-contract.md.

Embeddable ComplyEdge Enforcement Seal — coral hex glyph (logo mark) + live status dot + Runtime Enforced copy. Same trust snapshot as JSON.

• Green — checks in last 24h (#10b981)
• Amber — enforcement in 7d, quiet last 24h (#f59e0b)
• Red — no audit activity in 7d (#ef4444)

Returns 404 if slug unknown or trust not enabled. Cache-Control: public, max-age=300. Embed guide →

Read trust configuration and embed URLs for the authenticated tenant.

{
  "public_slug": "acme",
  "trust_public_enabled": true,
  "display_name": "Acme Corp",
  "trust_json_url": "https://api.complyedge.io/v1/public/trust/acme",
  "badge_svg_url": "https://api.complyedge.io/v1/public/badge/acme.svg"
}

Enable public trust surface for your tenant. Slug must be unique (3–64 chars, lowercase alphanumeric + hyphens).

{
  "public_slug": "acme",
  "trust_public_enabled": true,
  "display_name": "Acme Corp"
}

List API keys for the authenticated tenant (JWT session). Returns the full key value so the dashboard can Show / Copy — display masking is client-side.

Response 200

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

This endpoint returns the full key value (so the dashboard can offer Show/Copy) — treat the response as sensitive and never log or expose it client-side beyond your own dashboard.

Errors

• 401 — invalid or expired session token
• 500 — internal error retrieving 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."
}

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

Daily usage metrics for your tenant within a date range.

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 }
  ]
}

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-1c-001",
        "rule_description": "Regulation (EU) 2024/1689, Article 5(1)(c): Prohibits AI systems that evaluate or classify natural persons based on their social behaviour or personal characteristics, with the social score leading to detrimental or unfavourable treatment.",
        "severity": "critical",
        "reason": "Remove any social scoring, citizen ranking, or behaviour-based classification that leads to detrimental treatment.",
        "confidence": 1.0
      }],
      "latency_ms": 91,
      "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

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 }
}

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
}

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

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": [
    {
      "event_id": "evt_…",
      "timestamp": "2026-04-17T12:00:00Z",
      "text_hash": "sha256…",
      "allowed": true,
      "chain_link": "64-char-hex-sha256"
    }
  ],
  "chain_head": "64-char-hex-sha256",
  "chain_algorithm": "sha256-v1",
  "export_note": "Input text stored as SHA-256 hash only — plaintext never persisted."
}

Tamper verification (sha256-v1)

Each event includes a chain_link. Links are computed at export time in chronological order:

1. Sort events by timestamp, then event_id.
2. Genesis hash is empty string; for each event: chain_link = SHA-256(prev_link + canonical_json(event)) (sorted keys, no whitespace).
3. chain_head is the final link. Recompute and compare — any altered, removed, or reordered event breaks the chain.

Use verify_audit_export_chain() in services/api/audit_export.py or reimplement the same steps in your compliance toolchain.

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"
}

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

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": "Validated v1 — aligned to Commission Template C(2025) 5235 (24 Jul 2025)",
  "ai_office_template_source": "Commission C(2025) 5235 final (24 Jul 2025)",
  "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

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