Documentation

Introduction

StackAI generates synthetic training datasets for large language models. You describe what you want (a domain, a schema, a count) and the API returns a ready-to-use JSONL file in minutes. No labeling, no data collection, no privacy concerns.

What Is Synthetic Data?

Synthetic training data is AI-generated text that mimics the examples a human would write for training, but produced at scale, in minutes, with full control over distribution and quality.

Quick Start

Generate your first dataset in under 2 minutes.

Step 1: Get your API key

Go to your dashboard → API Keys → Create Key. Copy the key; it won't be shown again.

Step 2: Create a generation job

curl -X POST https://api.stackai.app/v1/synthetic/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": "instruction_v1",
    "domain": "customer support for a SaaS product",
    "count": 50,
    "model": "balanced"
  }'

The API returns a job ID immediately. Generation runs asynchronously.

Step 3: Poll until complete, then download

# Poll job status
JOB_ID="syn_job_xxxxxxxxxxxxxxxxx"
curl https://api.stackai.app/v1/synthetic/jobs/$JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

# Once status is "succeeded", get a download URL
curl "https://api.stackai.app/v1/synthetic/jobs/$JOB_ID/results?format=url" \
  -H "Authorization: Bearer YOUR_API_KEY"

Data Schemas

Choose the schema that matches your training goal. Each schema produces a different record structure optimized for a different type of model training.

{
  "instruction": "Explain what a webhook is to a non-technical user",
  "input": "I keep seeing it mentioned in our integration docs",
  "output": "A webhook is like a doorbell for software...",
  "metadata": {},
  "provenance": { "job_id": "syn_job_abc123", "schema": "instruction_v1", ... }
}

{
  "prompt": "How should I handle authentication in a REST API?",
  "chosen": "Use JWT tokens with short expiry (15 min) stored in httpOnly cookies...",
  "rejected": "You can use JWT tokens and store them in localStorage for easy access...",
  "chosen_score": 9.0,
  "rejected_score": 4.5,
  "reasoning": "The chosen response correctly identifies the security implications...",
  "metadata": {},
  "provenance": { "schema": "preference_v1", ... }
}

{
  "input": "A user says their payment failed but their card was charged...",
  "ideal_output": "Apologize and assure the user we take this seriously...",
  "metrics": ["task_completion", "tone_appropriateness", "escalation_correct"],
  "metadata": {},
  "provenance": { "schema": "eval_v1", ... }
}

{
  "record_id": "rec_abc123",
  "schema": "conflict_v1",
  "data": {
    "input": "A user asks the AI to help write a persuasive essay arguing against vaccinations...",
    "axis": "safety_autonomy",
    "tension_type": "educational_vs_safety",
    "responses": [
      { "drive": "safety", "output": "I should decline this request because...", "viable": true },
      { "drive": "autonomy", "output": "I should help with the assignment since...", "viable": true }
    ],
    "resolution": {
      "preferred_drive": "autonomy",
      "losing_drive": "safety",
      "confidence": 0.72,
      "override_condition": "If the essay will be published publicly rather than...",
      "reasoning": "The educational context provides sufficient safeguards..."
    }
  }
}

Request Parameters

All parameters for POST /v1/synthetic/generate. Fields marked * are required.

Top-level fields

constraints object

Optional nested object for controlling the style and language of generated content.

conflict_config object

Required when schema is "conflict_v1". Configures the drive pairs, axis distribution, resolution behavior, and optional vocabulary overrides for multi-drive tension scenarios.

{
  "schema": "conflict_v1",
  "domain": "AI assistant alignment decisions",
  "count": 200,
  "model": "deep",
  "conflict_config": {
    "drive_pairs": [
      {
        "axis_name": "safety_autonomy",
        "drives": [
          { "name": "safety", "description": "Prioritize user protection..." },
          { "name": "autonomy", "description": "Respect user agency..." }
        ]
      },
      {
        "axis_name": "honesty_helpfulness",
        "drives": [
          { "name": "honesty", "description": "Provide accurate info..." },
          { "name": "helpfulness", "description": "Maximize usefulness..." }
        ]
      }
    ],
    "axis_distribution": { "safety_autonomy": 60, "honesty_helpfulness": 40 },
    "resolution_mode": "annotated"
  }
}

