EVE Core › Docs › CoreGuard API Reference
API Reference

CoreGuard API Reference

The CoreGuard API is a deterministic AI governance decision engine that evaluates proposed actions against versioned policy packs and returns ALLOWED, BLOCKED, or MODIFIED dispositions with a cryptographically signed audit certificate. This reference documents all endpoints, request and response schemas, decision status values, error codes, and rate limits. For background on why deterministic governance matters in regulated industries, see Deterministic AI Governance: Why Probabilistic Guardrails Fail.

Contents

  1. Overview and Authentication
  2. POST /decisions/evaluate
  3. GET /decisions/health
  4. Decision Status Values
  5. Risk Levels
  6. Policy Sets
  7. Python SDK Quickstart
  8. Error Codes
  9. Rate Limits

1. Overview and Authentication

The CoreGuard API is accessible at the following base URL. All requests and responses use JSON. TLS 1.2+ is required on all connections; plain HTTP connections are rejected.

https://api.eveaicore.com/v1

Authentication

Authenticate by including your API key in the Authorization header as a Bearer token. API keys are issued per organization and can be scoped to specific policy sets.

HTTP Header
Authorization: Bearer sk_eve_your_api_key_here
Content-Type: application/json

API keys are prefixed with sk_eve_ for production keys and sk_eve_test_ for test keys. Test keys evaluate against the same policy logic but do not generate billable decisions and cannot be used to produce certificates submitted for regulatory audit.

Key security: API keys must be stored server-side and must never be embedded in client-side code, mobile applications, or public repositories. CoreGuard keys carry the ability to evaluate and block decisions — treat them with the same care as database credentials.

2. POST /decisions/evaluate

The primary endpoint. Evaluates a proposed action against a specified policy set and returns a governance decision with risk assessment, any policy violations, and a signed audit certificate.

POST /v1/decisions/evaluate Evaluate action against policy pack

Request Schema

Field Type Required Description
policy_set string required Policy pack identifier. See Policy Sets for available values.
user object required Identity of the agent initiating the action. Must include id. role and organization are used by role-sensitive policy rules.
action object required The proposed action to evaluate. Must include type. Additional fields are policy-specific — see policy pack documentation for the action schema your policy expects.
context object optional Request-level metadata. request_id is echoed in the audit record and used for idempotency. audit_session groups related decisions in the audit log.
Example Request — Lending Policy
{
  "policy_set": "lending_v1",
  "user": {
    "id": "user_123",
    "role": "loan_officer",
    "organization": "regional_bank"
  },
  "action": {
    "type": "loan_decision",
    "amount": 50000,
    "applicant_id": "app_456",
    "context": {
      "credit_score": 720,
      "income": 85000,
      "ltv_ratio": 0.78
    }
  },
  "context": {
    "request_id": "req_789",
    "timestamp": "2026-05-05T10:30:00Z",
    "audit_session": "ses_101"
  }
}

Response Schema

