API Reference

Complete REST API documentation for AuditCore's Auditable Decision Engine.
Every endpoint is designed for regulated industries requiring full decision traceability.

🔗

Hash-Chained Audit

Every decision is SHA-256 hashed and linked to the previous record. Tamper-evident by design.

🔍

Full Explainability

Factor impact, confidence maps, plain-language narratives, and counterfactual analysis.

📋

3 Regulated Domains

Healthcare, insurance, and finance — each with domain-specific rules and evidence sources.

📄

PDF Audit Reports

Generate compliance-ready PDF reports with executive summaries and cryptographic proof.

Base URL

Production

https://www.auditcoreai.com

Local Dev

http://localhost:8000

Authentication

🔓 No authentication required for the public demo API

The current demo API is open for evaluation. Production deployments support API key authentication via the Authorization: Bearer <key> header.

💡 Contact hello@auditcoreai.com for production API keys and enterprise onboarding.

Quick Start

Run a fully auditable decision in one API call:

cURL

Python

JavaScript

# Run a loan underwriting decision
curl -X POST https://www.auditcoreai.com/api/decide \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "finance",
    "query": "Evaluate mortgage application",
    "context": {
      "credit_score": 720,
      "dti_ratio": 0.35,
      "ltv_ratio": 0.80,
      "loan_type": "conventional",
      "employment_years": 5,
      "loan_amount": 250000
    }
  }'

import requests

response = requests.post("https://www.auditcoreai.com/api/decide", json={
    "domain": "finance",
    "query": "Evaluate mortgage application",
    "context": {
        "credit_score": 720,
        "dti_ratio": 0.35,
        "ltv_ratio": 0.80,
        "loan_type": "conventional",
        "employment_years": 5,
        "loan_amount": 250000
    }
})

result = response.json()
print(result["record"]["outcome"])  # "approved"
print(result["record"]["confidence"]["overall_confidence"])  # 0.91

const response = await fetch("https://www.auditcoreai.com/api/decide", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    domain: "finance",
    query: "Evaluate mortgage application",
    context: {
      credit_score: 720,
      dti_ratio: 0.35,
      ltv_ratio: 0.80,
      loan_type: "conventional",
      employment_years: 5,
      loan_amount: 250000
    }
  })
});

const result = await response.json();
console.log(result.record.outcome);  // "approved"

Core Endpoints

GET /api/domains List available decision domains ›

Returns all supported decision domains with metadata including rule counts, evidence sources, and UI configuration.

200 Response

[
  {
    "id": "finance",
    "title": "Financial Underwriting",
    "description": "Loan and mortgage decision analysis",
    "icon": "🏦",
    "color": "#3b82f6",
    "rules_count": 6,
    "evidence_sources": 4
  },
  ...
]

GET /api/scenarios/{domain} Get pre-built test scenarios ›

Returns pre-configured test scenarios for a specific domain. Useful for demos and integration testing.

Parameter	Type	Description
domain	string required	Domain ID: health, insurance, or finance

200 Response

[
  {
    "name": "Strong Borrower",
    "description": "Excellent credit, low risk",
    "query": "Evaluate mortgage application",
    "context": { ... }
  },
  ...
]

POST /api/decide Run an auditable decision ›

Runs a full 7-stage decision pipeline: Risk Classification → Evidence Gathering → Rule Checking → Structured Reasoning → Confidence Scoring → Decision Gate → Audit Chain. Returns the complete decision record with full explainability.

📌 Every call appends a hash-chained record to the audit trail. Records are immutable and tamper-evident.

Request Body

Field	Type	Description
domain	string required	health, insurance, or finance
query	string optional	Natural language description of the decision request
context	object required	Domain-specific input data (see domain schemas below)

Finance Context Schema

Field	Type	Description
credit_score	int	Credit score (300–850)
dti_ratio	float	Debt-to-income ratio (0–1)
ltv_ratio	float	Loan-to-value ratio (0–1+)
loan_type	string	conventional, fha, va, jumbo
employment_years	float	Years of employment
loan_amount	int	Requested loan amount in USD

Health Context Schema