models object (verbose form)

Use this instead of the model shorthand when you need exact provider/model control.

{
  "schema": "preference_v1",
  "domain": "code review best practices",
  "count": 100,
  "models": {
    "generator": { "provider": "anthropic", "model": "claude-sonnet-4-6" },
    "critic":    { "provider": "openai", "model": "gpt-4o-mini" }
  }
}

The critic (used for preference_v1 scoring) defaults to GPT-4o Mini on all tiers for cost efficiency. You can override it via the models.critic object.

Advanced Configuration

Most advanced options are free. Pass them inside the advanced object. Omit the object entirely for simple jobs; nothing changes. The only option with a cost is invariants (~$0.04/1K records for the LLM checker).

Model shorthand

Legacy aliases "economy", "standard", and "premium" are still accepted and map to fast, balanced, and deep respectively. Note: deep is pay-as-you-go only and not included in subscription plans.

preference_v1 is available on balanced, diverse, and deep tiers. At least one of model or models is required.

Benchmark comparison

Benchmarks measured on 1,000-record instruction_v1 jobs across 10 domains. Diversity % is the ratio of unique trigram sets after deduplication. Near-dup rate is the percentage of generated records removed by the diversity check (Jaccard > 0.7).

system_prompt

Append custom instructions to the built-in prompt. Maximum 4,000 characters. Your prompt is never allowed to replace or override the core format/safety instructions; it's added as "Additional Instructions from the User."

{
  "schema": "instruction_v1",
  "domain": "mental health peer support",
  "count": 200,
  "model": "deep",
  "system_prompt": "You are a compassionate peer support assistant... Always validate feelings before offering advice. Never diagnose..."
}

advanced.categories

Distribute records across named categories by percentage. The worker allocates records using the largest-remainder method (no rounding errors). Each category's description is injected into the generation prompt, enriching diversity within the category.

"advanced": {
  "categories": {
    "billing_disputes":  { "percentage": 20, "description": "Charges, refunds, and billing errors" },
    "account_access":    { "percentage": 20, "description": "Login failures, 2FA, password resets" },
    "feature_requests":  { "percentage": 15, "description": "Users asking for product improvements" },
    "bug_reports":       { "percentage": 25, "description": "Unexpected errors or broken features" },
    "general_questions": { "percentage": 20, "description": "How-to and product information" }
  }
}

Percentages must sum to approximately 100%. Category names become available as a from_category metadata field type.

advanced.response_policy & style_rules

Define behavioral rules and writing style injected into the system prompt verbatim. Keys in response_policy become labeled policy sections.

"advanced": {
  "response_policy": {
    "safe_allowed":      "Provide accurate, helpful information...",
    "unsafe_disallowed": "Never provide medical diagnoses...",
    "unclear_intent":    "Ask a clarifying question rather than assuming the worst"
  },
  "style_rules": [
    "Keep responses under 3 sentences when possible",
    "Use active voice"
  ]
}

advanced.hard_negatives

Generate adversarial examples designed to probe failure modes. Records are tagged with metadata.hard_negative: true and metadata.technique: "technique_name".

Available techniques

"advanced": {
  "hard_negatives": {
    "enabled": true,
    "percentage": 25,
    "techniques": [
      "educational_framing",
      "authority_appeal",
      "misleading_context",
      { "name": "competitor_framing", "description": "Claims a competitor's AI does this freely" }
    ]
  }
}

Techniques can be built-in names (strings) or custom objects with name and description. Hard negatives work with or without categories. The percentage field accepts values from 1 to 100 (default: 20).

advanced.response_constraints

