Sparkient Docs

1. Get Your API Key

Sign in to the Sparkient Dashboard and navigate to Settings → API Keys. Click Create API Key, give it a name, and copy the key.

Your API key is shown only once. Copy it and store it securely.

2. Create a Decision Type

A decision type defines what you're deciding. It specifies the possible outcomes, reason codes, and any hard rules.

Create 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": "content_moderation",
    "description": "Should this user-generated content be approved?",
    "options": ["approve", "flag", "reject"],
    "reason_codes": ["safe_content", "borderline", "policy_violation", "spam"],
    "rules": [
      {
        "name": "block_spam_links",
        "condition": "ctx.link_count > 5",
        "then": "reject",
        "reason_code": "spam",
        "priority": 1
      }
    ]
  }'

3. Add Training Examples

Provide labelled examples so Sparkient can train a model for your decision type. You can also generate synthetic examples via the dashboard or the POST /examples/generate endpoint.

Minimum data requirements: Training requires at least 38 labelled examples per decision option (the training pipeline requires 30 per class in the 80/20 training split). The POST /examples/generate endpoint can generate an initial dataset directly from the decision type definition; existing seed examples are optional. You can check readiness via GET /decision-types/{id}/training-readiness.

Add training examples

curl -X POST https://api.sparkient.ai/api/v1/decision-types/{id}/examples \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "examples": [
      {
        "input_payload": { "text": "Buy cheap watches now!!!", "link_count": 8, "user_reputation_score": 0.1 },
        "expected_decision": "reject",
        "reason_codes": ["spam"]
      },
      {
        "input_payload": { "text": "Had a great experience with your service", "link_count": 0, "user_reputation_score": 0.95 },
        "expected_decision": "approve",
        "reason_codes": ["safe_content"]
      }
    ]
  }'

Shorter aliases accepted: For convenience, the API also accepts input, decision, and reason_code (singular string) as aliases for input_payload, expected_decision, and reason_codes respectively.

4. Train & Deploy a Model

Train an ML model from your examples. One API call triggers the full pipeline (feature engineering → model training → compiled model export):

Trigger training

curl -X POST https://api.sparkient.ai/api/v1/decision-types/{id}/train \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "auto_deploy": false }'

Sparkient runs the complete text-model and classifier pipeline for every new policy. Training time depends on the dataset and available compute. Poll the progress endpoint for the current attempt, stage, and heartbeat instead of relying on a fixed duration.

You can set a quality gate with target_f1 and control auto-deployment:

Training config options

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

Set augment_target_size to control how much synthetic training data is generated. Higher values increase coverage and runtime, but do not guarantee a better model. Compare held-out results. See Training → Tuning Augmentation Size for guidance.

Training runs asynchronously. auto_deploy defaults to true; if you disable it or a configured quality gate is not met, review the result and deploy the trained policy manually:

Deploy the trained model

curl -X POST https://api.sparkient.ai/api/v1/decision-types/{id}/policies/{policy_id}/deploy \
  -H "Authorization: Bearer YOUR_API_KEY"

5. Make a Decision

You must train and deploy a model before calling /decide. Without a deployed model, the API returns 428 Precondition Required with error code model_not_deployed.

Now send an input to get a structured decision:

Make a decision

curl -X POST https://api.sparkient.ai/api/v1/decide \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision_type": "content_moderation",
    "input": {
      "text": "Check out this great new product!",
      "link_count": 1,
      "user_reputation_score": 0.85
    }
  }'

Response

Decision response

{
  "decision": "approve",
  "confidence": 0.92,
  "reason_codes": ["safe_content"],
  "latency_ms": 4.2,
  "stage": "classifier",
  "escalate": false,
  "rules_triggered": [],
  "request_id": "req_abc123"
}

Verify Your Setup

You can verify your API connection by hitting the root endpoint:

Check the API

curl https://api.sparkient.ai/

Root response

{
  "service": "Sparkient API",
  "by": "Sparkient",
  "version": "1.0.0",
  "documentation": "https://docs.sparkient.ai",
  "openapi": "https://docs.sparkient.ai/openapi.json",
  "health": "/health"
}

Authentication

Sparkient supports two authentication methods:

Method	Header	Use Case
API Key	`Authorization: Bearer YOUR_API_KEY`	Programmatic access — `/decide`, `/decide/batch`, decision type CRUD, examples, training
Firebase JWT	`Authorization: Bearer <firebase_id_token>`	Dashboard — `/auth/me`, API key management, billing, org settings

All examples on this page use API key auth. Dashboard-only endpoints (account management, billing, API key CRUD) require a Firebase JWT and will return 403 if called with an API key.

Next Steps

Authentication — understand API keys vs Firebase JWT
Decision Types — learn about options, rules, and versions
Training Pipeline — how the teacher-student architecture works
API Reference — full endpoint documentation

Quickstart