Getting Started

Quickstart Guide

The Auditvec Risk API sits at the edge. It normalizes inputs, runs your model via the specified profile, and applies governance policies before returning a decision.

Base URL https://risk.auditvec.com

Request Schema

Understanding the input fields and comments.

{
  "include_precedent": true,         
  "panel_size": 11,                  
  "data": {
    "duration": 24,                  // model feature – months
    "duration_months": 36,           // policy field – months (min 36 to PASS in demo)
    "credit_amount": 2500,
    "age": 35,
    "installment_rate": 2,
    "residence_since": 3,
    "existing_credits_count": 1,
    "dependents": 1,
    "status": "A12",
    "credit_history": "A32",
    "purpose": "A43",
    "savings": "A62",
    "employment_length": "A74",
    "personal_status_sex": "A92",
    "other_debtors": "A101",
    "property": "A122",
    "other_plans": "A143",
    "housing": "A152",
    "job": "A172",
    "telephone": "A191",
    "foreign_worker": "A201"
  }
}

Note on Duration Fields The Worker normalizes duration and duration_months so either can be provided. If both are present they must match. The Demo policy requires duration_months >= 36. If not met, the router returns REVIEW regardless of score.

Make a Request

curl -s -X POST "https://risk.auditvec.com/classify?explain=plain" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_DEMO_KEY" \
  -H "X-Config-Id: homecredit" \
  -d '{
    "include_precedent": true,
    "panel_size": 11,
    "data": {
      "duration": 24,
      "duration_months": 36,
      "credit_amount": 2500,
      "age": 35,
      "installment_rate": 2,
      "residence_since": 3,
      "existing_credits_count": 1,
      "dependents": 1,
      "status": "A12",
      "credit_history": "A32",
      "purpose": "A43",
      "savings": "A62",
      "employment_length": "A74",
      "personal_status_sex": "A92",
      "other_debtors": "A101",
      "property": "A122",
      "other_plans": "A143",
      "housing": "A152",
      "job": "A172",
      "telephone": "A191",
      "foreign_worker": "A201"
    }
  }'

$API = "https://risk.auditvec.com"
$KEY = "YOUR_DEMO_KEY"
$body = @{
  include_precedent = $true
  panel_size = 11
  data = @{
    duration = 24
    duration_months = 36
    credit_amount = 2500
    age = 35
    installment_rate = 2
    residence_since = 3
    existing_credits_count = 1
    dependents = 1
    status = "A12"
    credit_history = "A32"
    purpose = "A43"
    savings = "A62"
    employment_length = "A74"
    personal_status_sex = "A92"
    other_debtors = "A101"
    property = "A122"
    other_plans = "A143"
    housing = "A152"
    job = "A172"
    telephone = "A191"
    foreign_worker = "A201"
  }
} | ConvertTo-Json -Compress

$r = Invoke-RestMethod -Method Post "$API/classify?explain=plain" `
  -Headers @{ "Content-Type"="application/json"; "X-API-Key"=$KEY; "X-Config-Id"="homecredit" } `
  -Body $body

$r.router
$r.policy
$r.plain_summary

Typical Response

JSON

{
  "p_raw_gbdt": 0.23,
  "p_bad_calibrated": 0.14,
  "coverage_pct": 100.0,
  "router": {
    "gate_policy": "PASS|FAIL",
    "gate_cov": "OK|LOW",
    "gate_gray": "CLEAR|GRAY",
    "final_decision": "APPROVE|REVIEW|DENY"
  },
  "precedent_panel": {
    "label": "good|bad",
    "confidence": 0.92,
    "coverage": 1.0
  },
  "plain_summary": {
    "decision": "APPROVE|REVIEW|DENY",
    "reason_lines": ["...", "..."]
  },
  "policy": {
    "status": "PASS|FAIL",
    "violations": ["min_duration_not_met"],
    "flags": []
  },
  "audit_id": "abcdef123456"
}

Policy Snapshot

Inspect the active policy logic and thresholds.

GET /policy

{
  "profile": "homecredit",
  "policy": {
    "min_duration_months": 36,
    "final_mode": "triage",
    "gray_band": 0,
    "coverage_review_pct": 0,
    "bad_thresh_source": "cal"
  },
  "source": "edge"
}

Note: Demo plan may be rate limited. Production plans define daily/per-minute quotas.

Endpoints & Authentication

Authentication

Authenticate using the X-API-Key header.

Content-Type: application/json
X-API-Key: <your key> (Required)
X-Config-Id: homecredit (Optional, defaults to homecredit)

Available Endpoints

POST

/classify?explain=plain

Main scoring endpoint. Returns decision, explanation, and audit ID.

GET

/policy

Returns the currently active policy snapshot and thresholds.

GET

/version

Returns origin service version and cryptographic serving signatures.

AI Policy & Scope

This document outlines the governance controls, roles, and risk management strategies employed by the Auditvec Risk API.

Roles & Responsibilities

Role	Assignee
Accountable	Head of Product & Engineering
Responsible	API Maintainers & DevOps
Reviewer	Independent Validator / Advisor

Controls

Access: API Keys in KV
Transport: HTTPS Only
Policy Gates: Min Duration, Gray Band
Change Control: Snapshots & Lint Gates

Risk Management

Model Risk: Calibration & Coverage monitored.
Data Risk: Dataset limits documented in cards.
Privacy: No PII stored. Redaction-safe reasons.

Model Card: HomeCredit

Active Profile

Overview

Owner: API Maintainers
Intended Use: Credit-risk triage for demo/pilot.
Vector Length: 68 with masked subspaces.

Routing Logic

Gray Band: 0 (Demo Mode)
Policy Gate: Duration ≥ 36 months
Coverage Gate: Requires coverage where enabled

Limitations

This model is trained on a benchmark dataset for demonstration purposes only. It is not intended for production underwriting. Results may be sensitive to dataset bias inherent in the source data.

Model Card: German Credit

Historical benchmark dataset from the 1990s.

Same structural routing parameters as HomeCredit apply. Note that categorical codes reflect 1990s German currency and credit standards.

Model Card: GMSC

Give Me Some Credit (Kaggle) benchmark sample.

Optimized for probability calibration over raw ranking. Coverage gate is strict.

Model Card: Fraud Sample

High-imbalance fraud detection sample.

Note: Label prevalence is significantly lower than credit risk models. Thresholds are adjusted accordingly.

Monthly Monitoring Checklist

Routine checks to confirm calibration, drift, fairness, and availability.

1

Availability & Version

Check GET /version uptime. Confirm serving signature for each enabled profile.

2

Calibration

Compute ECE on validation split. Investigate if ECE > 0.06.

3

Drift Analysis

Compute PSI for key inputs. Investigate if PSI > 0.2.

4

Fairness Slices

Compare calibrated risk & decision rates across selected segments. Record in monthly report.

Sign off: Owner signs and stores report at ops/monitoring/reports/YYYY-MM/