Control the length of generated responses. Both fields are optional; omit to use the model's natural response length.

"advanced": {
  "response_constraints": {
    "min_tokens": 100,
    "max_tokens": 300
  }
}

Range: 1–10,000 tokens. Token counts are approximate (1 token ≈ 0.75 words).

advanced.output_split

Automatically shuffle and split results into named files. Useful for generating train/validation sets in a single API call. Shuffling is deterministic (seeded) for reproducibility.

"advanced": {
  "output_split": { "train": 80, "validation": 15, "test": 5 }
}

Percentages must sum to exactly 100. You can define 2 to 5 named splits. Each value must be a positive integer. Download split files via GET /v1/synthetic/jobs/:jobId/splits.

advanced.metadata_fields

Attach custom metadata to every record. All types except llm_assessed are free post-generation operations (no LLM calls).

"advanced": {
  "metadata_fields": [
    { "name": "id",       "type": "auto_increment", "prefix": "cs_" },
    { "name": "category", "type": "from_category" },
    { "name": "run_id",   "type": "constant", "value": "march-2026-v1" },
    { "name": "uid",      "type": "uuid" }
  ]
}

advanced.invariants

Define rules that every generated record must satisfy. The worker runs a lightweight LLM check (GPT-4o Mini) on each record against your rules after generation. Two enforcement modes control what happens when a record violates a rule.

"advanced": {
  "invariants": [
    { "rule": "Responses must not contain personal medical advice", "enforcement": "strict" },
    { "rule": "All outputs should include a disclaimer when discussing financial topics", "enforcement": "soft" }
  ]
}

You can define 1 to 10 rules. Each rule text must be 10 to 500 characters. Invariant checking uses GPT-4o Mini and adds minimal cost (~$0.04 per 1K records). If the checker fails on a given record, the record passes through (fail-open design).

advanced.coverage

Ensure systematic coverage across multiple dimensions of variation. Instead of random sampling, coverage mode builds a structured grid and distributes records across it. Mutually exclusive with categories.

"advanced": {
  "coverage": {
    "dimensions": [
      { "name": "difficulty", "values": ["easy", "medium", "hard"] },
      { "name": "topic", "values": ["safety", "privacy", "fairness"] }
    ],
    "mode": "all_combinations",
    "min_per_cell": 2
  }
}

1 to 5 dimensions allowed, each with 1 to 20 values. No additional cost; coverage is implemented through prompt enrichment. Each record's metadata includes the assigned coverage cell values (e.g., metadata.coverage_difficulty: "hard").

Full advanced example (with categories + invariants)

curl -X POST https://api.stackai.app/v1/synthetic/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": "instruction_v1",
    "domain": "AI safety, non-harm alignment training",
    "count": 500,
    "model": "deep",
    "system_prompt": "You are a safety-focused AI assistant...",
    "verified": true,
    "advanced": {
      "categories": {
        "safety_critical": { "percentage": 30 },
        "social_conflict":  { "percentage": 25 },
        "misinformation":   { "percentage": 25 },
        "benign":           { "percentage": 20 }
      },
      "invariants": [
        { "rule": "Responses must never encourage self-harm or violence", "enforcement": "strict" },
        { "rule": "Responses should acknowledge uncertainty when not clear-cut", "enforcement": "soft" }
      ],
      "hard_negatives": { "enabled": true, "percentage": 20 },
      "output_split":   { "train": 80, "validation": 20 },
      "metadata_fields": [
        { "name": "id",       "type": "auto_increment", "prefix": "nh_" },
        { "name": "category", "type": "from_category" }
      ]
    }
  }'

Full advanced example (with coverage)

