API reference.

Health probe

Liveness check. Returns the service status, the running engine version, and the engine identifier. Anonymous; no API key required. Use this from a load balancer health check, an uptime monitor, or a CI smoke probe.

Response

{
  "status": "ok",
  "version": "1.4.0",
  "engine": "iadtx-core"
}

Curl

curl https://api.iadtx.com/v1/health

Run the structural diagnostic

Run the IADTX diagnostic against an uploaded dataset. Returns the domain classification, the per-variable force list, the structural reading on the model-comparison block, the fitness reading, the multiscale profile, the closed-vocabulary result envelope, and a portable state_json suitable for later submission to the cascade, transfer, drift, or assumption-audit lenses. Sub-fields on the model-comparison block are part of the locked private calibration and may change between minor versions without notice. The validation hash is a SHA-256 over the canonicalised result and is tamper-evident.

Zero data retention. The upload is held only for the duration of the request and discarded before the response is returned.

Query parameters

• outcome_column (required). Name of the outcome column.
• feature_columns (optional). Comma-separated feature column names. When omitted, every non-outcome column is treated as a feature.
• organisation (optional). Organisation name for report metadata. Preferred British spelling. Never affects the diagnostic result.
• organization Deprecated Legacy spelling retained for backward compatibility. The British spelling wins on precedence when both are passed. Use organisation in new code.
• industry (optional). Industry name for report metadata. Never affects the diagnostic result.
• country (optional). ISO-2 country code for report metadata.

Body

• file (multipart, required). CSV, TSV, or Excel.

Response (abridged)

{
  "domain": "MULTIPLICATIVE",
  "n_multiplicative": 7,
  "n_additive": 2,
  "n_observations": 201,
  "n_features": 9,
  "max_collapse_ratio": 2.10,
  "fitness": {
    "score": 78,
    "label": "Multiplicative domain",
    "tail_risk_ratio": 1.38,
    "summary": "Multiplicative model fits cleanly across the dataset."
  },
  "forces": [
    {
      "variable": "exposure",
      "collapse_ratio": 1.74,
      "classification": "MULTIPLICATIVE",
      "confidence": "high"
    }
  ],
  "model_comparison": {
    "winner": "MULTIPLICATIVE",
    "structural_reading": "above_band"
  },
  "validation_hash": "8b2d4a...",
  "duration_seconds": 1.83,
  "version": "1.4.0",
  "verdict": "MULTIPLICATIVE",
  "headline": "Multiplicative composition confirmed.",
  "result_envelope": { "verdict": "MULTIPLICATIVE", "...": "..." },
  "state_json": { "schema": "iadtx/diagnostic.v1", "...": "..." },
  "attribution": "IADTX engine (iadtx-core), version 1.4.0.",
  "disclaimer": "This artifact provides structural validation evidence..."
}

Curl

curl -X POST "https://api.iadtx.com/v1/diagnose?outcome_column=claim_amount" \
  -H "X-API-Key: $IADTX_API_KEY" \
  -F "file=@insurance_sample.csv"

The upload contract page lists every error subcode the validator can raise on this route. The band readings page documents the closed band vocabulary used in the response.

The confidence field on each force is a qualitative label drawn from a closed vocabulary of high, moderate, low, and not_significant.

The model_comparison.structural_reading field is a closed-vocabulary qualifier on the multiplicative against additive comparison. It carries one of three values, above_band, inside_tie_band, or below_band, and reads in the same direction as the verdict. The band readings page documents the per-reading interpretation. The thresholds that map an internal calculation to a reading are part of the locked private calibration and are not disclosed.

Cross-Model Lens

Compare three or more model prediction vectors and return a decorrelation index plus a per-pair breakdown. Higher values indicate that ensembling genuinely diversifies risk; lower values indicate shared blind spots. The internal scoring is part of the locked private calibration and is not disclosed.

Tier gating on the API is Business and Enterprise. The lens is also available to Pro on app.iadtx.com; Pro is a platform-only tier and has no API access. Zero data retention.

Request body

{
  "models": {
    "model_a": [0.12, 0.84, 0.31, ...],
    "model_b": [0.15, 0.79, 0.28, ...],
    "model_c": [0.42, 0.61, 0.55, ...]
  }
}

Constraints

• At least three models.
• At least twenty observations per vector.
• Every vector the same length.

Response

{
  "n_models": 3,
  "model_names": ["model_a", "model_b", "model_c"],
  "decorrelation_index": 0.48,
  "mean_pairwise_agreement": 0.52,
  "label": "Partially decorrelated",
  "summary": "Two of the three pairs share substantial structure...",
  "most_aligned_pair": "model_a vs model_b",
  "most_divergent_pair": "model_a vs model_c",
  "pairs": [
    {
      "model_a": "model_a",
      "model_b": "model_b",
      "spearman": 0.81,
      "agreement": 0.78,
      "direction": "aligned"
    }
  ],
  "disclaimer": "This artifact provides structural validation evidence..."
}