Field Type Description
decision object Top-level governance verdict. Contains status (ALLOWED / BLOCKED / MODIFIED), confidence (0–1), decision_id, and policy_version.
risk_assessment object Computed risk characterization. risk_level is LOW / MEDIUM / HIGH. risk_score is 0–1. risk_factors and mitigations_applied are arrays of strings describing what was detected and what was done.
policy_violations array Array of policy violation objects. Each includes rule_id, rule_description, severity, and field indicating which request field triggered the violation. Empty array when status is ALLOWED.
modifications object | null Present only when status is MODIFIED. Describes required changes before the action may proceed. null for ALLOWED and BLOCKED decisions.
audit_record object Cryptographically signed audit certificate. Contains record_id, timestamp, request_hash, decision_hash, certificate (JWT-format), hmac_signature, policy_set, and evaluator_version.
latency_ms number Server-side evaluation latency in milliseconds, excluding network transit. Includes policy evaluation and certificate signing; excludes request parsing and response serialization.
Example Response — ALLOWED Decision
{
  "decision": {
    "status": "ALLOWED",
    "confidence": 0.97,
    "decision_id": "dec_abc123",
    "policy_version": "lending_v1@2026-04-01"
  },
  "risk_assessment": {
    "risk_level": "LOW",
    "risk_score": 0.12,
    "risk_factors": [],
    "mitigations_applied": []
  },
  "policy_violations": [],
  "modifications": null,
  "audit_record": {
    "record_id": "aud_def456",
    "timestamp": "2026-05-05T10:30:00.000Z",
    "request_hash": "sha256:abc...",
    "decision_hash": "sha256:def...",
    "certificate": "eyJ...",
    "hmac_signature": "hmac-sha256:xyz...",
    "policy_set": "lending_v1",
    "evaluator_version": "1.3.0"
  },
  "latency_ms": 0.4
}
Example Response — BLOCKED Decision (ECOA Violation)
{
  "decision": {
    "status": "BLOCKED",
    "confidence": 1.0,
    "decision_id": "dec_blk789",
    "policy_version": "lending_v1@2026-04-01"
  },
  "risk_assessment": {
    "risk_level": "HIGH",
    "risk_score": 0.91,
    "risk_factors": ["protected_class_inference", "ecoa_proxy_variable"],
    "mitigations_applied": []
  },
  "policy_violations": [
    {
      "rule_id": "lending.ecoa.015",
      "rule_description": "Action references zip_code as primary factor — known proxy for race under Reg B",
      "severity": "CRITICAL",
      "field": "action.context.zip_code"
    }
  ],
  "modifications": null,
  "audit_record": { /* ... signed record ... */ },
  "latency_ms": 0.3
}

Audit record retention: CoreGuard retains all audit records for 7 years by default, accessible via the audit retrieval API. Records are stored with hash-chain integrity — any tampering is cryptographically detectable. You do not need to store the audit records yourself to satisfy regulatory requirements, though you may optionally retrieve and archive them.

3. GET /decisions/health

Returns the operational status of the CoreGuard evaluation engine. Use this endpoint for load balancer health checks and monitoring integrations. This endpoint does not require authentication and does not generate audit records.

GET /v1/decisions/health Engine health check — no auth required
Example Response — Healthy
{
  "status": "healthy",
  "evaluator_version": "1.3.0",
  "policy_sets_loaded": ["lending_v1", "healthcare_v1", "enterprise_v1"],
  "uptime_seconds": 2847392,
  "timestamp": "2026-05-05T10:30:00Z"
}

Returns HTTP 200 when healthy. Returns HTTP 503 with a "status": "degraded" body if the evaluation engine is not fully operational. A degraded engine will still accept and evaluate requests, but certificate signing may be operating in fallback mode.

4. Decision Status Values

Every evaluation response includes a decision.status field with one of three values. The status is deterministic: the same request against the same policy version always produces the same status.

Status Meaning When It Occurs Caller Action
ALLOWED Action passes all policy rules No rules triggered; risk score below all thresholds; all mandatory checks passed Proceed. Archive the audit_record for regulatory retention.
BLOCKED Action violates one or more policy rules A hard-block rule triggered; risk score above policy ceiling; prohibited action type detected Do not proceed. Present applicable adverse action notice if required. Log policy_violations for your compliance record.
MODIFIED Action permitted with required changes Action is within policy scope but requires specific additions or adjustments — e.g., a mandatory disclosure, an amount cap, or a supervisory review step Apply all changes specified in the modifications object, then proceed. The audit_record documents which modifications were required.

On BLOCKED vs. MODIFIED: The distinction is policy-defined, not heuristic. A rule that identifies a hard prohibition — using a protected-class proxy variable, exceeding a statutory limit, proposing a clinically contraindicated action — produces BLOCKED. A rule that identifies a gap requiring remediation — missing a disclosure, an amount needing adjustment — produces MODIFIED. Policy authors have explicit control over which outcome each rule triggers.

5. Risk Levels

The risk_assessment.risk_level field is a categorical summary of the computed risk_score. Risk is assessed independently of the governance verdict — an ALLOWED decision can have a MEDIUM risk level if it passes policy rules but exhibits characteristics that warrant elevated monitoring.

