Public interface

Model outputs API

Stable JSON resources for FinObservatory-created outputs, with required caveats, source attribution and a generated OpenAPI 3.1 contract.

OpenAPI JSON

The public boundary

Available: coefficients, aggregate evaluations, one requested output-only score and FinObservatory-created index values. Not available: source records, raw feature vectors, institution tables, bulk entity rankings, watchlists, defaulter lists or CSV responses. No registration or API key is required.

Validation travels with the output

The banking-crisis early-warning model underperforms the BIS credit-gap benchmark out of sample. Its pooled ROC AUC is 0.624, compared with 0.679 for the benchmark, across 5,930 test country-years and 389 crisis onsets. The API returns these evaluation fields and the caveat beside every early-warning score.

Source: FinObservatory pooled early-warning out-of-sample evaluation Model version ews-1.0; vintage jst-r6(2020);lv-2026-wp2694(2023);bis-gap(2025-Q4);gmd-2026_06(cut2024). Methodology

Endpoints

Every path, input, response field, curl command and OpenAPI operation below comes from one runtime registry. Score identifiers are mandatory. Misspelled or extra query parameters return HTTP 400 instead of being ignored.

parameters

Banking-crisis early-warning coefficients and aggregate evaluation

GET

/api/v1/models/crisis-early-warning/parameters

This is a modelled probability, not a forecast. The pooled out-of-sample model AUC is 0.624, below the 0.679 BIS credit-gap benchmark, so the output is a research screen and not a warning about a country.

Methodology · Operation ID: getCrisisEarlyWarningParameters

Required query parameters

None. Any query parameter is rejected.

Response fields

Field	Type	Meaning
model_version	string · required	Published model version.
data_vintage	string · required	Input vintages recorded by the model build.
coefficients	array · required	Published fitted coefficients and preprocessing parameters, without source feature values.
coefficients[].feature	string · required	Stable feature key.
coefficients[].label	string · required	Human-readable feature label.
coefficients[].coefficient	number · required	Fitted logistic coefficient.
coefficients[].is_flag	boolean · required	Whether the feature is a missingness flag.
coefficients[].winsor_low	number \| null · required	Lower winsorization bound, null when not applicable.
coefficients[].winsor_high	number \| null · required	Upper winsorization bound, null when not applicable.
coefficients[].median_impute	number \| null · required	Training-sample median imputation value, null when not applicable.
coefficients[].mean	number \| null · required	Training-sample standardization mean, null when not applicable.
coefficients[].sd	number \| null · required	Training-sample standard deviation, null when not applicable.
evaluation	object · required	Structured output field.
evaluation.test_observations	integer · required	Out-of-sample test country-years.
evaluation.positive_events	integer · required	Crisis onsets in the test observations.
evaluation.model_auc	number · required	Pooled out-of-sample ROC AUC.
evaluation.benchmark_auc	number · required	BIS credit-gap benchmark ROC AUC.
caveat	string · required	Required interpretation and model-limit warning.
methodology	string · required	FinObservatory methodology page.
sources	array · required	Attribution for the inputs used to derive this output.
sources[].label	string · required	Source name.
sources[].url	string · required	Publisher or source landing page.

curl

curl 'https://finobservatory.org/api/v1/models/crisis-early-warning/parameters'

Example response

{
  "model_version": "ews-1.0",
  "data_vintage": "jst-r6(2020);lv-2026-wp2694(2023);bis-gap(2025-Q4);gmd-2026_06(cut2024)",
  "coefficients": [
    {
      "feature": "credit_gap",
      "label": "Credit-to-GDP gap (pp)",
      "coefficient": 0.26619169575912377,
      "is_flag": false,
      "winsor_low": -32.013600000000004,
      "winsor_high": 29.690760000000004,
      "median_impute": 1.1709999999999998,
      "mean": 1.0731940207589654,
      "sd": 9.530995254917102
    }
  ],
  "evaluation": {
    "test_observations": 5930,
    "positive_events": 389,
    "model_auc": 0.6242230737076127,
    "benchmark_auc": 0.6794201861130995
  },
  "caveat": "This is a modelled probability, not a forecast. The pooled out-of-sample model AUC is 0.624, below the 0.679 BIS credit-gap benchmark, so the output is a research screen and not a warning about a country.",
  "methodology": "/crises/early-warning",
  "sources": [
    {
      "label": "Jordà-Schularick-Taylor Macrohistory Database",
      "url": "https://www.macrohistory.net/database/"
    },
    {
      "label": "Laeven-Valencia Systemic Banking Crises Database",
      "url": "https://www.imf.org/en/Publications/WP/Issues/2020/08/28/Systemic-Banking-Crises-Database-II-49660"
    },
    {
      "label": "BIS credit-to-GDP gaps",
      "url": "https://www.bis.org/statistics/c_gaps.htm"
    },
    {
      "label": "Global Macro Database",
      "url": "https://www.globalmacrodata.com/"
    }
  ]
}

