Sparkient Docs

Trigger model training

Start training an ML policy for a decision type. Accepts optional quality-gate, augmentation, and tuning settings. Every request runs the complete task-specific pipeline. Returns 202 after Cloud Run accepts the job. If dispatch fails, returns 503 with the durable policy ID and status. Poll GET /policies/{policy_id} for subsequent status.

Quality gate: Set target_f1 to auto-deploy only when the target is met. If the target is not met, the policy stays in 'trained' status for manual review.

Omit the request body to use full-pipeline defaults with no quality gate.

Authorization

AuthorizationBearer <token>

A 64-character hexadecimal Sparkient API key. Create a key in the Sparkient dashboard and send it as Authorization: Bearer YOUR_API_KEY.

In: header

Path Parameters

decision_type_id*Decision Type Id

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Training configuration sent as the request body to POST /train.

The task-specific text and classifier pipeline is mandatory. Callers may configure augmentation, tuning, and deployment around that complete pipeline.

Example::

{    "target_f1": 0.85,    "auto_deploy": true}

target_f1?|

Minimum macro-F1 required for auto-deployment. If set, the policy will only auto-deploy when this threshold is met. If None, no quality gate is applied.

auto_deploy?Auto Deploy

If True and target_f1 is met (or no target set), automatically deploy the policy after training completes.

Defaulttrue

augment?|

Enable/disable data augmentation. None uses the full-pipeline default (enabled).

augment_target_size?|

Target total dataset size after augmentation (max 5,000). Default: options × 300 (e.g. 4 options → 1,200). Higher values increase coverage and runtime but do not guarantee better held-out quality.

auto_generate?Auto Generate

Explicitly allow generation of extra synthetic examples when the submitted dataset is smaller than the evaluation target. Disabled by default; training never generates hidden data.

Defaultfalse

tune_hyperparams?|

Enable/disable automated HP tuning. None uses the full-pipeline default (enabled).

n_tuning_trials?N Tuning Trials

Number of hyperparameter tuning trials.

Range5 <= value <= 100

Default20

escalation_threshold?Escalation Threshold

Confidence threshold below which decisions escalate to the LLM fallback. Used for escalation rate estimation.

Range0.5 <= value <= 0.95

Default0.7

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/decision-types/497f6eca-6276-4993-bfeb-53cbbbba6f08/train" \  -H "Content-Type: application/json" \  -d '{    "auto_deploy": true,    "target_f1": 0.85  }'

null

Check training readiness

Check whether a decision type has enough labelled examples to start training. Returns per-option counts and any issues that need to be addressed.

Authorization

AuthorizationBearer <token>

A 64-character hexadecimal Sparkient API key. Create a key in the Sparkient dashboard and send it as Authorization: Bearer YOUR_API_KEY.

In: header

Path Parameters

decision_type_id*Decision Type Id

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/decision-types/497f6eca-6276-4993-bfeb-53cbbbba6f08/training-readiness"

{  "ready": true,  "total_examples": 0,  "labelled_examples": 0,  "per_option": {    "property1": 0,    "property2": 0  },  "options": [    "string"  ],  "min_total": 38,  "min_per_option": 38,  "issues": [    "string"  ]}

List policies

List all policies for a decision type, ordered by creation date (newest first). Includes status, summary metrics, and quality gate status.

Authorization

AuthorizationBearer <token>

A 64-character hexadecimal Sparkient API key. Create a key in the Sparkient dashboard and send it as Authorization: Bearer YOUR_API_KEY.

In: header

Path Parameters

decision_type_id*Decision Type Id

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/decision-types/497f6eca-6276-4993-bfeb-53cbbbba6f08/policies"

[  {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "decision_type_id": "5387d3c6-2309-41c6-9fe0-78021326d726",    "version": 0,    "policy_type": "string",    "status": "string",    "deployed": true,    "auto_deployed": false,    "accuracy": 0,    "macro_f1": 0,    "train_size": 0,    "quality_gate_met": true,    "augmentation_status": "string",    "created_at": "2019-08-24T14:15:22Z"  }]

Get policy detail

Get full detail for a specific policy, including rich metrics (per-class breakdown, confusion matrix, escalation estimate, latency estimates) and the training configuration that was used.

Includes stale training detection: an attempt with a dead heartbeat is fenced as 'stopping' until its exact Cloud Run execution is confirmed terminal, while a pre-start job retains the longer lifecycle allowance.

Authorization

AuthorizationBearer <token>

A 64-character hexadecimal Sparkient API key. Create a key in the Sparkient dashboard and send it as Authorization: Bearer YOUR_API_KEY.

