Sparkient Docs

A decision type is the core building block of Sparkient. It defines a specific kind of decision your application needs to make — content moderation, fraud detection, agent action gating, or anything else.

Anatomy of a Decision Type

Every decision type has:

Field	Description
Name	Unique identifier (e.g., `content_moderation`). Used in API calls.
Description	Human-readable explanation of what this decision does.
Options	The possible outcomes (e.g., `["approve", "flag", "reject"]`).
Reason Codes	Why a particular decision was made (e.g., `["safe_content", "spam"]`).
Rules	Hard-coded expression rules that fire before the ML classifier.
Input Schema	Optional JSON Schema to validate inputs before processing.

Creating a Decision Type

curl -X POST https://api.sparkient.ai/api/v1/decision-types \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "agent_action_gate",
    "description": "Should an AI agent proceed with this action?",
    "options": ["act", "ask_user", "escalate", "block"],
    "reason_codes": ["safe_action", "needs_confirmation", "high_risk"],
    "rules": [
      {
        "name": "block_destructive",
        "condition": "ctx.action_type == \"delete\" && ctx.scope == \"all\"",
        "then": "block",
        "reason_code": "high_risk",
        "priority": 1
      }
    ]
  }'

Versioning

Decision types are immutable by version. When you update a decision type (change options, rules, or thresholds), a new version is created. The active version is always the latest.

This means:

You can roll back by re-activating an older version
Training history is tied to specific versions
Deployed models reference the version they were trained on

Confidence Thresholds

You can configure how confident the classifier must be before making a decision autonomously:

{
  "confidence_thresholds": {
    "escalate_below": 0.5,
    "per_option": {
      "block": 0.9,
      "ask_user": 0.75
    }
  },
  "escalation_policy": {
    "enabled": false
  }
}

The effective threshold is the higher of escalate_below and the threshold for the predicted option. A prediction at or above that threshold is returned directly.

Below the threshold:

With escalation_policy.enabled: true, Sparkient can call the configured LLM escalation path.
With escalation_policy.enabled: false, Sparkient returns the classifier result with escalate: true so your application can request human review. It does not call or charge for an LLM.
If the classifier is unavailable while escalation is disabled, the API returns 503 instead of inventing a fallback decision.

New decision types default to enabled: false. Enabling live-LLM escalation must be an explicit choice.

Thresholds must be between 0 and 1, and every per_option key must be one of the decision type's configured options.

Decision Types

Anatomy of a Decision Type

Creating a Decision Type

Versioning

Confidence Thresholds

On this page