Level Score Range Meaning Typical Disposition
LOW 0.00 – 0.33 Action is well within policy parameters. No risk factors detected. ALLOWED. Standard audit retention.
MEDIUM 0.34 – 0.66 One or more risk factors detected but below blocking threshold. May warrant supervisory attention or enhanced monitoring. ALLOWED or MODIFIED depending on rule configuration. Flagged for enhanced audit retention in most policy packs.
HIGH 0.67 – 1.00 Multiple risk factors or a single critical risk factor detected. Policy hard-block rules typically trigger in this range. BLOCKED or MODIFIED with mandatory escalation. HMAC certificate automatically marked for regulatory priority retention.

6. Policy Sets

A policy set is a versioned collection of rules compiled from regulatory requirements and organizational policies. Policy sets are immutable once published — a version number and a date stamp uniquely identify the exact rules that were in effect for any historical evaluation. This immutability is what enables audit replay: you can resubmit any historical request against the exact policy version that was active at the time and receive an identical verdict.

Policy Set ID Version Coverage Availability
lending_v1 1.2.0 ECOA / Reg B disparate impact rules, adverse action notice requirements, Fair Housing Act proxy variable detection, HMDA reportable action identification, LTV and DTI threshold enforcement All tiers
healthcare_v1 1.0.0 HIPAA minimum necessary standard, clinical decision support safety rules, off-label recommendation detection, contraindication blocking, documentation completeness enforcement Pro and Enterprise
enterprise_v1 2.1.0 General enterprise AI safety baseline: PII exposure prevention, output toxicity blocking, competitive intelligence disclosure, legal privilege protection, hallucination risk flags for regulated statements All tiers
custom Varies Tenant-authored policy rules deployed to your isolated namespace. Custom rules may extend any base policy set. Custom policy sets undergo EVE Core review before activation to verify they do not weaken base-pack protections. Enterprise only

To retrieve the full rule catalog for a policy set, call GET /v1/policies/{policy_set}/rules. Each rule entry includes the rule ID, description, the regulatory citation it implements, the fields it inspects, and the triggering conditions.

7. Python SDK Quickstart

The eve-coreguard package provides a typed Python client with automatic retry, certificate verification, and async support. Install with pip:

Installation
pip install eve-coreguard
Basic Evaluation
# Synchronous usage
from eve_coreguard import CoreGuardClient

client = CoreGuardClient(api_key="sk_eve_your_api_key_here")

result = client.evaluate(
    policy_set="lending_v1",
    user={"id": "user_123", "role": "loan_officer"},
    action={"type": "loan_decision", "amount": 50000},
    context={"credit_score": 720, "income": 85000}
)

print(result.decision.status)          # ALLOWED / BLOCKED / MODIFIED
print(result.risk_assessment.risk_level)  # LOW / MEDIUM / HIGH
print(result.audit_record.certificate) # HMAC-signed audit certificate
print(result.latency_ms)               # Sub-millisecond evaluation latency

# Check for violations
if result.policy_violations:
    for v in result.policy_violations:
        print(f"Rule {v.rule_id}: {v.rule_description}")

# Verify the audit certificate independently
is_valid = client.verify_certificate(result.audit_record.certificate)
print(f"Certificate valid: {is_valid}")
Async Usage
import asyncio
from eve_coreguard import AsyncCoreGuardClient

async def evaluate_loan():
    async with AsyncCoreGuardClient(api_key="sk_eve_...") as client:
        result = await client.evaluate(
            policy_set="lending_v1",
            user={"id": "user_123"},
            action={"type": "loan_decision", "amount": 75000}
        )
        return result

asyncio.run(evaluate_loan())
Handling MODIFIED Decisions
result = client.evaluate(
    policy_set="lending_v1",
    user={"id": "user_123"},
    action={"type": "loan_decision", "amount": 250000}
)

if result.decision.status == "MODIFIED":
    mods = result.modifications
    print(f"Required modifications: {mods.required_changes}")
    # Apply changes and re-evaluate, or apply changes to the output
    # directly and attach the audit certificate to the record

