Skip to main content
POST
/
vishwas
/
analyze
curl -X POST https://api.rotavision.com/v1/vishwas/analyze \
  -H "Authorization: Bearer rv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "loan-approval-v2",
    "dataset": {
      "features": ["age", "income", "credit_score", "gender", "region"],
      "data_url": "s3://my-bucket/loan-data.parquet",
      "predictions": "prediction_col",
      "actuals": "approved_col",
      "protected_attributes": ["gender", "region"]
    },
    "metrics": ["demographic_parity", "equalized_odds", "calibration"],
    "thresholds": {
      "demographic_parity": 0.85,
      "equalized_odds": 0.80
    }
  }'

{
  "id": "analysis_abc123xyz",
  "model_id": "loan-approval-v2",
  "status": "completed",
  "overall_score": 0.82,
  "bias_detected": true,
  "dataset_summary": {
    "total_rows": 50000,
    "protected_groups": {
      "gender": ["male", "female"],
      "region": ["urban", "rural", "semi-urban"]
    }
  },
  "metrics": [
    {
      "name": "demographic_parity",
      "value": 0.78,
      "threshold": 0.85,
      "status": "fail",
      "details": {
        "gender": {
          "male": 0.72,
          "female": 0.65,
          "ratio": 0.90
        },
        "region": {
          "urban": 0.75,
          "rural": 0.58,
          "semi-urban": 0.68,
          "min_ratio": 0.77
        }
      },
      "affected_groups": ["region:rural"]
    },
    {
      "name": "equalized_odds",
      "value": 0.91,
      "threshold": 0.80,
      "status": "pass",
      "details": {
        "tpr_ratio": 0.93,
        "fpr_ratio": 0.89
      }
    },
    {
      "name": "calibration",
      "value": 0.85,
      "threshold": 0.80,
      "status": "pass"
    }
  ],
  "recommendations": [
    {
      "severity": "high",
      "metric": "demographic_parity",
      "group": "region:rural",
      "message": "Rural applicants have 23% lower approval rate despite similar creditworthiness",
      "action": "Review feature weights for location-correlated variables (distance_to_branch, digital_access)",
      "impact_estimate": "+0.12 fairness score improvement"
    }
  ],
  "created_at": "2026-02-01T10:30:00Z",
  "completed_at": "2026-02-01T10:32:15Z"
}

​
Request

​
model_id
string
required
Unique identifier for your model. Used for tracking and comparison.
​
dataset
object
required
The dataset to analyze.
​
metrics
array
default:"['demographic_parity', 'equalized_odds']"
Fairness metrics to calculate. Options:
  • demographic_parity
  • equalized_odds
  • equal_opportunity
  • calibration
  • individual_fairness
  • counterfactual_fairness
​
thresholds
object
Custom thresholds for each metric. Default is 0.8 (80%) for all metrics.
​
reference_groups
object
Specify reference groups for each protected attribute.
​
async
boolean
default:"true"
Whether to run analysis asynchronously. Set to false for small datasets (< 10,000 rows).
​
webhook_url
string
URL to receive webhook when analysis completes.

​
Response

​
id
string
Unique analysis identifier.
​
model_id
string
The model ID provided in the request.
​
status
string
Analysis status: pending, processing, completed, failed.
​
overall_score
number
Aggregate fairness score from 0-1.
​
bias_detected
boolean
Whether any metric fell below its threshold.
​
metrics
array
Detailed results for each fairness metric.
​
recommendations
array
Actionable recommendations for improving fairness.
curl -X POST https://api.rotavision.com/v1/vishwas/analyze \
  -H "Authorization: Bearer rv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "loan-approval-v2",
    "dataset": {
      "features": ["age", "income", "credit_score", "gender", "region"],
      "data_url": "s3://my-bucket/loan-data.parquet",
      "predictions": "prediction_col",
      "actuals": "approved_col",
      "protected_attributes": ["gender", "region"]
    },
    "metrics": ["demographic_parity", "equalized_odds", "calibration"],
    "thresholds": {
      "demographic_parity": 0.85,
      "equalized_odds": 0.80
    }
  }'

{
  "id": "analysis_abc123xyz",
  "model_id": "loan-approval-v2",
  "status": "completed",
  "overall_score": 0.82,
  "bias_detected": true,
  "dataset_summary": {
    "total_rows": 50000,
    "protected_groups": {
      "gender": ["male", "female"],
      "region": ["urban", "rural", "semi-urban"]
    }
  },
  "metrics": [
    {
      "name": "demographic_parity",
      "value": 0.78,
      "threshold": 0.85,
      "status": "fail",
      "details": {
        "gender": {
          "male": 0.72,
          "female": 0.65,
          "ratio": 0.90
        },
        "region": {
          "urban": 0.75,
          "rural": 0.58,
          "semi-urban": 0.68,
          "min_ratio": 0.77
        }
      },
      "affected_groups": ["region:rural"]
    },
    {
      "name": "equalized_odds",
      "value": 0.91,
      "threshold": 0.80,
      "status": "pass",
      "details": {
        "tpr_ratio": 0.93,
        "fpr_ratio": 0.89
      }
    },
    {
      "name": "calibration",
      "value": 0.85,
      "threshold": 0.80,
      "status": "pass"
    }
  ],
  "recommendations": [
    {
      "severity": "high",
      "metric": "demographic_parity",
      "group": "region:rural",
      "message": "Rural applicants have 23% lower approval rate despite similar creditworthiness",
      "action": "Review feature weights for location-correlated variables (distance_to_branch, digital_access)",
      "impact_estimate": "+0.12 fairness score improvement"
    }
  ],
  "created_at": "2026-02-01T10:30:00Z",
  "completed_at": "2026-02-01T10:32:15Z"
}