Source: Jordà-Schularick-Taylor Macrohistory Database | Laeven-Valencia Systemic Banking Crises Database | BIS credit-to-GDP gaps | Global Macro Database Methodology

parameters

Bank-failure nowcast coefficients and aggregate evaluation

GET

/api/v1/models/bank-failure-nowcast/parameters

This is a vulnerability score from public call-report ratios, not a failure prediction, CAMELS rating or supervisory judgment. The model did not flag the three large US bank failures of 2023 before they failed.

Methodology · Operation ID: getBankFailureNowcastParameters

Required query parameters

None. Any query parameter is rejected.

Response fields

Field	Type	Meaning
model	string · required	Published model key.
as_of_year	integer · required	Coefficient build year.
coefficients	array · required	Published fitted coefficients and standardization parameters.
coefficients[].feature	string · required	Stable feature key.
coefficients[].coefficient	number · required	Fitted logistic coefficient.
coefficients[].mean	number \| null · required	Training-sample standardization mean, null for the intercept.
coefficients[].sd	number \| null · required	Training-sample standard deviation, null for the intercept.
evaluation	object · required	Structured output field.
evaluation.test_observations	integer · required	Out-of-sample institution-quarters.
evaluation.failures	integer · required	Failures in the test observations.
evaluation.auc	number · required	Pooled out-of-sample ROC AUC.
evaluation.recall_top_one_percent	number · required	Failure recall within the top one percent of scores.
evaluation.recall_top_five_percent	number · required	Failure recall within the top five percent of scores.
caveat	string · required	Required interpretation and model-limit warning.
methodology	string · required	FinObservatory methodology page.
sources	array · required	Attribution for the inputs used to derive this output.
sources[].label	string · required	Source name.
sources[].url	string · required	Publisher or source landing page.

curl

curl 'https://finobservatory.org/api/v1/models/bank-failure-nowcast/parameters'

Example response

{
  "model": "logit_full8",
  "as_of_year": 2026,
  "coefficients": [
    {
      "feature": "__intercept__",
      "coefficient": -9.672353951250182,
      "mean": null,
      "sd": null
    }
  ],
  "evaluation": {
    "test_observations": 126859,
    "failures": 62,
    "auc": 0.740677186063474,
    "recall_top_one_percent": 0.43548387096774194,
    "recall_top_five_percent": 0.5967741935483871
  },
  "caveat": "This is a vulnerability score from public call-report ratios, not a failure prediction, CAMELS rating or supervisory judgment. The model did not flag the three large US bank failures of 2023 before they failed.",
  "methodology": "/banks/nowcast",
  "sources": [
    {
      "label": "FFIEC Central Data Repository call reports",
      "url": "https://cdr.ffiec.gov/public/PWS/DownloadBulkData.aspx"
    },
    {
      "label": "FDIC Failures and Assistance Transactions",
      "url": "https://banks.data.fdic.gov/bankfind-suite/failures"
    }
  ]
}

Source: FFIEC Central Data Repository call reports | FDIC Failures and Assistance Transactions Methodology

parameters

Sovereign-stress coefficients and aggregate evaluations

GET

/api/v1/models/sovereign-stress/parameters

This is a screen over public annual macro data, not a forecast or rating. The model loses to debt/GDP alone in both published evaluations, so debt/GDP is the better single public indicator.

Methodology · Operation ID: getSovereignStressParameters

Required query parameters

None. Any query parameter is rejected.

Response fields

Field	Type	Meaning
coefficients	array · required	Published fitted coefficients, without source feature values.
coefficients[].feature	string · required	Stable feature key.
coefficients[].coefficient	number · required	Fitted logistic coefficient.
evaluation	array · required	Pooled walk-forward and natural-experiment evaluations.
evaluation[].scope	string · required	Published evaluation design.
evaluation[].test_observations	integer · required	Observations in the evaluation.
evaluation[].positive_events	integer · required	Sovereign credit events in the evaluation.
evaluation[].model_auc	number · required	Model ROC AUC.
evaluation[].benchmark_auc	number · required	Debt-to-GDP benchmark ROC AUC.
caveat	string · required	Required interpretation and model-limit warning.
methodology	string · required	FinObservatory methodology page.
sources	array · required	Attribution for the inputs used to derive this output.
sources[].label	string · required	Source name.
sources[].url	string · required	Publisher or source landing page.

