API Reference

Base URL: https://api.example.com
Authentication: X-API-Key header on all endpoints except /health.

Train a model

POST/train

Train a new classifier from labeled data.

Request body

Field	Type	Required	Description
`model_id`	string	Yes	Unique identifier for the model
`X`	float[][]	Yes	Training samples, shape (n_samples, n_features)
`y`	string[]	Yes	Class labels, length n_samples
`rule_purity`	float	No	Minimum rule purity. Default: `1.0`
`online_correction`	bool	No	Apply online correction. Default: `true`
`recover_undetermined`	bool	No	Recover UNDETERMINED via evidence escalation. Default: `true`

Response

{
  "model_id": "my_model",
  "n_classes": 3,
  "classes": ["setosa", "versicolor", "virginica"],
  "status": "trained"
}

Errors

Status	Cause
`401`	Invalid API key
`429`	Model limit or training sample limit exceeded

Predict

POST/predict

Get a typed prediction for one or more samples.

Request body

Field	Type	Required	Description
`model_id`	string	Yes	Model to use for prediction
`X`	float[] or float[][]	Yes	Single sample (1D) or batch (2D)
`cost`	float	No	Cost ratio for action recommendation. Omit for no action field.

Response (single sample)

{
  "type": "CLASS",
  "class_": "setosa",
  "alternatives": [],
  "margin": 4,
  "support": 7,
  "total_evidence": 9,
  "action": "commit",
  "evidence": {
    "setosa":     {"support": 7, "against": 0},
    "versicolor": {"support": 3, "against": 4},
    "virginica":  {"support": 2, "against": 5}
  }
}

Response (batch)

Returns a JSON array of prediction objects, one per input sample.

Response fields

Field	Type	Description
`type`	string	`CLASS`, `POSSIBILITIES`, or `UNDETERMINED`
`class_`	string \| null	Committed class (only when type is CLASS)
`alternatives`	string[]	Possible classes (only when type is POSSIBILITIES)
`margin`	int	Evidence gap between top class and runner-up
`support`	int	Evidence count for committed class
`total_evidence`	int	Total rules that fired
`action`	string \| null	`commit`, `narrow`, or `abstain` (only if cost provided)
`evidence`	object \| null	Per-class support/against counts

Errors

Status	Cause
`401`	Invalid API key
`404`	Model not found
`429`	Monthly prediction limit exceeded

List models

GET/models

List all models for the authenticated user.

{
  "models": [
    {
      "model_id": "credit_risk_v2",
      "n_classes": 2,
      "classes": ["approve", "deny"],
      "created_at": "2026-03-15T14:30:00Z"
    }
  ]
}

Delete a model

DELETE/models/{model_id}

Delete a trained model and free the model slot.

{"status": "deleted", "model_id": "old_model"}

Check usage

GET/billing/usage

Get current month's usage and limits for the authenticated user.

{
  "tier": "free",
  "month": "2026-03",
  "predictions_used": 1247,
  "predictions_limit": 50000,
  "trains_used": 3
}

Health check

GET/health

No authentication required.

{"status": "ok", "version": "0.1.0"}

Rate limits

Tier	Predictions / month	Models	Max training samples
Free	50,000	5	50,000
Team ($49/mo)	500,000	20	100,000
Business ($199/mo)	2,000,000	100	1,000,000
Enterprise	Unlimited	Unlimited	Unlimited

When a limit is exceeded, the API returns 429 Too Many Requests with a message indicating which limit was hit and how to upgrade.