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 '{}'
{
  "$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"
  },
  "actions": [
    {
      "action_id": "string",
      "label": "string",
      "losses": 0,
      "observed_win_rate": 0.1,
      "selections": 0,
      "simulated_expected_rate": 0.1,
      "wins": 0
    }
  ],
  "model": null,
  "ope": {
    "ci_high": 0.1,
    "ci_low": 0.1,
    "dr": 0.1
  },
  "policy": null,
  "scenario": "string",
  "series": [
    {
      "auc": 0.1,
      "best_action_share": 0.1,
      "ci_high": 0.1,
      "ci_low": 0.1,
      "losses": 0,
      "n": 0,
      "nba_reward": 0.1,
      "nba_value": 0.1,
      "ope_dr": 0.1,
      "round": 0,
      "scoring_brier": 0.1,
      "win_rate": 0.1,
      "wins": 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"
}

Stream self-learning simulation rounds as they complete

POST
/builtin-agents/ml/{use_case}/simulate-rounds/stream
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

text/event-stream

application/problem+json

curl -X POST "https://loading/api/v1/builtin-agents/ml/string/simulate-rounds/stream" \  -H "Content-Type: application/json" \  -d '{}'
Empty
{
  "$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"
}

Send-time & channel suggestion: next-best daypart/day-type/channel to contact (P3)

POST
/ml/contact_timing/suggest
AuthorizationBearer <token>

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

In: header

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/ml/contact_timing/suggest" \  -H "Content-Type: application/json" \  -d '{    "channels": [      "string"    ],    "contact_id": "string"  }'
{
  "$schema": "/api/v1/schemas/ContactTimingSuggestResponse.json",
  "action_id": "string",
  "channel": "string",
  "propensity": 0.1,
  "send_bucket": {
    "day_type": "string",
    "daypart": "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"
}

Expected-value ranking: P(convert) × predicted deal value (P1)

POST
/ml/ev
AuthorizationBearer <token>

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

In: header

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/ml/ev" \  -H "Content-Type: application/json" \  -d '{    "features": {      "property1": null,      "property2": null    }  }'
{
  "$schema": "/api/v1/schemas/EvResponseBody.json",
  "expected_value": 0.1,
  "prob_served_from": "string",
  "probability": 0.1,
  "value": 0.1,
  "value_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"
}

Pipeline revenue forecast: Monte Carlo over open-pipeline expected value (P4)

GET
/ml/forecast
AuthorizationBearer <token>

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

In: header

Query Parameters

window_days?integer

Lookback window in days for 'open pipeline' (not yet converted, created within this window). Defaults to the tenant manifest's objective.attribution_window_days, else 90.

Formatint64

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/ml/forecast"
{
  "$schema": "/api/v1/schemas/ForecastResponseBody.json",
  "assumptions": [
    "string"
  ],
  "expected_revenue": 0.1,
  "open_leads": 0,
  "p10": 0.1,
  "p50": 0.1,
  "p90": 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"
}

Human-handoff timing: bandit over {escalate_now, wait_one_day, keep_automated} (P7)

POST
/ml/handoff/suggest
AuthorizationBearer <token>

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

In: header

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/ml/handoff/suggest" \  -H "Content-Type: application/json" \  -d '{    "contact_id": "string",    "context": {      "property1": null,      "property2": null    }  }'
{
  "$schema": "/api/v1/schemas/HandoffSuggestResponse.json",
  "action_id": "string",
  "approval_enqueued": true,
  "approval_id": "string",
  "gated": true,
  "have": 0,
  "needed": 0,
  "propensity": 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"
}

Lookalike prospecting rank: non-converted leads ranked by similarity to the won-deal centroid (P6)

GET
/ml/lookalike/rank
AuthorizationBearer <token>

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

In: header

Query Parameters

limit?integer

Max leads to return. Defaults to 20.

Formatint64

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/ml/lookalike/rank"
{
  "$schema": "/api/v1/schemas/LookalikeRankResponse.json",
  "items": [
    {
      "lead_ref": "string",
      "lookalike_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"
}

Lookalike prospecting score: similarity to the project's won-deal centroid (P6)

POST
/ml/lookalike/score
AuthorizationBearer <token>

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

In: header

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/ml/lookalike/score" \  -H "Content-Type: application/json" \  -d '{}'
{
  "$schema": "/api/v1/schemas/LookalikeScoreResponse.json",
  "centroid_won_profiles": 0,
  "lookalike_score": 0.1,
  "used_cached_dossier": 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"
}

Offer suggestion: bandit over the tenant manifest's offer-type actions, margin-weighted (P7)

POST
/ml/offers/suggest
AuthorizationBearer <token>

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

In: header

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/ml/offers/suggest" \  -H "Content-Type: application/json" \  -d '{    "contact_id": "string"  }'
{
  "$schema": "/api/v1/schemas/OfferSuggestResponse.json",
  "gated": true,
  "have": 0,
  "needed": 0,
  "suggestion": {
    "action_id": "string",
    "channel": "string",
    "cost_hint": 0.1,
    "intrusiveness": "string",
    "label": "string",
    "propensity": 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"
}

Latest computed dead-lead revival queue (P2)

GET
/ml/revival-queue
AuthorizationBearer <token>

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

In: header

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/ml/revival-queue"
{
  "$schema": "/api/v1/schemas/RevivalQueueBody.json",
  "computed_at": "string",
  "items": [
    {
      "agent_id": "string",
      "contact_id": "string",
      "dormancy_days": 0.1,
      "expected_value": 0.1,
      "reason": "string",
      "revival_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"
}

Trigger an on-demand revival-queue sweep for this project (P2)

POST
/ml/revival-queue/compute
AuthorizationBearer <token>

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

In: header

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/ml/revival-queue/compute"
{
  "$schema": "/api/v1/schemas/RevivalQueueBody.json",
  "computed_at": "string",
  "items": [
    {
      "agent_id": "string",
      "contact_id": "string",
      "dormancy_days": 0.1,
      "expected_value": 0.1,
      "reason": "string",
      "revival_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"
}

Generate the Win/Loss Intelligence report (P5)

POST
/ml/winloss/generate
AuthorizationBearer <token>

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

In: header

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/ml/winloss/generate" \  -H "Content-Type: application/json" \  -d '{}'
{
  "$schema": "/api/v1/schemas/WinlossReportResponse.json",
  "cached": true,
  "created_at": "2019-08-24T14:15:22Z",
  "evidence_stats": {
    "attribution_window_days": 0,
    "episodes_included": 0,
    "episodes_truncated": 0,
    "leads_skipped_no_identity": 0,
    "lost_leads": 0,
    "lost_leads_truncated": 0,
    "pack_chars": 0,
    "used_fallback_attribution_window": true,
    "window_days": 0,
    "won_leads": 0,
    "won_leads_truncated": 0
  },
  "project_id": "string",
  "report": {
    "caveats": [
      "string"
    ],
    "objection_taxonomy": [
      {
        "cohort": "string",
        "frequency_hint": "string",
        "objection": "string"
      }
    ],
    "phrases_that_lost": [
      {
        "phrasing": "string",
        "situation": "string"
      }
    ],
    "phrases_that_worked": [
      {
        "phrasing": "string",
        "situation": "string"
      }
    ],
    "recommendations": [
      {
        "detail": "string",
        "expected_impact": "string",
        "title": "string"
      }
    ],
    "stall_points": [
      "string"
    ]
  },
  "report_id": "string",
  "violations": [
    "string"
  ],
  "window_end": "2019-08-24T14:15:22Z",
  "window_start": "2019-08-24T14:15:22Z"
}
{
  "$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"
}

Latest persisted Win/Loss Intelligence report (P5)

GET
/ml/winloss/latest
AuthorizationBearer <token>

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

In: header

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/ml/winloss/latest"
{
  "$schema": "/api/v1/schemas/WinlossReportResponse.json",
  "cached": true,
  "created_at": "2019-08-24T14:15:22Z",
  "evidence_stats": {
    "attribution_window_days": 0,
    "episodes_included": 0,
    "episodes_truncated": 0,
    "leads_skipped_no_identity": 0,
    "lost_leads": 0,
    "lost_leads_truncated": 0,
    "pack_chars": 0,
    "used_fallback_attribution_window": true,
    "window_days": 0,
    "won_leads": 0,
    "won_leads_truncated": 0
  },
  "project_id": "string",
  "report": {
    "caveats": [
      "string"
    ],
    "objection_taxonomy": [
      {
        "cohort": "string",
        "frequency_hint": "string",
        "objection": "string"
      }
    ],
    "phrases_that_lost": [
      {
        "phrasing": "string",
        "situation": "string"
      }
    ],
    "phrases_that_worked": [
      {
        "phrasing": "string",
        "situation": "string"
      }
    ],
    "recommendations": [
      {
        "detail": "string",
        "expected_impact": "string",
        "title": "string"
      }
    ],
    "stall_points": [
      "string"
    ]
  },
  "report_id": "string",
  "violations": [
    "string"
  ],
  "window_end": "2019-08-24T14:15:22Z",
  "window_start": "2019-08-24T14:15:22Z"
}
{
  "$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"
}