Field	Type	Description
patient_age	int	Patient age in years
conditions	string[]	Active medical conditions
current_medications	string[]	Current medications
proposed_treatment	string	Treatment being evaluated
allergies	string[]	Known allergies
informed_consent	bool	Whether patient consent has been obtained

Insurance Context Schema

Field	Type	Description
policy_status	string	active, lapsed, cancelled, expired
claim_type	string	collision, comprehensive, liability, etc.
covered_types	string[]	Types covered by the policy
claim_amount	int	Claim amount in USD
max_per_claim	int	Maximum payout per claim
deductible	int	Policy deductible in USD

200 Response

{
  "record": {
    "record_id": "a1b2c3d4",
    "domain": "finance",
    "outcome": "approved",
    "risk_tier": "low",
    "confidence": {
      "overall_confidence": 0.91,
      "evidence_strength": 0.88,
      "reasoning_clarity": 0.85,
      "rule_compliance": 1.0
    },
    "rule_checks": [ ... ],
    "evidence": [ ... ],
    "reasoning_steps": [ ... ],
    "decision_summary": "Application approved with strong ...",
    "record_hash": "sha256:8f14e45f...",
    "previous_record_hash": null,
    "escalated": false
  },
  "explanation": {
    "factors": [ ... ],
    "narrative": "The application was approved because ..."
  },
  "pipeline": {
    "risk_tier": "low",
    "evidence_count": 4,
    "rules": { "total": 6, "passed": 6, "violations": 0 },
    "confidence": 0.91,
    "escalated": false,
    "outcome": "approved"
  },
  "trail_length": 1
}

Tier 3: AI-Autonomous Conversation

The Conversation Engine conducts a guided, multi-turn dialogue to gather all inputs needed for a decision. The AI asks domain-specific questions, validates answers, and proposes a decision — the human approves or sends it back. Every exchange is auditable.

💬 Tier 3 Flow: start(domain) → answer questions → receive proposal → approve → /api/decide with collected context. The rules engine still enforces compliance — the AI cannot skip required checks.

POST /api/conversation/start Start a guided conversation ›

Starts a new AI-driven conversation session for a given domain. Returns a greeting, the first question, and a session ID for subsequent replies.

Request Body

Field	Type	Description
domain	string required	health, insurance, or finance

Response

{
  "session_id": "a1b2c3d4e5f6",
  "domain": "finance",
  "status": "active",
  "exchanges": [
    { "role": "assistant", "content": "I'll help evaluate a loan application..." },
    { "role": "assistant", "content": "Please describe the loan application.",
      "question_meta": { "type": "text", "required": true } }
  ],
  "progress": { "answered": 0, "total": 8, "percent": 0 }
}

POST /api/conversation/reply Reply to a conversation question ›

Sends the user's answer. The engine parses, validates, acknowledges, and returns either the next question or a decision proposal (when all required fields are collected).

Request Body

Field	Type	Description
session_id	string required	Session ID returned from /api/conversation/start
answer	string required	User's free-text answer (parsed automatically based on question type)

Question Types

Type	Parsing	Example Input
text	Raw text	"Evaluate mortgage application"
number	Extracts first number (strips $ and ,)	"$300,000" → 300000
boolean	yes/no/true/false detection	"Yes, confirmed" → true
choice	Fuzzy match against options	"conventional" or "FHA"
list	Multi-match against options	"hypertension, diabetes"

Response (Next Question)

{
  "status": "active",
  "exchanges": [ /* ...all messages so far... */ ],
  "progress": { "answered": 3, "total": 8, "percent": 38 }
}

Response (Proposal)

{
  "status": "proposal",
  "proposal": {
    "summary": "Based on the information gathered...",
    "query": "Evaluate mortgage application",
    "context": { "credit_score": 720, "dti_ratio": 0.35, /* ... */ },
    "fields_collected": 8,
    "conversation_turns": 18
  }
}

📌 After receiving a proposal, call /api/decide with the proposal.query and proposal.context to run the full auditable decision pipeline.

Explainability

POST /api/whatif Counterfactual / What-If analysis ›

Compare two decision outcomes by modifying input parameters. Essential for EU AI Act compliance, ECOA adverse-action explanations, and sensitivity analysis.

