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. Check Readiness and Optionally Add Examples

You can proceed directly to training with a decision definition. If you have representative labelled examples, add them first. You can also generate and review candidate examples separately using the optional endpoint below.

Starting data is optional: Training generates fresh examples and augments its training data by default. Both stages use credits. Add representative real examples when available. Check the planned preparation with 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

One API call generates fresh examples, augments the training data, trains the model and exports it:

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