In: header

Path Parameters

decision_type_id*Decision Type Id

Formatuuid

policy_id*Policy Id

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/decision-types/497f6eca-6276-4993-bfeb-53cbbbba6f08/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "decision_type_id": "5387d3c6-2309-41c6-9fe0-78021326d726",  "version": 0,  "policy_type": "string",  "status": "string",  "deployed": true,  "auto_deployed": false,  "training_config": {    "augment": true,    "augment_target_size": 0,    "auto_generate": false,    "tune_hyperparams": true,    "n_tuning_trials": 0,    "target_f1": 0,    "auto_deploy": true,    "escalation_threshold": 0  },  "metrics": {    "accuracy": 0,    "macro_f1": 0,    "macro_precision": 0,    "macro_recall": 0,    "per_class": {      "property1": {        "property1": 0,        "property2": 0      },      "property2": {        "property1": 0,        "property2": 0      }    },    "confusion_matrix": [      [        0      ]    ],    "confusion_labels": [      "string"    ],    "train_size": 0,    "test_size": 0,    "feature_count": 0,    "escalation_estimate": 0,    "latency_estimate_p50_ms": 0,    "latency_estimate_p95_ms": 0,    "augmentation": {      "status": "string",      "original_count": 0,      "augmented_count": 0,      "target_size": 0,      "failure_reason": "string",      "per_class_counts": {        "property1": 0,        "property2": 0      }    },    "auto_generation": {      "status": "string",      "generated_count": 0,      "original_count": 0,      "minimum_required": 0    }  },  "quality_gate_met": true,  "target_f1": 0,  "error": "string",  "current_attempt_id": "0a9f3a6a-6768-44e1-9b4d-bcf1a1fbbb53",  "execution_name": "string",  "last_heartbeat_at": "2019-08-24T14:15:22Z",  "last_training_error": "string",  "created_at": "2019-08-24T14:15:22Z"}

Deploy a policy

Deploy a policy (set as active for inference). Deactivates all other policies for the same decision type. Only policies with status 'trained' or 'deployed' can be deployed.

Authorization

AuthorizationBearer <token>

A 64-character hexadecimal Sparkient API key. Create a key in the Sparkient dashboard and send it as Authorization: Bearer YOUR_API_KEY.

In: header

Path Parameters

decision_type_id*Decision Type Id

Formatuuid

policy_id*Policy Id

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/decision-types/497f6eca-6276-4993-bfeb-53cbbbba6f08/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/deploy"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "decision_type_id": "5387d3c6-2309-41c6-9fe0-78021326d726",  "version": 0,  "policy_type": "string",  "status": "string",  "deployed": true,  "auto_deployed": false,  "training_config": {    "augment": true,    "augment_target_size": 0,    "auto_generate": false,    "tune_hyperparams": true,    "n_tuning_trials": 0,    "target_f1": 0,    "auto_deploy": true,    "escalation_threshold": 0  },  "metrics": {    "accuracy": 0,    "macro_f1": 0,    "macro_precision": 0,    "macro_recall": 0,    "per_class": {      "property1": {        "property1": 0,        "property2": 0      },      "property2": {        "property1": 0,        "property2": 0      }    },    "confusion_matrix": [      [        0      ]    ],    "confusion_labels": [      "string"    ],    "train_size": 0,    "test_size": 0,    "feature_count": 0,    "escalation_estimate": 0,    "latency_estimate_p50_ms": 0,    "latency_estimate_p95_ms": 0,    "augmentation": {      "status": "string",      "original_count": 0,      "augmented_count": 0,      "target_size": 0,      "failure_reason": "string",      "per_class_counts": {        "property1": 0,        "property2": 0      }    },    "auto_generation": {      "status": "string",      "generated_count": 0,      "original_count": 0,      "minimum_required": 0    }  },  "quality_gate_met": true,  "target_f1": 0,  "error": "string",  "current_attempt_id": "0a9f3a6a-6768-44e1-9b4d-bcf1a1fbbb53",  "execution_name": "string",  "last_heartbeat_at": "2019-08-24T14:15:22Z",  "last_training_error": "string",  "created_at": "2019-08-24T14:15:22Z"}

Cancel a training job

Cancel a training job that is currently in progress. Durably fences the worker as 'cancelling', requests cancellation of this policy's exact Cloud Run execution, then marks it 'cancelled' only after Cloud Run confirms the stop operation. Policies already in 'cancelling' can be polled/retried safely.

Authorization

AuthorizationBearer <token>

