Scoring API

Overview

The Scoring API exposes real-time machine-learning endpoints for in-session player-targeting decisions. The first available model is the First-User Payer Conversion scorer — designed to drive the Starter Pack popup decision at the 30-minute post-install mark.

Send six behavioural features from a new install's first 30 minutes, get back a calibrated score in [0,1] (an isotonic-calibrated probability the user pays within D1) and a bucket label (top_1pct / top_5pct / top_10pct / rest) for operational thresholding. Firing the popup on top_5pct-or-higher targets the ~6% of installs that convert at ~26% (≈8.8× the base rate).

Authentication

All scoring endpoints require a client-side API key with the scoring:write scope.

Test Mode

Integrate end-to-end before going live with a test key. Test keys carry a pk_test_ prefix; live keys carry pk_live_. A test key hits the same endpoints, the same model, and the same thresholds, with an identical request and response shape. Scores from a test key are tagged and excluded from production analytics and A/B attribution, so sandbox calls never affect your reported numbers. Swap the key string when you go live; nothing else changes.

curl -X POST class="code-string">"https:class="code-commentclass="code-string">">//app.ilara.ai/api/v1/scoring/first-user-conversion/30m" \
  -H class="code-string">"X-API-Key: pk_test_v1_xxx" \
  -H class="code-string">"Content-Type: application/json" \
  -d class="code-string">'{"device_id": "ILARA_TEST_TOP_1PCT"}'
# -> 200, data.bucket == class="code-string">"top_1pct"

First-User Conversion

Predicts the probability that a new install will pay within their first day (D1). Use the bucket label to drive in-session offers like the Starter Pack popup.

curl -X POST class="code-string">"https:class="code-commentclass="code-string">">//api.ilara.ai/v1/scoring/first-user-conversion/30m" \
  -H class="code-string">"X-API-Key: pk_live_v1_xxx" \
  -H class="code-string">"Content-Type: application/json" \
  -d '{
    class="code-string">"device_id": class="code-string">"DCD5D755-E12C-4E3C-9010-CDAE3232B059",
    class="code-string">"loot_distinct_types": 3,
    class="code-string">"sess_duration_total": 500.0,
    class="code-string">"match_avg_fight_time": 45.0,
    class="code-string">"match_wins": 4,
    class="code-string">"install_hour": 14,
    class="code-string">"vpay_count": 2
  }'
# Endpoints: .../30m (in-session) and .../12h (next-session). The bare path 404s.

{
  class="code-string">"success": true,
  class="code-string">"data": {
    class="code-string">"device_id":       class="code-string">"DCD5D755-E12C-4E3C-9010-CDAE3232B059",
    class="code-string">"score":           0.162,
    class="code-string">"bucket":          class="code-string">"top_5pct",
    class="code-string">"model_version":   class="code-string">"a8e08f6f20bc",
    class="code-string">"thresholds_used": {
      class="code-string">"top_1pct":  0.4000,
      class="code-string">"top_5pct":  0.1009,
      class="code-string">"top_10pct": 0.0473
    },
    class="code-string">"scored_at":       class="code-string">"2026-05-20T14:30:00.913Z"
  },
  class="code-string">"error": null,
  class="code-string">"meta":  null
}

Bucket Semantics

Cutoffs are the 90/95/99th percentiles of the served model's calibrated scores on an out-of-time hold-out — i.e. expressed in the same calibrated [0,1] probability space as score. They rotate with each retrain. Always read thresholds_used from the response — don't hardcode the cutoffs. The values below are the 30m model's; the 12h model's cutoffs are higher.

Call Timing

The model is trained on features observed in the user's first 30 minutes post-install. Score at 30 minutes (or at end-of-first-session, whichever fires first) for the calibration the model expects.

At 30 minutes, 81% of users (and 92% of payers) have all 6 fields populated. Scoring earlier than 30 minutes is supported but drops ROC-AUC below 0.75 — only do so if the popup must fire in-FTUE.

Model Card

Headline metrics for the current production artifact:

Field-Definition Gotchas

Six places where a backend-side bug will silently send values that don't match what the model was trained on. Confirm each with your engineering team before integration:

• install_hour must be UTC, not IST or device-local. Off-by-5.5h on every score otherwise.
• sess_duration_total uses the activityduration field on session-END events, not wall-clock elapsed time and not the (start_ts, end_ts) difference. activityduration excludes idle.
• match_wins counts the exact uppercase string "WIN". "Win" and "win" are not matched.
• vpay_count covers ALL virtual-currency events (earns + spends of in-game currency), NOT real-money IAPs. Sending IAP-count instead will yield values ~10× smaller than training.
• loot_distinct_types counts distinct values of _LootcaseType. Use the same enumeration as devtodev exports.
• Omit fields you don't have — send 0 if you must, never null. Pydantic strict-types numerics and 422s on null.

Error Responses

Operational Notes

Next Steps

• Authentication — API key types and the scoring:write scope
• Events API — Track behaviour that feeds future scoring models
• Churn Prediction — Complementary lifecycle modelling