Getting Started

Quickstart Guide

Supported governed endpoints return explicit coverage_pct, routing metadata, policy outcome, decision summary, and audit linkage.

Need assisted onboarding for private deployment? See Offline Profile Onboarding (Optional).

Base URL https://risk.auditvec.com

Request Schema

Public bundled examples and governed HTTP integration examples use the demo credit profile shown below and specify X-Config-Id: german in the request headers. Optional evidence fields are deployment-specific and omitted from the public examples.

{
  "data": {
    "duration": 24,
    "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"
  }
}

Field Mapping Note For this demo credit profile, send duration. The API mirrors it to duration_months for compatibility. If both are sent, values must match.

Make a Request

Bundled hosted calls use POST /classify?explain=compact. Governed HTTP-connected scorer integrations use POST /hybrid/score?explain=plain. Supported governed endpoints return explicit coverage_pct, routing metadata (router), policy outcome (policy), decision summary (plain_summary), and audit linkage (audit_id). Coverage gates are supported as configured governance controls; hosted branch-by-branch gate behavior should be validated for each deployment/profile. Use /ping for health checks and /audit/export?download=1 for audit pack download.

curl -s -X POST "https://risk.auditvec.com/classify?explain=compact" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -H "X-Config-Id: german" \
  -d '{
    "data": {
      "duration": 24,
      "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_KEY"
$body = @{
  data = @{
    duration = 24
    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=compact" `
  -Headers @{ "Content-Type"="application/json"; "X-API-Key"=$KEY; "X-Config-Id"="german" } `
  -Body $body

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

const API = "https://risk.auditvec.com";
const KEY = "YOUR_KEY";

const body = {
  data: {
    duration: 24,
    credit_amount: 2500,
    age: 35,
    installment_rate: 2,
    residence_since: 3,
    status: "A12",
    credit_history: "A32",
    purpose: "A43",
  },
};

async function run() {
  const res = await fetch(`${API}/classify?explain=compact`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": KEY,
      "X-Config-Id": "german",
    },
    body: JSON.stringify(body),
  });
  const data = await res.json();
  console.log(data.router, data.policy, data.plain_summary);
}

run().catch(console.error);

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
)

func main() {
  body := map[string]interface{}{
    "data": map[string]interface{}{
      "duration":         24,
      "credit_amount":    2500,
      "age":              35,
      "installment_rate": 2,
      "residence_since":  3,
      "status":           "A12",
      "credit_history":   "A32",
      "purpose":          "A43",
    },
  }
  buf, _ := json.Marshal(body)
  req, _ := http.NewRequest("POST", "https://risk.auditvec.com/classify?explain=compact", bytes.NewBuffer(buf))
  req.Header.Set("Content-Type", "application/json")
  req.Header.Set("X-API-Key", "YOUR_KEY")
  req.Header.Set("X-Config-Id", "german")

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()
  fmt.Println(resp.Status)
}

Governed HTTP-connected scorer example

Use this lane when your scorer is exposed over HTTP in an enabled Auditvec deployment. Representative sklearn, xgboost, and Torch-compatible integrations have been validated through that contract during proof testing.

API_BASE="https://YOUR_AUDITVEC_BASE"

curl -s -X POST "$API_BASE/hybrid/score?explain=plain" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -H "X-Config-Id: german" \
  -d '{
    "data": {
      "duration": 24,
      "credit_amount": 2500,
      "age": 35,
      "installment_rate": 2,
      "residence_since": 3,
      "status": "A12",
      "credit_history": "A32",
      "purpose": "A43"
    }
  }'

Typical Response

JSON

{
  "coverage_pct": 100.0,
  "router": {
    "gate_policy": "PASS|REVIEW|FAIL",
    "gate_cov": "OK|LOW",
    "gate_gray": "CLEAR|EDGE",
    "final_decision": "APPROVE|REVIEW|DENY"
  },
  "plain_summary": {
    "decision": "APPROVE|REVIEW|DENY",
    "reason_lines": ["...", "..."]
  },
  "policy": {
    "status": "PASS|REVIEW|FAIL",
    "violations": ["min_duration_not_met"],
    "flags": []
  },
  "audit_id": "abcdef123456"
}

Reason-line boundary: Reason lines are operational decision summaries. They are not automatically validated adverse-action notices or legally sufficient consumer explanations.

Evidence is optional when enabled/configured.

Audit Pack Export (ZIP)

API="https://risk.auditvec.com"
KEY="YOUR_KEY"
CFG="german"

curl -sS -X POST "$API/audit/export?download=1" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KEY" \
  -H "X-Config-Id: $CFG" \
  -d '{}' \
  -o audit_pack.zip

powershell -ExecutionPolicy Bypass -File .\ops\verify_audit_pack.ps1 -ZipPath .\audit_pack.zip

Audit pack export is supported on the bundled and governed HTTP surfaces. It returns a ZIP with SHA-256 checksums; verifier script provided.

Offline Profile Onboarding (Optional)

Available in assisted onboarding and private deployment workflows.

Provide an examples file + mapping file.
We build a profile bundle + versioned signature offline.
Evidence pack can be generated for optional support when enabled.
Production rejects mismatched profile signatures.

Runbook commands: use request smoke tests and the audit pack verifier command during onboarding sign-off. Need onboarding help? Request assisted onboarding.

Scorer Integration Checklist

1) Choose a lane: bundled scorer or governed HTTP-connected scorer.

2) Provide your scorer contract: feature schema, expected probability field, and valid ranges.

3) Configure governance: policy control, coverage checks, and review routing.

4) Set your profile: use X-Config-Id per product/region (for this example: german).

5) Validate latency: target 8-10s client timeouts and retry idempotent calls.

6) Define REVIEW handling: route to human queue or fallback policy.

7) Confirm audit exports: confirm the agreed export path, including scheduled export or an available-by-agreement SIEM/webhook integration.

Example Policy Snapshot

Inspect policy metadata exposed by the deployment. This example shows the public demo profile context; live default profile/config context may differ. The public policy snapshot can be simpler than governed response records, so validate deployment-specific controls before relying on it for release evidence.

GET /policy with public demo profile context

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

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

Endpoints & Authentication

Authentication

For bundled hosted calls and enabled governed HTTP integrations, send Content-Type: application/json, X-API-Key, and X-Config-Id.

Content-Type: application/json
X-API-Key: <your key> (Required for bundled hosted calls and enabled governed HTTP integrations)
X-Config-Id: german (set explicitly per request in public examples)

Public and governed lane endpoints

POST

/classify?explain=compact

Bundled scorer lane. Returns explicit coverage_pct, routing metadata, policy outcome, decision summary, and audit linkage. Some direct hosted responses may also include a compatibility coverage value.

POST

/hybrid/score?explain=plain

Governed integration lane for HTTP-connected scorers. Returns explicit coverage_pct, routing metadata, policy outcome, decision summary, and audit linkage.

GET

/ping

Simple health check endpoint for gateway availability.

POST

/audit/export?download=1

Audit export for the bundled and governed HTTP surfaces. Downloads a ZIP with verifier-friendly checksums.

Common Integration Errors

Missing API key: Send X-API-Key on each bundled hosted call and enabled governed HTTP integration; hosted calls without it return 401.
Wrong profile: Check X-Config-Id matches an allowed profile.
Wrong endpoint: Use /classify?explain=compact for bundled scorers and /hybrid/score?explain=plain for governed HTTP-connected scorers.
Invalid JSON: Ensure your body is valid JSON and properly escaped.
Timeouts: Use 8-10s client timeouts; retry idempotent requests.
REVIEW handling: Treat REVIEW as a human handoff, not a failure.

AI Policy & Scope

This document outlines the governance controls, roles, and risk management strategies employed by the Auditvec Governance 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: Public demo workflows are not intended for applicant PII. Customer data handling and retention are deployment-specific.

Console & Ops

Illustrative private-deployment controls that may be included by agreement; not all controls are available in every deployment.

These examples show how agreed controls can support existing security, compliance, and change-control workflows.

Authentication - typical private deployment controls

SSO / OIDC: SAML or OIDC integration and enforced MFA, where included by agreement.
Service tokens: Scoped API keys for CI/CD and automation, where configured.
Key rotation: Per-tenant key versioning and revocation controls, where included.

RBAC - typical private deployment roles

Owner Coordinates agreed tenant, authentication, and audit-export settings.

Admin Coordinates approved policy and profile configuration changes.

Analyst May view audit logs, coverage metrics, and case reviews where included.

Auditor May receive read-only access to logs, policy history, and exports where included.

Audit logging - typical private deployment controls

Illustrative event types: policy change, profile update, key rotation, access grant, export start.
Illustrative payloads: actor, timestamp, old/new value, and reason code, where configured.
Exports: webhook or scheduled JSON/CSV delivery to a SIEM, where included by agreement.

Change-control workflow - typical private deployment controls

Example sequence when a change-control workflow is included:

Draft a policy/profile update in staging.
Run validation checks (schema, signature, coverage gates).
Request approval through the configured workflow.
Publish a versioned release with rollback.

Audit pack exports include SHA-256 checksums and can be validated with the provided verifier script.

Quickstart Guide

Request Schema

Make a Request

Governed HTTP-connected scorer example

Typical Response

Audit Pack Export (ZIP)

Offline Profile Onboarding (Optional)

Scorer Integration Checklist

Example Policy Snapshot

Endpoints & Authentication

Authentication

Public and governed lane endpoints

Common Integration Errors

AI Policy & Scope

Roles & Responsibilities

Controls

Risk Management

Console & Ops

Authentication - typical private deployment controls

RBAC - typical private deployment roles

Audit logging - typical private deployment controls

Change-control workflow - typical private deployment controls

Example Profile: Demo credit profile

Overview

Routing Logic

Limitations

German Credit benchmark

Monthly Monitoring Checklist

Availability & Version

Calibration

Drift Analysis

Fairness Slices