Curl

curl -X POST https://api.iadtx.com/v1/cross_model \
  -H "X-API-Key: $IADTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d @predictions.json

Missing Force Lens

Return the top candidate variable pairs flagged by the lens, ranked by a surprise score. Each candidate names the two variables, a pairwise relationship score, individual structural strengths, and the surprise score. The internal scoring rule is part of the locked private calibration and is not disclosed. On the API, both Business and Enterprise return the top five candidates (the full variant). The simple variant (top three) is available to Growth and Pro on app.iadtx.com only.

Zero data retention.

Query parameters

• outcome_column (required).
• feature_columns (optional). Comma-separated feature names.

Body

• file (multipart, required). CSV, TSV, or Excel.

Response

{
  "n_candidates": 5,
  "candidates": [
    {
      "force_a": "exposure",
      "force_b": "tenure",
      "observed_correlation": 0.12,
      "individual_strength_a": 0.71,
      "individual_strength_b": 0.64,
      "surprise": 0.83,
      "summary": "Both variables drive the outcome but barely correlate..."
    }
  ],
  "most_suspicious_pair": "exposure vs tenure",
  "summary": "Five pairs exceed the surprise threshold...",
  "disclaimer": "This artifact provides structural validation evidence..."
}

Curl

curl -X POST "https://api.iadtx.com/v1/missing_force?outcome_column=claim_amount" \
  -H "X-API-Key: $IADTX_API_KEY" \
  -F "file=@insurance_sample.csv"

Cascade Lens

Compare two signed diagnostic states over time. Returns which variables strengthened, weakened, or changed classification, the count of domain flips, and the overall trajectory (stable, escalating, de-escalating, restructuring). Both states must be tamper-evident; states whose signature does not verify are rejected.

Tier gating on the API is Business and Enterprise. The lens is also available to Pro on app.iadtx.com. Zero data retention.

Request body

{
  "prior_state":   { "schema": "iadtx/diagnostic.v1", "...": "..." },
  "current_state": { "schema": "iadtx/diagnostic.v1", "...": "..." }
}

Response (abridged)

{
  "n_common": 9,
  "n_strengthened": 3,
  "n_weakened": 1,
  "n_stable": 5,
  "n_domain_flips": 0,
  "prior_fitness": 71,
  "current_fitness": 78,
  "fitness_delta": 7,
  "prior_domain": "MULTIPLICATIVE",
  "current_domain": "MULTIPLICATIVE",
  "trend": "stable",
  "summary": "Most variables held; three strengthened modestly...",
  "moves": [
    {
      "variable": "exposure",
      "prior_cr": 1.31,
      "current_cr": 1.61,
      "delta": 0.19,
      "direction": "strengthened",
      "prior_class": "MULTIPLICATIVE",
      "current_class": "MULTIPLICATIVE"
    }
  ],
  "disclaimer": "This artifact provides structural validation evidence..."
}

Curl

curl -X POST https://api.iadtx.com/v1/cascade \
  -H "X-API-Key: $IADTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d @cascade_request.json

Transfer Lens

Test whether the structural form of a decision transfers across two environments (for example training versus production, or EU versus US). Both inputs are signed diagnostic states. The lens returns the verdict (transfers_cleanly, partial_transfer, or non_transferable), the per-variable comparison, and a similarity score.

Tier gating is Business and Enterprise on every surface. Zero data retention.

Request body

{
  "state_a": { "schema": "iadtx/diagnostic.v1", "...": "..." },
  "state_b": { "schema": "iadtx/diagnostic.v1", "...": "..." },
  "environment_a_name": "training",
  "environment_b_name": "production"
}

Optional fields

• environment_a_name (optional). Free-text label for the first environment. Echoed into the response under environment_a and into the per-variable environment_a_value. Preferred public spelling.
• environment_b_name (optional). Free-text label for the second environment. Echoed into the response under environment_b and into the per-variable environment_b_value. Preferred public spelling.

Response (abridged)

{
  "n_common": 9,
  "similarity_score": 0.84,
  "classification_agreement": 0.89,
  "n_classification_flips": 1,
  "domain_a": "MULTIPLICATIVE",
  "domain_b": "MULTIPLICATIVE",
  "fitness_a": 78,
  "fitness_b": 74,
  "fitness_delta": -4,
  "environment_a": "training",
  "environment_b": "production",
  "verdict": "transfers_cleanly",
  "summary": "Structural form holds across the two environments...",
  "variables": [
    {
      "variable": "exposure",
      "classification_match": true,
      "cr_gap": 0.03,
      "environment_a_value": 1.31,
      "environment_b_value": 1.34
    }
  ],
  "disclaimer": "This artifact provides structural validation evidence..."
}