Request Body

{
  "domain": "finance",
  "original": {
    "query": "Evaluate loan",
    "context": { "credit_score": 580, ... }
  },
  "modified": {
    "context": { "credit_score": 720, ... }
  }
}

200 Response

Returns original vs. modified decision summaries, input deltas, outcome shift analysis, and a pivotal flag indicating whether the change flipped the decision.

{
  "original": { "outcome": "denied", "confidence": 0.72, ... },
  "modified": { "outcome": "approved", "confidence": 0.91, ... },
  "input_deltas": [
    { "field": "credit_score", "from": 580, "to": 720, "direction": "increased" }
  ],
  "outcome_shift": { "changed": true, "direction": "favorable" },
  "pivotal": true
}

Audit & Compliance

GET /api/audit/trail?domain={domain} Get hash-chained audit trail ›

Returns the complete audit trail for a domain — every decision record with full SHA-256 hash chain linking.

Parameter	Type	Description
domain	string optional	Domain ID. Defaults to health

200 Response

Array of decision records with record_hash and previous_record_hash fields forming a verifiable chain.

GET /api/audit/verify?domain={domain} Verify chain integrity ›

Performs full cryptographic verification of the audit chain. Detects any tampered, modified, or missing records.

200 Response

{
  "valid": true,
  "records_checked": 5,
  "errors": [],
  "summary": "All 5 records verified. Chain integrity confirmed.",
  "records": [
    { "index": 0, "record_id": "a1b2c3d4", "valid": true },
    ...
  ]
}

GET /api/audit/export?domain={domain} Download PDF audit report ›

Generates and downloads a compliance-ready PDF audit report. Includes cover page with executive summary, per-record detail pages with confidence breakdowns, rule results, evidence, and cryptographic chain verification status.

📄 PDF is generated using pure Python (ISO 32000 spec) — no external dependencies like wkhtmltopdf or ReportLab.

200 Response

Returns application/pdf binary with Content-Disposition: attachment.

GET /api/audit/stats?domain={domain} Get audit statistics ›

Returns aggregate statistics about decisions: total count, escalation rate, average confidence, and chain integrity status.

200 Response

{
  "total_decisions": 12,
  "escalation_rate": 0.25,
  "avg_confidence": 0.84,
  "chain_valid": true
}

Integrity Testing

POST /api/audit/tamper Simulate tampering (demo) ›

Deliberately corrupts a record in the audit trail to demonstrate tamper detection. For demo/testing purposes only.

Request Body

{
  "domain": "finance",
  "position": 0  // index of record to tamper
}

POST /api/audit/restore Restore tampered record ›

Restores a previously tampered record and re-verifies the chain integrity.

Request Body

{
  "domain": "finance",
  "position": 0
}

Configuration

GET /api/policy/{domain} Get policy configuration ›

Returns the current rule thresholds and escalation policy for a domain. All thresholds can be adjusted without code changes.

200 Response

{
  "domain": "finance",
  "thresholds": [
    { "id": "min_credit_score", "label": "Min Credit Score", "value": 620, ... }
  ],
  "escalation": {
    "confidence_low": 0.70,
    "escalate_on_violations": true,
    "max_known_unknowns": 3
  }
}

POST /api/policy/{domain} Update policy configuration ›

Update decision thresholds and escalation settings. Changes are applied immediately to the live agent — no restart required.

Request Body

{
  "thresholds": [
    { "id": "min_credit_score", "value": 650 }
  ],
  "escalation": {
    "confidence_low": 0.80,
    "escalate_on_violations": true
  }
}

GET /api/reset?domain={domain} Reset domain session ›

Resets the agent for the specified domain — clears audit trail, restores default policy, and re-initializes the decision pipeline.

Error Handling

All errors return a JSON object with an error field:

400
{
  "error": "Unknown domain: invalid_domain"
}

Status	Meaning
200	Success
400	Bad request — invalid JSON, missing fields, or unknown domain
404	Endpoint not found
500	Internal server error — check request body format

⚡ Rate Limits: The public demo API is rate-limited to 60 requests/minute per IP. Contact us for production-tier limits.