curl

curl 'https://finobservatory.org/api/v1/models/sovereign-stress/parameters'

Example response

{
  "coefficients": [
    {
      "feature": "debt_gdp",
      "coefficient": 0.20064767992175214
    }
  ],
  "evaluation": [
    {
      "scope": "pooled",
      "test_observations": 4445,
      "positive_events": 79,
      "model_auc": 0.6889572473138231,
      "benchmark_auc": 0.7461802072400656
    },
    {
      "scope": "natural_experiment",
      "test_observations": 142,
      "positive_events": 12,
      "model_auc": 0.6487179487179487,
      "benchmark_auc": 0.717948717948718
    }
  ],
  "caveat": "This is a screen over public annual macro data, not a forecast or rating. The model loses to debt/GDP alone in both published evaluations, so debt/GDP is the better single public indicator.",
  "methodology": "/sovereign/stress",
  "sources": [
    {
      "label": "Global Macro Database",
      "url": "https://www.globalmacrodata.com/"
    },
    {
      "label": "Bank of Canada and Bank of England sovereign default database",
      "url": "https://www.bankofcanada.ca/2025/07/staff-analytical-note-2025-11/"
    }
  ]
}

Source: Global Macro Database | Bank of Canada and Bank of England sovereign default database Methodology

score

One requested country banking-crisis early-warning score

GET

/api/v1/scores/crisis-early-warning?iso3=USA

Methodology · Operation ID: getCrisisEarlyWarningScore

Required query parameters

iso3: Uppercase ISO 3166-1 alpha-3 country code. Example: USA.

Response fields

Field	Type	Meaning
entity	object · required	Requested entity identifier only.
entity.iso3	string · required	Requested ISO 3166-1 alpha-3 code.
as_of_year	integer · required	Year assigned to the score.
features_through_year	integer · required	Latest year of source features used by the score.
score	object · required	Structured output field.
score.p_onset_next_three_years	number · required	Modelled probability of a banking-crisis onset in the next three years.
score.decile	integer · required	Within-vintage score decile.
model_version	string · required	Published model version.
data_vintage	string · required	Input vintages recorded by the model build.
evaluation	object · required	Structured output field.
evaluation.test_observations	integer · required	Out-of-sample test country-years.
evaluation.positive_events	integer · required	Crisis onsets in the test observations.
evaluation.model_auc	number · required	Pooled out-of-sample ROC AUC.
evaluation.benchmark_auc	number · required	BIS credit-gap benchmark ROC AUC.
caveat	string · required	Required interpretation and model-limit warning.
methodology	string · required	FinObservatory methodology page.
sources	array · required	Attribution for the inputs used to derive this output.
sources[].label	string · required	Source name.
sources[].url	string · required	Publisher or source landing page.

curl

curl 'https://finobservatory.org/api/v1/scores/crisis-early-warning?iso3=USA'

Example response

{
  "entity": {
    "iso3": "USA"
  },
  "as_of_year": 2025,
  "features_through_year": 2024,
  "score": {
    "p_onset_next_three_years": 0.04268882307809985,
    "decile": 4
  },
  "model_version": "ews-1.0",
  "data_vintage": "jst-r6(2020);lv-2026-wp2694(2023);bis-gap(2025-Q4);gmd-2026_06(cut2024)",
  "evaluation": {
    "test_observations": 5930,
    "positive_events": 389,
    "model_auc": 0.6242230737076127,
    "benchmark_auc": 0.6794201861130995
  },
  "caveat": "This is a modelled probability, not a forecast. The pooled out-of-sample model AUC is 0.624, below the 0.679 BIS credit-gap benchmark, so the output is a research screen and not a warning about a country.",
  "methodology": "/crises/early-warning",
  "sources": [
    {
      "label": "Jordà-Schularick-Taylor Macrohistory Database",
      "url": "https://www.macrohistory.net/database/"
    },
    {
      "label": "Laeven-Valencia Systemic Banking Crises Database",
      "url": "https://www.imf.org/en/Publications/WP/Issues/2020/08/28/Systemic-Banking-Crises-Database-II-49660"
    },
    {
      "label": "BIS credit-to-GDP gaps",
      "url": "https://www.bis.org/statistics/c_gaps.htm"
    },
    {
      "label": "Global Macro Database",
      "url": "https://www.globalmacrodata.com/"
    }
  ]
}

Source: Jordà-Schularick-Taylor Macrohistory Database | Laeven-Valencia Systemic Banking Crises Database | BIS credit-to-GDP gaps | Global Macro Database Methodology

score

One requested institution bank-failure nowcast score

GET