The response carries the two environment labels at the top level under environment_a and environment_b, and per-environment sub-fields on each variable under environment_a_value and environment_b_value.

Curl

curl -X POST https://api.iadtx.com/v1/transfer \
  -H "X-API-Key: $IADTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d @transfer_request.json

Agent Chain Lens

Diagnose a multi-agent trace. Each tool is scored as an independent factor against the chain success outcome. Returns which tools dominate the success signal and classifies the chain as resilient, fragile, or cascade_risk. Accepts a LangChain or LangGraph JSON trace, or a list of dicts with at minimum a tool field and a success field.

Tier gating is Business and Enterprise on every surface. Zero data retention.

Request body

{
  "trace": [
    { "tool": "search", "success": true,  "latency_ms": 142 },
    { "tool": "fetch",  "success": true,  "latency_ms": 211 },
    { "tool": "search", "success": false, "latency_ms": 187 }
  ]
}

Constraints

• At least five tool calls.
• At least two distinct tools.
• Each step must include tool and success.

Response (abridged)

{
  "n_steps": 142,
  "n_agents": 3,
  "n_tools": 7,
  "overall_success_rate": 0.81,
  "mean_tool_cr": 1.34,
  "n_dominant_tools": 1,
  "mean_latency_ms": 198.4,
  "total_output_tokens": 41203,
  "verdict": "fragile",
  "summary": "One tool drives most of the success signal...",
  "tool_risks": [
    {
      "tool": "search",
      "n_calls": 58,
      "success_rate": 0.79,
      "collapse_ratio": 1.81,
      "classification": "MULTIPLICATIVE",
      "mean_latency_ms": 162.1,
      "mean_output_tokens": 312.0
    }
  ],
  "disclaimer": "This artifact provides structural validation evidence..."
}

Curl

curl -X POST https://api.iadtx.com/v1/agent_chain \
  -H "X-API-Key: $IADTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d @agent_trace.json

Assumption Audit Lens

Score three to ten plain-text modelling assumptions against a signed diagnostic state. Each assumption receives a challenge score from zero to one hundred and a verdict that records whether observed evidence supports, partially supports, or contradicts the assumption. Findings only; no recommendations.

Tier gating is Enterprise only on every surface. Zero data retention.

Request body

{
  "state": { "schema": "iadtx/diagnostic.v1", "...": "..." },
  "assumptions": [
    "Exposure is the dominant driver of claim severity.",
    "Tenure has a monotonic positive effect on outcome.",
    "Region is independent of pricing band."
  ]
}

Response (abridged)

{
  "n_assumptions": 3,
  "n_scorable": 3,
  "top_assumption_index": 0,
  "mean_challenge": 38.0,
  "summary": "Two of three assumptions are partially supported...",
  "findings": [
    {
      "index": 0,
      "assumption": "Exposure is the dominant driver of claim severity.",
      "matched_variables": ["exposure"],
      "polarity": "positive",
      "implied_cr": 1.50,
      "observed_cr": 1.68,
      "challenge_score": 18,
      "verdict": "supported",
      "explanation": "Observed strength of exposure is 0.74 versus the dataset mean of 0.50. Worth checking whether the modelling framing matches this level of structural weight."
    }
  ],
  "disclaimer": "This artifact provides structural validation evidence..."
}

Curl

curl -X POST https://api.iadtx.com/v1/assumption_audit \
  -H "X-API-Key: $IADTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d @audit_request.json

Drift comparison

Compare between two and ten IADTX diagnostic state snapshots over time. The states are the JSON payloads returned by /v1/diagnose as the state_json field, or the equivalents downloaded from the app. Each state is verified against its embedded SHA-256 signature; tampered states are rejected before comparison.

Zero data retention. Inputs and outputs live only in the request and response cycle.

Request body

{
  "states": [
    { "schema": "iadtx/diagnostic.v1", "report_id": "r-1", "...": "..." },
    { "schema": "iadtx/diagnostic.v1", "report_id": "r-2", "...": "..." },
    { "schema": "iadtx/diagnostic.v1", "report_id": "r-3", "...": "..." }
  ]
}

Response

{
  "n_states": 3,
  "timeline": [
    {
      "generated_at": "2026-04-01T12:00:00Z",
      "report_id": "r-1",
      "fitness_score": 71,
      "fitness_label": "Multiplicative domain",
      "domain": "MULTIPLICATIVE",
      "n_multiplicative": 6,
      "max_collapse_ratio": 1.54
    }
  ],
  "fitness_trajectory": [71, 74, 78],
  "fitness_change": 7,
  "domain_changes": 0,
  "trend": "improving",
  "summary": "Three snapshots show a steady improvement in fitness...",
  "disclaimer": "This artifact provides structural validation evidence..."
}

Curl

curl -X POST https://api.iadtx.com/v1/drift/compare \
  -H "X-API-Key: $IADTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d @drift_states.json