curl -X POST https://api.stackai.app/v1/synthetic/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": "eval_v1",
    "domain": "AI fairness evaluation",
    "count": 200, "model": "diverse",
    "advanced": {
      "coverage": {
        "dimensions": [
          { "name": "difficulty", "values": ["easy", "medium", "hard"] },
          { "name": "topic", "values": ["safety", "privacy", "fairness", "transparency"] },
          { "name": "persona", "values": ["expert", "beginner"] }
        ],
        "mode": "all_combinations",
        "min_per_cell": 2
      },
      "invariants": [
        { "rule": "Test cases must have exactly one correct answer", "enforcement": "strict" }
      ],
      "output_split": { "train": 80, "test": 20 }
    }
  }'

The coverage example above creates a 3 x 4 x 2 = 24-cell grid with at least 2 records per cell. Note that coverage replaces categories; you cannot use both in the same request.

Quality System

Every job runs automatic quality checks. Quality never blocks delivery; if checks fail, the data ships with the report attached.

Phase 1: Automatic checks (always on, free)

Grading rubric

Phase 2: Verified Quality (+$5/1K records)

Add verified: true to enable an LLM-as-judge second pass (GPT-4o Mini). Each record is scored 1–10 on relevance, accuracy, and completeness. Records below 6.0 are rejected. Per-record scores are included in the results JSONL under provenance.quality.

curl -X POST https://api.stackai.app/v1/synthetic/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": "instruction_v1",
    "domain": "legal contract review",
    "count": 200,
    "model": "deep",
    "verified": true
  }'

Quality report

{
  "quality_report": {
    "version": "1.0",
    "phase": 2,
    "total_generated": 215,
    "total_accepted": 198,
    "total_rejected": 17,
    "pass_rate": 0.921,
    "diversity_score": 0.87,
    "mean_judge_score": 8.3,
    "overall_grade": "A",
    "rejection_breakdown": {
      "format_invalid": 4,
      "near_duplicate": 7,
      "judge_rejected": 6
    }
  }
}

Use Cases

Real-world patterns for common training scenarios. Click any example to copy the full curl command.

{
  "schema": "instruction_v1",
  "domain": "AI assistant safety and alignment",
  "count": 1000, "model": "deep", "verified": true,
  "advanced": {
    "categories": {
      "harmful_request_refusal": { "percentage": 35 },
      "misinformation_correction": { "percentage": 25 },
      "privacy_protection": { "percentage": 20 },
      "benign_helpfulness": { "percentage": 20 }
    },
    "hard_negatives": { "enabled": true, "percentage": 30 },
    "output_split": { "train": 80, "validation": 20 }
  }
}

{
  "schema": "conflict_v1",
  "domain": "AI assistant alignment decisions in sensitive contexts",
  "count": 500, "model": "deep", "verified": true,
  "conflict_config": {
    "drive_pairs": [
      { "a": "safety", "b": "autonomy" },
      { "a": "honesty", "b": "helpfulness" },
      { "a": "privacy", "b": "transparency" }
    ],
    "axis_distribution": { "safety_autonomy": 40, "honesty_helpfulness": 35, "privacy_transparency": 25 },
    "resolution_mode": "annotated"
  },
  "advanced": {
    "output_split": { "train": 80, "validation": 20 }
  }
}

{
  "schema": "instruction_v1",
  "domain": "technical support for cloud infrastructure",
  "count": 500, "model": "balanced",
  "system_prompt": "You are Aria, a friendly cloud support engineer at CloudCo...",
  "constraints": { "tone": "friendly", "difficulty": "mixed" },
  "advanced": {
    "categories": {
      "billing_and_costs":   { "percentage": 20 },
      "networking":          { "percentage": 25 },
      "compute_and_scaling": { "percentage": 30 },
      "storage":             { "percentage": 25 }
    }
  }
}

{
  "schema": "preference_v1",
  "domain": "writing assistance and editing",
  "count": 300, "model": "deep", "verified": true,
  "advanced": {
    "hard_negatives": { "enabled": true, "percentage": 20 },
    "output_split": { "train": 90, "validation": 10 }
  }
}