/api/v1/scores/bank-failure-nowcast?cert=628

Methodology · Operation ID: getBankFailureNowcastScore

Required query parameters

cert: Positive FDIC certificate number. Example: 628.

Response fields

Field	Type	Meaning
entity	object · required	Requested entity identifier only.
entity.cert	integer · required	Requested FDIC certificate number.
as_of	string · required	Call-report date assigned to the score.
model	string · required	Published model key.
score	object · required	Structured output field.
score.modelled_p_fail_four_quarters	number · required	Modelled probability of failure within four quarters.
score.vulnerability_percentile	number · required	Within-vintage vulnerability percentile.
evaluation	object · required	Structured output field.
evaluation.test_observations	integer · required	Out-of-sample institution-quarters.
evaluation.failures	integer · required	Failures in the test observations.
evaluation.auc	number · required	Pooled out-of-sample ROC AUC.
evaluation.recall_top_one_percent	number · required	Failure recall within the top one percent of scores.
evaluation.recall_top_five_percent	number · required	Failure recall within the top five percent of scores.
caveat	string · required	Required interpretation and model-limit warning.
methodology	string · required	FinObservatory methodology page.
sources	array · required	Attribution for the inputs used to derive this output.
sources[].label	string · required	Source name.
sources[].url	string · required	Publisher or source landing page.

curl

curl 'https://finobservatory.org/api/v1/scores/bank-failure-nowcast?cert=628'

Example response

{
  "entity": {
    "cert": 628
  },
  "as_of": "2026-03-31",
  "model": "logit_full8",
  "score": {
    "modelled_p_fail_four_quarters": 0.0002522955375452727,
    "vulnerability_percentile": 75.83025830258303
  },
  "evaluation": {
    "test_observations": 126859,
    "failures": 62,
    "auc": 0.740677186063474,
    "recall_top_one_percent": 0.43548387096774194,
    "recall_top_five_percent": 0.5967741935483871
  },
  "caveat": "This is a vulnerability score from public call-report ratios, not a failure prediction, CAMELS rating or supervisory judgment. The model did not flag the three large US bank failures of 2023 before they failed.",
  "methodology": "/banks/nowcast",
  "sources": [
    {
      "label": "FFIEC Central Data Repository call reports",
      "url": "https://cdr.ffiec.gov/public/PWS/DownloadBulkData.aspx"
    },
    {
      "label": "FDIC Failures and Assistance Transactions",
      "url": "https://banks.data.fdic.gov/bankfind-suite/failures"
    }
  ]
}

Source: FFIEC Central Data Repository call reports | FDIC Failures and Assistance Transactions Methodology

score

One requested country sovereign-stress score

GET

/api/v1/scores/sovereign-stress?iso3=USA

This is a screen over public annual macro data, not a forecast or rating. The model loses to debt/GDP alone in both published evaluations, so debt/GDP is the better single public indicator.

Methodology · Operation ID: getSovereignStressScore

Required query parameters

iso3: Uppercase ISO 3166-1 alpha-3 country code. Example: USA.

Response fields

Field	Type	Meaning
entity	object · required	Requested entity identifier only.
entity.iso3	string · required	Requested ISO 3166-1 alpha-3 code.
as_of_year	integer · required	Year assigned to the score.
score	object · required	Structured output field.
score.modelled_p_credit_event_three_years	number · required	Modelled probability of a sovereign credit event within three years.
score.stress_percentile	number · required	Within-vintage stress percentile.
evaluation	array · required	Pooled walk-forward and natural-experiment evaluations.
evaluation[].scope	string · required	Published evaluation design.
evaluation[].test_observations	integer · required	Observations in the evaluation.
evaluation[].positive_events	integer · required	Sovereign credit events in the evaluation.
evaluation[].model_auc	number · required	Model ROC AUC.
evaluation[].benchmark_auc	number · required	Debt-to-GDP benchmark ROC AUC.
caveat	string · required	Required interpretation and model-limit warning.
methodology	string · required	FinObservatory methodology page.
sources	array · required	Attribution for the inputs used to derive this output.
sources[].label	string · required	Source name.
sources[].url	string · required	Publisher or source landing page.

curl

curl 'https://finobservatory.org/api/v1/scores/sovereign-stress?iso3=USA'

Example response

