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 50 labelled examples with at least 10 per decision option. The POST /examples/generate endpoint requires at least 10 existing examples as seed data. 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 (default: balanced preset)

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 '{ "preset": "balanced" }'

Training Presets

Preset	Augmentation	HP Tuning	Typical Duration	Best For
`quick`	Off	Off	~30 seconds	Rapid iteration, prototyping
`balanced`	On	On (30 trials)	~2–5 minutes	Production-quality models

The balanced preset is the default. You can also set a quality gate with target_f1 and control auto-deployment:

Training config options

{
  "preset": "balanced",
  "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 produce better models but take longer to train. See Training → Tuning Augmentation Size for guidance.

Training runs asynchronously. Once complete, deploy the trained policy to production:

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": "/openapi.json",
  "health": "/health"
}

Authentication

Sparkient supports two authentication methods:

Method	Header	Use Case
API Key	`Authorization: Bearer sk_...`	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