8. Error Codes

All API errors return a JSON body with an error object containing a code string, a human-readable message, and where applicable a field indicating which request parameter caused the error.

HTTP Status Error Code Cause and Resolution
400 invalid_request The request body is malformed or missing required fields. Check the field property in the error response for the specific parameter that is invalid or absent.
401 unauthenticated The Authorization header is absent or does not contain a valid Bearer token. Verify your API key is correctly formatted and has not been revoked.
403 forbidden Your API key is valid but is not authorized to access the requested policy set or endpoint. API keys can be scoped to specific policy sets — check your key's scope in the developer dashboard.
404 policy_not_found The specified policy_set value does not exist or is not available on your account tier. Verify the policy set identifier against the Policy Sets table.
422 validation_error The request structure is valid JSON but fails semantic validation — for example, a required field within the action object that the specified policy set expects. The details array lists each specific validation failure.
429 rate_limit_exceeded Your organization has exceeded its per-minute request limit. The response includes a Retry-After header indicating how many seconds to wait before retrying. See Rate Limits.
500 internal_error An unexpected server-side error occurred. The response includes a request_id you can provide to support. CoreGuard is designed with fail-closed semantics — in the event of an internal error on a BLOCKED or MODIFIED path, the error is surfaced rather than defaulting to ALLOWED.

Fail-closed behavior: If CoreGuard encounters an internal error during policy evaluation, it returns a 500 rather than silently passing the request through as ALLOWED. This is intentional. A governance system that fails open under load or error conditions is not a governance system — it is a performance-mode bypass. Design your integration to handle 500 responses by halting the action and escalating for human review.

9. Rate Limits

Rate limits are applied per API key at the per-minute level. Limits are enforced with a sliding window. Burst capacity is available on Pro and Enterprise tiers: you can exceed the per-minute rate for up to 10 seconds before the limit is enforced.

Tier Requests / Minute Concurrent Connections Audit Retention Custom Policy Sets
Free 100 5 90 days No
Pro 1,000 25 7 years No
Enterprise Custom (SLA-backed) Custom 7 years + archival export Yes

Rate limit headers are included in every response:

Rate Limit Response Headers
X-RateLimit-Limit:      1000
X-RateLimit-Remaining:  987
X-RateLimit-Reset:      1746444660  # Unix timestamp of next window reset

Frequently Asked Questions

What authentication does the CoreGuard API use?

The CoreGuard API uses Bearer token authentication. Include your API key in the Authorization header as Authorization: Bearer {your_api_key}. API keys are issued per organization and can be scoped to specific policy sets. Contact [email protected] to request an API key for your organization.

What is the latency of the POST /decisions/evaluate endpoint?

CoreGuard's evaluation engine is implemented as a pure deterministic function with no model inference in the critical path. Median latency for a standard policy evaluation is under 1 millisecond. The audit certificate generation, including HMAC-SHA256 signing, adds negligible overhead. P99 latency in production is under 5 milliseconds — orders of magnitude faster than LLM-based safety filters, which typically add 200–2,000ms to each request.

How do I verify a CoreGuard audit certificate?

Each audit record includes an hmac_signature field containing an HMAC-SHA256 signature over the canonical form of the decision record. The Python SDK provides a verify_certificate() helper that handles canonicalization and signature verification automatically. You can also verify certificates offline using only the CoreGuard public verification key — no API call required. This enables independent third-party audit verification without relying on CoreGuard infrastructure.

What happens when CoreGuard returns MODIFIED status?

A MODIFIED decision means the requested action is conditionally permitted, but the policy engine has identified required changes that must be applied before the action can proceed. The response includes a modifications object describing the required changes — for example, requiring the addition of an adverse action notice, capping a loan amount to a policy-compliant maximum, or mandating a supervisory review step. The caller is responsible for applying the modifications before presenting the output to the end user or downstream system.

Try CoreGuard Now

Test the API in our interactive demo — no API key required. See ALLOWED, BLOCKED, and MODIFIED decisions with live audit certificates in under 30 seconds.

Try the Demo CoreGuard Overview