DocumentationAPI Reference

Getting Started

Quickstart

Go from a trained scorecard to a live scoring API in six steps. This guide assumes you already have a Calibr account and the desktop app installed.

1

Build a scorecard in Calibr Desktop

Open the Calibr desktop app, create a new project, and work through the modeling workflow: upload data, run EDA, configure binning, train a logistic regression, and generate a scorecard. The scorecard captures your model as a points-based system ready for deployment.

2

Configure risk grades in Cutoff Simulator

Navigate to the Scorecard tab and open the Cutoff Simulator. Define risk grade thresholds that map score ranges to letter grades (e.g., A through E). These grades will be included in every scoring response.

3

Deploy to the Scoring API

In the Scaling Configuration panel, click “Deploy to API”. Calibr packages your scorecard as a CalibrScorecardSpec v1 document and uploads it to the scoring service. You will receive a scorecard ID (e.g., sc_01HXYZ).

4

Create an API key

Go to the web dashboard at app.calibr.dev and navigate to Settings → API Keys. Click “Create Key”, give it a name, and select the score scope. Copy the key — it will only be shown once.

You can also create keys from the desktop app under Settings → API.

bash
# Your key will look like this: sk_live_abc123def456ghi789
5

Score your first applicant

Send a scoring request with the applicant's features. The variable names must match those defined in your scorecard.

curl -X POST https://api.calibr.dev/api/v1/score \ -H "Authorization: Bearer sk_live_abc123def456ghi789" \ -H "Content-Type: application/json" \ -d '{ "scorecard_id": "sc_01HXYZ", "applicant": { "monthly_income": 5500, "employment_length": 36, "debt_to_income": 0.28, "home_ownership": "MORTGAGE", "purpose": "debt_consolidation" } }'
6

Check the results

The API returns a scoring response with the total score, probability of default, risk grade, and a breakdown of points per variable:

json
{ "score": 687, "pd": 0.034, "risk_grade": "B", "details": { "base_points": 500, "variables": { "monthly_income": { "bin": "(4000, 6000]", "points": 52 }, "employment_length": { "bin": "(24, 48]", "points": 38 }, "debt_to_income": { "bin": "(0.2, 0.35]", "points": 27 }, "home_ownership": { "bin": "MORTGAGE", "points": 41 }, "purpose": { "bin": "debt_consolidation", "points": 29 } } }, "model_version": "v1", "scored_at": "2026-03-26T14:32:01Z" }

Visit the web dashboard to see scoring history, volume charts, and grade distribution for your deployed scorecard.

Next Steps

  • Read the Authentication guide to learn about token refresh and API key scopes
  • Explore the How Scoring Works guide for details on bin matching and PD calculation
  • Set up Champion / Challenger testing to compare model versions in production
  • Review Rate Limits before going to production