API Documentation — ModelPassport

POST /audit/full

Run a full four-layer AI bias audit. Accepts a CSV dataset and optional pre-trained model. Returns a complete certificate with scores, warnings, remediation checklist, and Gemini governance narrative. This is the primary endpoint.

Request Parameters (multipart/form-data)

Parameter	Type	Description	Required
dataset_file	file	CSV dataset file. Must include all protected attributes and target column.	Yes
model_file	file	Joblib-serialized scikit-learn model. If omitted, a RandomForest is trained automatically.	No
model_name	string	Human-readable name for the model being audited (e.g. "LoanScorer v2.1").	Yes
organization	string	Name of the organization submitting the audit (e.g. "Acme Bank").	Yes
domain	string	Deployment domain: hiring, loan, healthcare, benefits, or custom string.	Yes
target_column	string	Name of the CSV column containing the binary outcome variable.	Yes
protected_attributes	string	Comma-separated list of column names to audit for fairness (e.g. "race,gender,age").	Yes

Example Request (curl)

curl -X POST https://modelpassport-666743556492.asia-south1.run.app/audit/full \
  -F "dataset_file=@/path/to/adult.csv" \
  -F "model_name=IncomeClassifier v1.0" \
  -F "organization=Research Institute" \
  -F "domain=employment" \
  -F "target_column=income" \
  -F "protected_attributes=race,sex,age"

Example Request (Python)

import requests

with open("adult.csv", "rb") as f:
    response = requests.post(
        "https://modelpassport-666743556492.asia-south1.run.app/audit/full",
        data={
            "model_name":           "IncomeClassifier v1.0",
            "organization":         "Research Institute",
            "domain":               "employment",
            "target_column":        "income",
            "protected_attributes": "race,sex,age",
        },
        files={"dataset_file": f},
    )
certificate = response.json()
print(certificate["certificate_id"])   # MP-2026-000001
print(certificate["overall_score"])      # 57.23
print(certificate["certification_status"]) # NOT CERTIFIED

Response Structure (200 OK)

200 OK 422 Invalid Params 504 Timeout

{
  "certificate_id":        "MP-2026-000001",
  "certification_status":   "NOT CERTIFIED",
  "overall_score":          57.23,
  "model_name":             "IncomeClassifier v1.0",
  "organization":           "Research Institute",
  "domain":                 "employment",
  "issued_at":              "2026-04-18T14:32:00Z",
  "sha256_hash":            "a3f9b2c1...",
  "verify_url":             "https://modelpassport-666743556492.asia-south1.run.app/verify/MP-2026-000001",
  "narrative":              "The model exhibits significant disparate impact...",
  "remediation_checklist": [
    "Re-sample training data to improve minority representation.",
    "Apply fairness constraint during model training."
  ],
  "layer_results": {
    "data_forensics": {
      "health_score": 62.5,
      "status": "WARN",
      "warnings": ["Underrepresentation detected in 'race' column."]
    },
    "stress_test": {
      "bias_score": 44.1,
      "status": "FAIL"
    },
    "fairness_metrics": {
      "overall_fairness_score": 58.7,
      "status": "WARN"
    },
    "gemini_governance": {
      "gemini_status": "ok",
      "severity_summary": {
        "overall_risk_level": "HIGH",
        "total_critical_warnings": 2
      }
    }
  }
}

GET /verify/{certificate_id}

Retrieve and verify a previously issued certificate by its ID. No authentication required — this endpoint is publicly accessible to enable third-party verification.

Path Parameter

Parameter	Type	Description	Required
certificate_id	string	The certificate ID to verify (e.g. MP-2026-000001). URL-encode if necessary.	Yes

Example Request

curl https://modelpassport-666743556492.asia-south1.run.app/verify/MP-2026-000001

Response

200 OK — Full certificate object (same structure as /audit/full response) 404 Not Found

{
  "detail": "Certificate 'MP-2026-999999' not found."
}

GET /health

Liveness check endpoint. Returns service status and version. Use this to verify the API is running before submitting an audit.

Example Request

curl https://modelpassport-666743556492.asia-south1.run.app/health

Response (200 OK)

{
  "status":  "ok",
  "version": "1.0.0"
}

Authentication

🔑 API Key Authentication — Coming Soon

The current prototype does not require authentication. The public API is rate-limited by IP address. Production authentication via API keys will be added before the full commercial release. The Professional and Enterprise plans will include API key management dashboards.

Currently, the GET /verify/{id} endpoint will always remain public with no authentication requirement, by design.

Error Codes

Code	Description
422	Unprocessable Entity — a required field is missing, a protected attribute column was not found in the CSV, or the target column doesn't exist.
404	Not Found — the certificate ID does not exist in the registry.
504	Timeout — audit pipeline exceeded 300 seconds. Try with a smaller dataset or fewer protected attributes.
500	Internal Server Error — unexpected failure. The error message is returned in `detail`.