{
  "entity": {
    "iso3": "USA"
  },
  "as_of_year": 2024,
  "score": {
    "modelled_p_credit_event_three_years": 0.059083761858970255,
    "stress_percentile": 73.12775330396477
  },
  "evaluation": [
    {
      "scope": "pooled",
      "test_observations": 4445,
      "positive_events": 79,
      "model_auc": 0.6889572473138231,
      "benchmark_auc": 0.7461802072400656
    },
    {
      "scope": "natural_experiment",
      "test_observations": 142,
      "positive_events": 12,
      "model_auc": 0.6487179487179487,
      "benchmark_auc": 0.717948717948718
    }
  ],
  "caveat": "This is a screen over public annual macro data, not a forecast or rating. The model loses to debt/GDP alone in both published evaluations, so debt/GDP is the better single public indicator.",
  "methodology": "/sovereign/stress",
  "sources": [
    {
      "label": "Global Macro Database",
      "url": "https://www.globalmacrodata.com/"
    },
    {
      "label": "Bank of Canada and Bank of England sovereign default database",
      "url": "https://www.bankofcanada.ca/2025/07/staff-analytical-note-2025-11/"
    }
  ]
}

Source: Global Macro Database | Bank of Canada and Bank of England sovereign default database Methodology

index

FinObservatory financial-conditions index observations

GET

/api/v1/indices/financial-conditions

This is a FinObservatory-created composite of standardized financial indicators. It describes prevailing conditions and is not a forecast, trading signal or source-data series.

Methodology · Operation ID: getFinancialConditionsIndex

Required query parameters

None. Any query parameter is rejected.

Response fields

Field	Type	Meaning
frequency	"quarterly" · required	Observation frequency.
observations	array · required	FinObservatory-created FCI observations only.
observations[].date	string · required	Quarter-end observation date.
observations[].value	number · required	Standardized financial-conditions index value.
observations[].regime	string · required	Derived conditions regime.
caveat	string · required	Required interpretation and model-limit warning.
methodology	string · required	FinObservatory methodology page.
sources	array · required	Attribution for the inputs used to derive this output.
sources[].label	string · required	Source name.
sources[].url	string · required	Publisher or source landing page.

curl

curl 'https://finobservatory.org/api/v1/indices/financial-conditions'

Example response

{
  "observations": [
    {
      "date": "2026-03-31",
      "value": -0.6834531477168461,
      "regime": "EXPANSION"
    }
  ],
  "frequency": "quarterly",
  "caveat": "This is a FinObservatory-created composite of standardized financial indicators. It describes prevailing conditions and is not a forecast, trading signal or source-data series.",
  "methodology": "/conditions/methodology",
  "sources": [
    {
      "label": "Federal Reserve Economic Data",
      "url": "https://fred.stlouisfed.org/"
    },
    {
      "label": "BIS credit statistics",
      "url": "https://www.bis.org/statistics/totcredit.htm"
    }
  ]
}

Source: Federal Reserve Economic Data | BIS credit statistics Methodology

index

FinObservatory annual Federal Reserve tone index observations

GET

/api/v1/indices/fed-tone

This lexicon count is descriptive, not causal and not a policy-shock measure. Corpus composition changes over time, and thin years are returned as null rather than imputed.

Methodology · Operation ID: getFedToneIndex

Required query parameters

None. Any query parameter is rejected.

Response fields

Field	Type	Meaning
frequency	"annual" · required	Observation frequency.
observations	array · required	Annual net tone observations pooled across document types.
observations[].year	integer · required	Calendar year.
observations[].value	number \| null · required	Net tone, (hawkish matches minus dovish matches) divided by total matches.
null_rule	string · required	Rule used to preserve thin years as null.
caveat	string · required	Required interpretation and model-limit warning.
methodology	string · required	FinObservatory methodology page.
sources	array · required	Attribution for the inputs used to derive this output.
sources[].label	string · required	Source name.
sources[].url	string · required	Publisher or source landing page.

curl

curl 'https://finobservatory.org/api/v1/indices/fed-tone'

Example response

{
  "observations": [
    {
      "year": 2026,
      "value": 0.36681222707423583
    }
  ],
  "frequency": "annual",
  "null_rule": "The value is null when a pooled year has fewer than 20 hawkish and dovish matches combined.",
  "caveat": "This lexicon count is descriptive, not causal and not a policy-shock measure. Corpus composition changes over time, and thin years are returned as null rather than imputed.",
  "methodology": "/library/fomc/tone",
  "sources": [
    {
      "label": "Federal Reserve historical materials and current releases",
      "url": "https://www.federalreserve.gov/monetarypolicy/fomc_historical.htm"
    }
  ]
}

Source: Federal Reserve historical materials and current releases Methodology

Contract and errors

The generated OpenAPI 3.1 JSON specification uses JSON Schema 2020-12. Invalid identifiers and unknown parameters return 400, absent scores return 404, and query failures return 503. Successful JSON responses use a one-hour shared-cache policy with stale revalidation.