Skip to main content
Api

M L

Record a realized outcome — improves the scoring model + the bandit in one call

POST
/builtin-agents/ml/{use_case}/feedback
AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

use_case*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/builtin-agents/ml/string/feedback" \  -H "Content-Type: application/json" \  -d '{    "converted": true  }'
{
  "$schema": "/api/v1/schemas/FeedbackResponse.json",
  "bandit_error": "string",
  "bandit_n": 0,
  "bandit_updated": true,
  "converted": true,
  "message": "string",
  "ok": true,
  "outcome_recorded": true,
  "use_case": "string"
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Next-best-action over a per-tenant variable action set

POST
/builtin-agents/ml/{use_case}/nba/decide
AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

use_case*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/builtin-agents/ml/string/nba/decide" \  -H "Content-Type: application/json" \  -d '{    "actions": [      {        "id": "string"      }    ]  }'
{
  "$schema": "/api/v1/schemas/DecideResponse.json",
  "action_id": "string",
  "explore": true,
  "model_n": 0,
  "propensity": 0.1,
  "scores": [
    {
      "action_id": "string",
      "propensity": 0.1,
      "score": 0.1
    }
  ]
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Teach the bandit a realized (action, propensity, reward)

POST
/builtin-agents/ml/{use_case}/nba/learn
AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

use_case*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/builtin-agents/ml/string/nba/learn" \  -H "Content-Type: application/json" \  -d '{    "action_id": "string",    "reward": 0.1  }'
{
  "$schema": "/api/v1/schemas/LearnResponse.json",
  "n": 0,
  "ok": true
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Off-policy evaluation (IPS / SNIPS / doubly-robust + CI)

POST
/builtin-agents/ml/{use_case}/ope/evaluate
AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

use_case*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/builtin-agents/ml/string/ope/evaluate" \  -H "Content-Type: application/json" \  -d '{    "logged": [      {        "action_id": "string",        "propensity": 0.1,        "reward": 0.1      }    ]  }'
{
  "$schema": "/api/v1/schemas/OPEResponse.json",
  "ci_high": 0.1,
  "ci_low": 0.1,
  "dr": 0.1,
  "ess": 0.1,
  "estimator_ci": "string",
  "ips": 0.1,
  "n": 0,
  "snips": 0.1
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Score a record with the per-tenant model (falls back to the global prior)

POST
/builtin-agents/ml/{use_case}/scoring/predict
AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

use_case*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/builtin-agents/ml/string/scoring/predict" \  -H "Content-Type: application/json" \  -d '{    "features": {      "property1": null,      "property2": null    }  }'
{
  "$schema": "/api/v1/schemas/PredictResponse.json",
  "calibration_method": "string",
  "model_version": 0,
  "raw": 0.1,
  "score": 0.1,
  "served_from": "string"
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Train the per-tenant scoring model (CatBoost + Optuna, calibrated)

POST
/builtin-agents/ml/{use_case}/scoring/train
AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

use_case*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/builtin-agents/ml/string/scoring/train" \  -H "Content-Type: application/json" \  -d '{    "rows": [      {        "features": {          "property1": null,          "property2": null        },        "label": 0      }    ]  }'
{
  "$schema": "/api/v1/schemas/TrainResponse.json",
  "auc": 0.1,
  "best_params": {
    "property1": null,
    "property2": null
  },
  "brier": 0.1,
  "brier_baseline": 0.1,
  "brier_uncalibrated": 0.1,
  "calibration_method": "string",
  "ece": 0.1,
  "importances": [
    {
      "gain": 0.1,
      "name": "string"
    }
  ],
  "logloss": 0.1,
  "model_version": 0,
  "n": 0,
  "trials": 0
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Single-call self-learning simulation (train → decide → learn → OPE over rounds)

POST
/builtin-agents/ml/{use_case}/simulate-rounds
AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

use_case*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/builtin-agents/ml/string/simulate-rounds" \  -H "Content-Type: application/json" \  -d '{}'
{
  "$schema": "/api/v1/schemas/SimulateRoundsResponse.json",
  "action_labels": {
    "property1": "string",
    "property2": "string"
  },
  "model": null,
  "ope": {
    "ci_high": 0.1,
    "ci_low": 0.1,
    "dr": 0.1
  },
  "policy": null,
  "scenario": "string",
  "series": [
    {
      "auc": 0.1,
      "ci_high": 0.1,
      "ci_low": 0.1,
      "n": 0,
      "nba_reward": 0.1,
      "nba_value": 0.1,
      "ope_dr": 0.1,
      "round": 0
    }
  ]
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}