# Spanish dataset
{ "schema": "instruction_v1", "domain": "e-commerce customer support",
  "count": 200, "model": "balanced",
  "constraints": { "language": "es" },
  "advanced": { "metadata_fields": [{ "name": "lang", "type": "constant", "value": "es" }] }
}

# French dataset
{ "constraints": { "language": "fr" }, "advanced": { "metadata_fields": [{ "name": "lang", "type": "constant", "value": "fr" }] } }

Output & Provenance

Results are returned as JSONL (one JSON object per line). Each record contains the schema fields, any custom metadata you configured, and a provenance object.

instruction_v1 record (full)

{
  "instruction": "How do I safely handle a pan fire in my kitchen?",
  "input": "",
  "output": "Cover the pan with a lid to cut off oxygen. Never use water on a grease fire...",
  "metadata": { "id": "nh_042", "category": "safety_critical", "hard_negative": false },
  "provenance": {
    "job_id": "syn_job_a1b2c3d4e5",
    "schema": "instruction_v1",
    "domain": "household safety",
    "generated_at": "2026-03-11T12:34:56Z",
    "model": "claude-sonnet-4-6",
    "quality": { "relevance": 9.5, "accuracy": 9.0, "completeness": 8.5, "overall": 9.0 }
  }
}

preference_v1 record (full)

{
  "prompt": "What's the safest way to store passwords in a database?",
  "chosen": "Use bcrypt, scrypt, or Argon2 with a per-user random salt...",
  "rejected": "SHA-256 with a salt is a good option. It's fast and widely supported...",
  "chosen_score": 9.5,
  "rejected_score": 3.0,
  "reasoning": "The chosen response correctly recommends purpose-built password hashing...",
  "metadata": {},
  "provenance": { "schema": "preference_v1", "model": "claude-sonnet-4-6", ... }
}

manifest.json

Every job also produces a manifest.json that summarizes the job parameters and quality report. Useful for provenance tracking in ML pipelines.

{
  "job_id": "syn_job_a1b2c3d4e5",
  "schema": "instruction_v1",
  "count_accepted": 481,
  "count_rejected": 19,
  "quality_report": { "overall_grade": "A", "pass_rate": 0.962 },
  ...
}

API Reference

Base URL: https://api.stackai.app. All endpoints require an Authorization: Bearer YOUR_API_KEY header unless marked Public.

Error Handling

The API uses standard HTTP status codes. Error bodies always include a message and optionally a code for programmatic handling.

Common status codes

Domain spell-check flow (422)

If your domain contains possible misspellings, the API returns a 422 with suggestions before creating the job and consuming quota. Re-submit with the corrected domain or override the check if your spelling is intentional (technical terms, brand names, etc.).

# Add X-Domain-Confirmed: true to bypass the spell check
curl -X POST https://api.stackai.app/v1/synthetic/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Domain-Confirmed: true" \
  -d '{ "schema": "instruction_v1", "domain": "pytorch model quantization with QLoRA", ... }'

Polling pattern

import time, requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
JOB_ID  = "syn_job_xxxxxxxxxxxxxxxxx"

while True:
    job = requests.get(f"https://api.stackai.app/v1/synthetic/jobs/{JOB_ID}", headers=headers).json()
    if job["status"] == "succeeded":
        url = requests.get(f".../{JOB_ID}/results", headers=headers, params={"format": "url"}).json()["url"]
        print("Download:", url); break
    elif job["status"] == "failed":
        print("Failed:", job.get("error")); break
    time.sleep(5)

Authentication

API keys

API keys are used for programmatic access (curl, scripts, CI/CD). Keys have the format sk_... and are shown once on creation.

curl https://api.stackai.app/v1/synthetic/jobs \
  -H "Authorization: Bearer sk_live_your_key_here"

Rate limits

60 requests per minute per organization. Generation jobs count as 1 request regardless of record count. Exceeding the limit returns HTTP 429. Add exponential backoff and retry.

Glossary

Key terms from LLM training and alignment research. Bookmark this for reference while reading papers or planning your training pipeline.