{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"FinObservatory Model Outputs API","version":"1.0.0","description":"Public coefficients, aggregate evaluations, one requested output-only score and FinObservatory-created indices. Source records, bulk rankings, watchlists and raw feature vectors are not served.","license":{"name":"Output-specific source attribution is included in every response"}},"servers":[{"url":"https://finobservatory.org","description":"Canonical FinObservatory server"}],"tags":[{"name":"Parameters","description":"Published coefficients and aggregate model evaluations."},{"name":"Scores","description":"One output-only score for one required identifier."},{"name":"Indices","description":"FinObservatory-created index observations."}],"paths":{"/api/v1/models/crisis-early-warning/parameters":{"get":{"operationId":"getCrisisEarlyWarningParameters","tags":["Parameters"],"summary":"Banking-crisis early-warning coefficients and aggregate evaluation","description":"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.","externalDocs":{"description":"Methodology","url":"https://finobservatory.org/crises/early-warning"},"security":[],"parameters":[],"responses":{"200":{"description":"Model output returned successfully.","headers":{"Cache-Control":{"description":"Public cache policy.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["model_version","data_vintage","coefficients","evaluation","caveat","methodology","sources"],"properties":{"model_version":{"type":"string","description":"Published model version."},"data_vintage":{"type":"string","description":"Input vintages recorded by the model build."},"coefficients":{"type":"array","minItems":1,"description":"Published fitted coefficients and preprocessing parameters, without source feature values.","items":{"type":"object","additionalProperties":false,"required":["feature","label","coefficient","is_flag","winsor_low","winsor_high","median_impute","mean","sd"],"properties":{"feature":{"type":"string","description":"Stable feature key."},"label":{"type":"string","description":"Human-readable feature label."},"coefficient":{"type":"number","description":"Fitted logistic coefficient."},"is_flag":{"type":"boolean","description":"Whether the feature is a missingness flag."},"winsor_low":{"type":["number","null"],"description":"Lower winsorization bound, null when not applicable."},"winsor_high":{"type":["number","null"],"description":"Upper winsorization bound, null when not applicable."},"median_impute":{"type":["number","null"],"description":"Training-sample median imputation value, null when not applicable."},"mean":{"type":["number","null"],"description":"Training-sample standardization mean, null when not applicable."},"sd":{"type":["number","null"],"description":"Training-sample standard deviation, null when not applicable."}}}},"evaluation":{"type":"object","additionalProperties":false,"required":["test_observations","positive_events","model_auc","benchmark_auc"],"properties":{"test_observations":{"type":"integer","description":"Out-of-sample test country-years."},"positive_events":{"type":"integer","description":"Crisis onsets in the test observations."},"model_auc":{"type":"number","minimum":0,"maximum":1,"description":"Pooled out-of-sample ROC AUC."},"benchmark_auc":{"type":"number","minimum":0,"maximum":1,"description":"BIS credit-gap benchmark ROC AUC."}}},"caveat":{"type":"string","description":"Required interpretation and model-limit warning."},"methodology":{"type":"string","format":"uri-reference","description":"FinObservatory methodology page."},"sources":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["label","url"],"properties":{"label":{"type":"string","description":"Source name."},"url":{"type":"string","format":"uri","description":"Publisher or source landing page."}}},"description":"Attribution for the inputs used to derive this output."}}},"example":{"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/"}]}}}},"400":{"description":"Missing, invalid or unrecognised query parameter.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Stable human-readable error."},"links":{"type":"object","additionalProperties":false,"required":["documentation","openapi"],"properties":{"documentation":{"type":"string","format":"uri-reference"},"openapi":{"type":"string","format":"uri-reference"}}}}},"example":{"error":"invalid query parameter"}}}},"503":{"description":"The model output query is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Stable human-readable error."},"links":{"type":"object","additionalProperties":false,"required":["documentation","openapi"],"properties":{"documentation":{"type":"string","format":"uri-reference"},"openapi":{"type":"string","format":"uri-reference"}}}}},"example":{"error":"model output unavailable"}}}}},"x-finobservatory-kind":"parameters","x-finobservatory-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.","x-finobservatory-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/"}]}},"/api/v1/models/bank-failure-nowcast/parameters":{"get":{"operationId":"getBankFailureNowcastParameters","tags":["Parameters"],"summary":"Bank-failure nowcast coefficients and aggregate evaluation","description":"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.","externalDocs":{"description":"Methodology","url":"https://finobservatory.org/banks/nowcast"},"security":[],"parameters":[],"responses":{"200":{"description":"Model output returned successfully.","headers":{"Cache-Control":{"description":"Public cache policy.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["model","as_of_year","coefficients","evaluation","caveat","methodology","sources"],"properties":{"model":{"type":"string","description":"Published model key."},"as_of_year":{"type":"integer","description":"Coefficient build year."},"coefficients":{"type":"array","minItems":1,"description":"Published fitted coefficients and standardization parameters.","items":{"type":"object","additionalProperties":false,"required":["feature","coefficient","mean","sd"],"properties":{"feature":{"type":"string","description":"Stable feature key."},"coefficient":{"type":"number","description":"Fitted logistic coefficient."},"mean":{"type":["number","null"],"description":"Training-sample standardization mean, null for the intercept."},"sd":{"type":["number","null"],"description":"Training-sample standard deviation, null for the intercept."}}}},"evaluation":{"type":"object","additionalProperties":false,"required":["test_observations","failures","auc","recall_top_one_percent","recall_top_five_percent"],"properties":{"test_observations":{"type":"integer","description":"Out-of-sample institution-quarters."},"failures":{"type":"integer","description":"Failures in the test observations."},"auc":{"type":"number","minimum":0,"maximum":1,"description":"Pooled out-of-sample ROC AUC."},"recall_top_one_percent":{"type":"number","minimum":0,"maximum":1,"description":"Failure recall within the top one percent of scores."},"recall_top_five_percent":{"type":"number","minimum":0,"maximum":1,"description":"Failure recall within the top five percent of scores."}}},"caveat":{"type":"string","description":"Required interpretation and model-limit warning."},"methodology":{"type":"string","format":"uri-reference","description":"FinObservatory methodology page."},"sources":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["label","url"],"properties":{"label":{"type":"string","description":"Source name."},"url":{"type":"string","format":"uri","description":"Publisher or source landing page."}}},"description":"Attribution for the inputs used to derive this output."}}},"example":{"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"}]}}}},"400":{"description":"Missing, invalid or unrecognised query parameter.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Stable human-readable error."},"links":{"type":"object","additionalProperties":false,"required":["documentation","openapi"],"properties":{"documentation":{"type":"string","format":"uri-reference"},"openapi":{"type":"string","format":"uri-reference"}}}}},"example":{"error":"invalid query parameter"}}}},"503":{"description":"The model output query is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Stable human-readable error."},"links":{"type":"object","additionalProperties":false,"required":["documentation","openapi"],"properties":{"documentation":{"type":"string","format":"uri-reference"},"openapi":{"type":"string","format":"uri-reference"}}}}},"example":{"error":"model output unavailable"}}}}},"x-finobservatory-kind":"parameters","x-finobservatory-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.","x-finobservatory-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"}]}},"/api/v1/models/sovereign-stress/parameters":{"get":{"operationId":"getSovereignStressParameters","tags":["Parameters"],"summary":"Sovereign-stress coefficients and aggregate evaluations","description":"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.","externalDocs":{"description":"Methodology","url":"https://finobservatory.org/sovereign/stress"},"security":[],"parameters":[],"responses":{"200":{"description":"Model output returned successfully.","headers":{"Cache-Control":{"description":"Public cache policy.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["coefficients","evaluation","caveat","methodology","sources"],"properties":{"coefficients":{"type":"array","minItems":1,"description":"Published fitted coefficients, without source feature values.","items":{"type":"object","additionalProperties":false,"required":["feature","coefficient"],"properties":{"feature":{"type":"string","description":"Stable feature key."},"coefficient":{"type":"number","description":"Fitted logistic coefficient."}}}},"evaluation":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"object","additionalProperties":false,"required":["scope","test_observations","positive_events","model_auc","benchmark_auc"],"properties":{"scope":{"type":"string","enum":["pooled","natural_experiment"],"description":"Published evaluation design."},"test_observations":{"type":"integer","description":"Observations in the evaluation."},"positive_events":{"type":"integer","description":"Sovereign credit events in the evaluation."},"model_auc":{"type":"number","minimum":0,"maximum":1,"description":"Model ROC AUC."},"benchmark_auc":{"type":"number","minimum":0,"maximum":1,"description":"Debt-to-GDP benchmark ROC AUC."}}},"description":"Pooled walk-forward and natural-experiment evaluations."},"caveat":{"type":"string","description":"Required interpretation and model-limit warning."},"methodology":{"type":"string","format":"uri-reference","description":"FinObservatory methodology page."},"sources":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["label","url"],"properties":{"label":{"type":"string","description":"Source name."},"url":{"type":"string","format":"uri","description":"Publisher or source landing page."}}},"description":"Attribution for the inputs used to derive this output."}}},"example":{"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/"}]}}}},"400":{"description":"Missing, invalid or unrecognised query parameter.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Stable human-readable error."},"links":{"type":"object","additionalProperties":false,"required":["documentation","openapi"],"properties":{"documentation":{"type":"string","format":"uri-reference"},"openapi":{"type":"string","format":"uri-reference"}}}}},"example":{"error":"invalid query parameter"}}}},"503":{"description":"The model output query is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Stable human-readable error."},"links":{"type":"object","additionalProperties":false,"required":["documentation","openapi"],"properties":{"documentation":{"type":"string","format":"uri-reference"},"openapi":{"type":"string","format":"uri-reference"}}}}},"example":{"error":"model output unavailable"}}}}},"x-finobservatory-kind":"parameters","x-finobservatory-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.","x-finobservatory-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/"}]}},"/api/v1/scores/crisis-early-warning":{"get":{"operationId":"getCrisisEarlyWarningScore","tags":["Scores"],"summary":"One requested country banking-crisis early-warning score","description":"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.","externalDocs":{"description":"Methodology","url":"https://finobservatory.org/crises/early-warning"},"security":[],"parameters":[{"in":"query","name":"iso3","required":true,"description":"Uppercase ISO 3166-1 alpha-3 country code.","schema":{"type":"string","pattern":"^[A-Z]{3}$","minLength":3,"maxLength":3},"example":"USA"}],"responses":{"200":{"description":"Model output returned successfully.","headers":{"Cache-Control":{"description":"Public cache policy.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["entity","as_of_year","features_through_year","score","model_version","data_vintage","evaluation","caveat","methodology","sources"],"properties":{"entity":{"type":"object","additionalProperties":false,"required":["iso3"],"properties":{"iso3":{"type":"string","pattern":"^[A-Z]{3}$","description":"Requested ISO 3166-1 alpha-3 code."}},"description":"Requested entity identifier only."},"as_of_year":{"type":"integer","description":"Year assigned to the score."},"features_through_year":{"type":"integer","description":"Latest year of source features used by the score."},"score":{"type":"object","additionalProperties":false,"required":["p_onset_next_three_years","decile"],"properties":{"p_onset_next_three_years":{"type":"number","minimum":0,"maximum":1,"description":"Modelled probability of a banking-crisis onset in the next three years."},"decile":{"type":"integer","minimum":1,"maximum":10,"description":"Within-vintage score decile."}}},"model_version":{"type":"string","description":"Published model version."},"data_vintage":{"type":"string","description":"Input vintages recorded by the model build."},"evaluation":{"type":"object","additionalProperties":false,"required":["test_observations","positive_events","model_auc","benchmark_auc"],"properties":{"test_observations":{"type":"integer","description":"Out-of-sample test country-years."},"positive_events":{"type":"integer","description":"Crisis onsets in the test observations."},"model_auc":{"type":"number","minimum":0,"maximum":1,"description":"Pooled out-of-sample ROC AUC."},"benchmark_auc":{"type":"number","minimum":0,"maximum":1,"description":"BIS credit-gap benchmark ROC AUC."}}},"caveat":{"type":"string","description":"Required interpretation and model-limit warning."},"methodology":{"type":"string","format":"uri-reference","description":"FinObservatory methodology page."},"sources":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["label","url"],"properties":{"label":{"type":"string","description":"Source name."},"url":{"type":"string","format":"uri","description":"Publisher or source landing page."}}},"description":"Attribution for the inputs used to derive this output."}}},"example":{"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/"}]}}}},"400":{"description":"Missing, invalid or unrecognised query parameter.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Stable human-readable error."},"links":{"type":"object","additionalProperties":false,"required":["documentation","openapi"],"properties":{"documentation":{"type":"string","format":"uri-reference"},"openapi":{"type":"string","format":"uri-reference"}}}}},"example":{"error":"invalid query parameter"}}}},"404":{"description":"No score exists for the requested identifier in the current output vintage.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Stable human-readable error."},"links":{"type":"object","additionalProperties":false,"required":["documentation","openapi"],"properties":{"documentation":{"type":"string","format":"uri-reference"},"openapi":{"type":"string","format":"uri-reference"}}}}},"example":{"error":"score not found"}}}},"503":{"description":"The model output query is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Stable human-readable error."},"links":{"type":"object","additionalProperties":false,"required":["documentation","openapi"],"properties":{"documentation":{"type":"string","format":"uri-reference"},"openapi":{"type":"string","format":"uri-reference"}}}}},"example":{"error":"model output unavailable"}}}}},"x-finobservatory-kind":"score","x-finobservatory-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.","x-finobservatory-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/"}]}},"/api/v1/scores/bank-failure-nowcast":{"get":{"operationId":"getBankFailureNowcastScore","tags":["Scores"],"summary":"One requested institution bank-failure nowcast score","description":"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.","externalDocs":{"description":"Methodology","url":"https://finobservatory.org/banks/nowcast"},"security":[],"parameters":[{"in":"query","name":"cert","required":true,"description":"Positive FDIC certificate number.","schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"example":628}],"responses":{"200":{"description":"Model output returned successfully.","headers":{"Cache-Control":{"description":"Public cache policy.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["entity","as_of","model","score","evaluation","caveat","methodology","sources"],"properties":{"entity":{"type":"object","additionalProperties":false,"required":["cert"],"properties":{"cert":{"type":"integer","minimum":1,"description":"Requested FDIC certificate number."}},"description":"Requested entity identifier only."},"as_of":{"type":"string","format":"date","description":"Call-report date assigned to the score."},"model":{"type":"string","description":"Published model key."},"score":{"type":"object","additionalProperties":false,"required":["modelled_p_fail_four_quarters","vulnerability_percentile"],"properties":{"modelled_p_fail_four_quarters":{"type":"number","minimum":0,"maximum":1,"description":"Modelled probability of failure within four quarters."},"vulnerability_percentile":{"type":"number","minimum":0,"maximum":100,"description":"Within-vintage vulnerability percentile."}}},"evaluation":{"type":"object","additionalProperties":false,"required":["test_observations","failures","auc","recall_top_one_percent","recall_top_five_percent"],"properties":{"test_observations":{"type":"integer","description":"Out-of-sample institution-quarters."},"failures":{"type":"integer","description":"Failures in the test observations."},"auc":{"type":"number","minimum":0,"maximum":1,"description":"Pooled out-of-sample ROC AUC."},"recall_top_one_percent":{"type":"number","minimum":0,"maximum":1,"description":"Failure recall within the top one percent of scores."},"recall_top_five_percent":{"type":"number","minimum":0,"maximum":1,"description":"Failure recall within the top five percent of scores."}}},"caveat":{"type":"string","description":"Required interpretation and model-limit warning."},"methodology":{"type":"string","format":"uri-reference","description":"FinObservatory methodology page."},"sources":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["label","url"],"properties":{"label":{"type":"string","description":"Source name."},"url":{"type":"string","format":"uri","description":"Publisher or source landing page."}}},"description":"Attribution for the inputs used to derive this output."}}},"example":{"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"}]}}}},"400":{"description":"Missing, invalid or unrecognised query parameter.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Stable human-readable error."},"links":{"type":"object","additionalProperties":false,"required":["documentation","openapi"],"properties":{"documentation":{"type":"string","format":"uri-reference"},"openapi":{"type":"string","format":"uri-reference"}}}}},"example":{"error":"invalid query parameter"}}}},"404":{"description":"No score exists for the requested identifier in the current output vintage.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Stable human-readable error."},"links":{"type":"object","additionalProperties":false,"required":["documentation","openapi"],"properties":{"documentation":{"type":"string","format":"uri-reference"},"openapi":{"type":"string","format":"uri-reference"}}}}},"example":{"error":"score not found"}}}},"503":{"description":"The model output query is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Stable human-readable error."},"links":{"type":"object","additionalProperties":false,"required":["documentation","openapi"],"properties":{"documentation":{"type":"string","format":"uri-reference"},"openapi":{"type":"string","format":"uri-reference"}}}}},"example":{"error":"model output unavailable"}}}}},"x-finobservatory-kind":"score","x-finobservatory-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.","x-finobservatory-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"}]}},"/api/v1/scores/sovereign-stress":{"get":{"operationId":"getSovereignStressScore","tags":["Scores"],"summary":"One requested country sovereign-stress score","description":"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.","externalDocs":{"description":"Methodology","url":"https://finobservatory.org/sovereign/stress"},"security":[],"parameters":[{"in":"query","name":"iso3","required":true,"description":"Uppercase ISO 3166-1 alpha-3 country code.","schema":{"type":"string","pattern":"^[A-Z]{3}$","minLength":3,"maxLength":3},"example":"USA"}],"responses":{"200":{"description":"Model output returned successfully.","headers":{"Cache-Control":{"description":"Public cache policy.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["entity","as_of_year","score","evaluation","caveat","methodology","sources"],"properties":{"entity":{"type":"object","additionalProperties":false,"required":["iso3"],"properties":{"iso3":{"type":"string","pattern":"^[A-Z]{3}$","description":"Requested ISO 3166-1 alpha-3 code."}},"description":"Requested entity identifier only."},"as_of_year":{"type":"integer","description":"Year assigned to the score."},"score":{"type":"object","additionalProperties":false,"required":["modelled_p_credit_event_three_years","stress_percentile"],"properties":{"modelled_p_credit_event_three_years":{"type":"number","minimum":0,"maximum":1,"description":"Modelled probability of a sovereign credit event within three years."},"stress_percentile":{"type":"number","minimum":0,"maximum":100,"description":"Within-vintage stress percentile."}}},"evaluation":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"object","additionalProperties":false,"required":["scope","test_observations","positive_events","model_auc","benchmark_auc"],"properties":{"scope":{"type":"string","enum":["pooled","natural_experiment"],"description":"Published evaluation design."},"test_observations":{"type":"integer","description":"Observations in the evaluation."},"positive_events":{"type":"integer","description":"Sovereign credit events in the evaluation."},"model_auc":{"type":"number","minimum":0,"maximum":1,"description":"Model ROC AUC."},"benchmark_auc":{"type":"number","minimum":0,"maximum":1,"description":"Debt-to-GDP benchmark ROC AUC."}}},"description":"Pooled walk-forward and natural-experiment evaluations."},"caveat":{"type":"string","description":"Required interpretation and model-limit warning."},"methodology":{"type":"string","format":"uri-reference","description":"FinObservatory methodology page."},"sources":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["label","url"],"properties":{"label":{"type":"string","description":"Source name."},"url":{"type":"string","format":"uri","description":"Publisher or source landing page."}}},"description":"Attribution for the inputs used to derive this output."}}},"example":{"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/"}]}}}},"400":{"description":"Missing, invalid or unrecognised query parameter.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Stable human-readable error."},"links":{"type":"object","additionalProperties":false,"required":["documentation","openapi"],"properties":{"documentation":{"type":"string","format":"uri-reference"},"openapi":{"type":"string","format":"uri-reference"}}}}},"example":{"error":"invalid query parameter"}}}},"404":{"description":"No score exists for the requested identifier in the current output vintage.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Stable human-readable error."},"links":{"type":"object","additionalProperties":false,"required":["documentation","openapi"],"properties":{"documentation":{"type":"string","format":"uri-reference"},"openapi":{"type":"string","format":"uri-reference"}}}}},"example":{"error":"score not found"}}}},"503":{"description":"The model output query is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Stable human-readable error."},"links":{"type":"object","additionalProperties":false,"required":["documentation","openapi"],"properties":{"documentation":{"type":"string","format":"uri-reference"},"openapi":{"type":"string","format":"uri-reference"}}}}},"example":{"error":"model output unavailable"}}}}},"x-finobservatory-kind":"score","x-finobservatory-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.","x-finobservatory-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/"}]}},"/api/v1/indices/financial-conditions":{"get":{"operationId":"getFinancialConditionsIndex","tags":["Indices"],"summary":"FinObservatory financial-conditions index observations","description":"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.","externalDocs":{"description":"Methodology","url":"https://finobservatory.org/conditions/methodology"},"security":[],"parameters":[],"responses":{"200":{"description":"Model output returned successfully.","headers":{"Cache-Control":{"description":"Public cache policy.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["frequency","observations","caveat","methodology","sources"],"properties":{"frequency":{"type":"string","const":"quarterly","description":"Observation frequency."},"observations":{"type":"array","minItems":1,"description":"FinObservatory-created FCI observations only.","items":{"type":"object","additionalProperties":false,"required":["date","value","regime"],"properties":{"date":{"type":"string","format":"date","description":"Quarter-end observation date."},"value":{"type":"number","description":"Standardized financial-conditions index value."},"regime":{"type":"string","description":"Derived conditions regime."}}}},"caveat":{"type":"string","description":"Required interpretation and model-limit warning."},"methodology":{"type":"string","format":"uri-reference","description":"FinObservatory methodology page."},"sources":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["label","url"],"properties":{"label":{"type":"string","description":"Source name."},"url":{"type":"string","format":"uri","description":"Publisher or source landing page."}}},"description":"Attribution for the inputs used to derive this output."}}},"example":{"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"}]}}}},"400":{"description":"Missing, invalid or unrecognised query parameter.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Stable human-readable error."},"links":{"type":"object","additionalProperties":false,"required":["documentation","openapi"],"properties":{"documentation":{"type":"string","format":"uri-reference"},"openapi":{"type":"string","format":"uri-reference"}}}}},"example":{"error":"invalid query parameter"}}}},"503":{"description":"The model output query is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Stable human-readable error."},"links":{"type":"object","additionalProperties":false,"required":["documentation","openapi"],"properties":{"documentation":{"type":"string","format":"uri-reference"},"openapi":{"type":"string","format":"uri-reference"}}}}},"example":{"error":"model output unavailable"}}}}},"x-finobservatory-kind":"index","x-finobservatory-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.","x-finobservatory-sources":[{"label":"Federal Reserve Economic Data","url":"https://fred.stlouisfed.org/"},{"label":"BIS credit statistics","url":"https://www.bis.org/statistics/totcredit.htm"}]}},"/api/v1/indices/fed-tone":{"get":{"operationId":"getFedToneIndex","tags":["Indices"],"summary":"FinObservatory annual Federal Reserve tone index observations","description":"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.","externalDocs":{"description":"Methodology","url":"https://finobservatory.org/library/fomc/tone"},"security":[],"parameters":[],"responses":{"200":{"description":"Model output returned successfully.","headers":{"Cache-Control":{"description":"Public cache policy.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["frequency","observations","null_rule","caveat","methodology","sources"],"properties":{"frequency":{"type":"string","const":"annual","description":"Observation frequency."},"observations":{"type":"array","minItems":1,"description":"Annual net tone observations pooled across document types.","items":{"type":"object","additionalProperties":false,"required":["year","value"],"properties":{"year":{"type":"integer","description":"Calendar year."},"value":{"type":["number","null"],"description":"Net tone, (hawkish matches minus dovish matches) divided by total matches."}}}},"null_rule":{"type":"string","description":"Rule used to preserve thin years as null."},"caveat":{"type":"string","description":"Required interpretation and model-limit warning."},"methodology":{"type":"string","format":"uri-reference","description":"FinObservatory methodology page."},"sources":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["label","url"],"properties":{"label":{"type":"string","description":"Source name."},"url":{"type":"string","format":"uri","description":"Publisher or source landing page."}}},"description":"Attribution for the inputs used to derive this output."}}},"example":{"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"}]}}}},"400":{"description":"Missing, invalid or unrecognised query parameter.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Stable human-readable error."},"links":{"type":"object","additionalProperties":false,"required":["documentation","openapi"],"properties":{"documentation":{"type":"string","format":"uri-reference"},"openapi":{"type":"string","format":"uri-reference"}}}}},"example":{"error":"invalid query parameter"}}}},"503":{"description":"The model output query is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string","description":"Stable human-readable error."},"links":{"type":"object","additionalProperties":false,"required":["documentation","openapi"],"properties":{"documentation":{"type":"string","format":"uri-reference"},"openapi":{"type":"string","format":"uri-reference"}}}}},"example":{"error":"model output unavailable"}}}}},"x-finobservatory-kind":"index","x-finobservatory-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.","x-finobservatory-sources":[{"label":"Federal Reserve historical materials and current releases","url":"https://www.federalreserve.gov/monetarypolicy/fomc_historical.htm"}]}}}}