A 64-character hexadecimal Sparkient API key. Create a key in the Sparkient dashboard and send it as Authorization: Bearer YOUR_API_KEY.

In: header

Path Parameters

decision_type_id*Decision Type Id

Formatuuid

policy_id*Policy Id

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/decision-types/497f6eca-6276-4993-bfeb-53cbbbba6f08/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "decision_type_id": "5387d3c6-2309-41c6-9fe0-78021326d726",  "version": 0,  "policy_type": "string",  "status": "string",  "deployed": true,  "auto_deployed": false,  "training_config": {    "augment": true,    "augment_target_size": 0,    "auto_generate": false,    "tune_hyperparams": true,    "n_tuning_trials": 0,    "target_f1": 0,    "auto_deploy": true,    "escalation_threshold": 0  },  "metrics": {    "accuracy": 0,    "macro_f1": 0,    "macro_precision": 0,    "macro_recall": 0,    "per_class": {      "property1": {        "property1": 0,        "property2": 0      },      "property2": {        "property1": 0,        "property2": 0      }    },    "confusion_matrix": [      [        0      ]    ],    "confusion_labels": [      "string"    ],    "train_size": 0,    "test_size": 0,    "feature_count": 0,    "escalation_estimate": 0,    "latency_estimate_p50_ms": 0,    "latency_estimate_p95_ms": 0,    "augmentation": {      "status": "string",      "original_count": 0,      "augmented_count": 0,      "target_size": 0,      "failure_reason": "string",      "per_class_counts": {        "property1": 0,        "property2": 0      }    },    "auto_generation": {      "status": "string",      "generated_count": 0,      "original_count": 0,      "minimum_required": 0    }  },  "quality_gate_met": true,  "target_f1": 0,  "error": "string",  "current_attempt_id": "0a9f3a6a-6768-44e1-9b4d-bcf1a1fbbb53",  "execution_name": "string",  "last_heartbeat_at": "2019-08-24T14:15:22Z",  "last_training_error": "string",  "created_at": "2019-08-24T14:15:22Z"}

Get training progress

Get real-time training progress for a policy. Returns the current training stage, progress percentage, elapsed time, durable attempt history, and completed stages. Runtime-dependent completion times are not presented as a fixed estimate.

Optimised for polling: reads from Redis (sub-1ms) with a database fallback. Poll every 3-5 seconds while status is 'training', 'stopping', or 'cancelling'. A 'stopping' policy retains its organisation slot until the exact stale execution is confirmed terminal. Polling also reconciles a dead worker heartbeat.

When training is complete (status is 'trained', 'deployed', or 'cancelled') or has failed, returns the durable terminal state.

Authorization

AuthorizationBearer <token>

A 64-character hexadecimal Sparkient API key. Create a key in the Sparkient dashboard and send it as Authorization: Bearer YOUR_API_KEY.

In: header

Path Parameters

decision_type_id*Decision Type Id

Formatuuid

policy_id*Policy Id

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/decision-types/497f6eca-6276-4993-bfeb-53cbbbba6f08/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08/progress"

{  "policy_id": "ee9b03e0-6495-427a-85a5-34444d24ae04",  "status": "string",  "stage": "string",  "stage_name": "string",  "stage_number": 0,  "total_stages": 0,  "progress_percent": 0,  "message": "string",  "started_at": "2019-08-24T14:15:22Z",  "elapsed_seconds": 0,  "duration_hint": "string",  "completed_stages": [    {      "stage": "string",      "name": "string",      "completed_at": "2019-08-24T14:15:22Z"    }  ],  "error": "string",  "attempt_id": "7a838dca-3ea8-4a7c-8133-ba2c86aeb22d",  "attempt_number": 0,  "retry_count": 0,  "execution_name": "string",  "task_index": 0,  "task_attempt": 0,  "attempt_started_at": "2019-08-24T14:15:22Z",  "last_heartbeat_at": "2019-08-24T14:15:22Z",  "estimated_completion_at": "2019-08-24T14:15:22Z",  "attempts": [    {      "attempt_id": "7a838dca-3ea8-4a7c-8133-ba2c86aeb22d",      "attempt_number": 0,      "status": "string",      "execution_name": "string",      "task_index": 0,      "task_attempt": 0,      "started_at": "2019-08-24T14:15:22Z",      "last_heartbeat_at": "2019-08-24T14:15:22Z",      "completed_at": "2019-08-24T14:15:22Z",      "error": "string"    }  ]}

Training

202application/json

422application/json

503

200application/json

422application/json

200application/json

422application/json

200application/json

422application/json

200application/json

422application/json

200application/json

422application/json

200application/json

422application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`