Model Scoring & Reset

Score individual customers with a model, and reset learned model state for retraining.

POST /api/v1/algorithm-models//score

Score a single customer using a trained model. Pass customer attributes and receive a score with explanatory details.

Path Parameters

Parameter	Type	Description
id	string	Algorithm model ID

Request Body

Field	Type	Required	Description
attributes	object	No	Customer attributes to score (e.g., { "age": 35, "tenure_months": 24 })

Example

curl -X POST https://playground.kaireonai.com/api/v1/algorithm-models/model_001/score \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{
    "attributes": {
      "age": 35,
      "credit_score": 740,
      "tenure_months": 24,
      "segment": "high_value"
    }
  }'

Response

The score endpoint returns a result whose shape varies by model type. The common fields are:

{
  "score": 0.82
}

Additional fields may be present depending on model type:

Field	Type	Present for	Description
score	number	All types	The computed score (0-1)
confidence	number	bayesian	Confidence level of the score
explanations	array	scorecard, bayesian, gradient_boosted, thompson_bandit, epsilon_greedy	Per-predictor or per-offer score breakdowns

The response does not include modelId, modelType, or predictorContributions at the top level. Those fields are only returned by the /score-offer-set endpoint.

Error Codes

Code	Reason
404	Model not found

Roles

any authenticated

---

POST /api/v1/algorithm-models//reset-learning

Reset a model’s learned state back to its initial configuration. Creates a version snapshot before resetting for rollback capability. The model status is set to draft after reset.

Path Parameters

Parameter	Type	Description
id	string	Algorithm model ID

Behavior

1. Snapshot: Creates a model-version record with the current state (config, metrics, predictors)
2. Reset: Clears learned state, metrics, and training history
3. Status: Sets model to draft (requires retraining)

Error Codes

Code	Reason
400	Model is a scorecard type (scorecards have no learned state)
404	Model not found

Response

Returns the updated model object with cleared state.

{
  "id": "model_001",
  "name": "Propensity Model",
  "modelType": "bayesian",
  "status": "draft",
  "version": 3,
  "trainingSamples": 0,
  "lastTrainedAt": null,
  "metrics": {}
}

This operation clears all learned parameters. The model must be retrained before it can be used for scoring in production flows. A version snapshot is created automatically for rollback.

Roles

admin, editor

See also: Algorithm Models | Model Governance