Mock Matrix
Sign inGenerate free

Developer quickstart

Generate a synthetic dataset from the command line in five requests.

Mock Matrix generates realistic, fully synthetic business datasets from a declarative scenario spec — describe the business, pick a domain pack, and download provenance-marked CSV/NDJSON/Parquet files. No real data is ever ingested: every value is produced from your parameters, public reference data, and pack-authored distributions. The web UI is a client of the same API, so anything you see here you can automate with curl.

Get an API key

Open Settings → Developer access to create and store your API key (keys look like mm_live_… and are shown once — Mock Matrix only stores a hash). Every request sends it as a bearer token:

setup.sh
export MOCK_MATRIX_API_URL="http://127.0.0.1:8000"   # or your deployed API URL
export MOCK_MATRIX_API_KEY="mm_live_..."

List the installed packs

A pack is a domain model (tables, distributions, parameter schema). List what your server has installed:

terminal
curl -s "$MOCK_MATRIX_API_URL/v1/packs" \
  -H "Authorization: Bearer $MOCK_MATRIX_API_KEY"

# [
#   {
#     "id": "salon",
#     "latest_version": "1.0.0",
#     "title": "Hair salon chain",
#     "summary": "A salon chain's booking and POS database..."
#   }
# ]

GET /v1/packs/{pack_id} adds the export formats, and GET /v1/packs/{pack_id}/parameter-schemareturns the JSON Schema for the pack's parameters block.

Create a generation job

POST /v1/jobs takes either an inline spec or a saved scenario_id (exactly one of the two), plus optional seed and formats overrides. Here is a small spec for the salon pack, written as JSON:

terminal
curl -s -X POST "$MOCK_MATRIX_API_URL/v1/jobs" \
  -H "Authorization: Bearer $MOCK_MATRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "spec_version": 1,
      "name": "quickstart-salon",
      "pack": "salon",
      "seed": 42,
      "time_window": { "start": "2025-01-01", "end": "2025-07-01" },
      "region": { "country": "US" },
      "output": { "formats": ["csv"] },
      "parameters": {
        "business": {
          "locations": 2,
          "footprint": ["Riverton metro"],
          "maturity": "expansion"
        },
        "customers": {
          "monthly_visits_per_location": 200,
          "membership_program": { "enabled": true, "penetration": 0.25 },
          "retail_attach_rate": 0.2
        }
      }
    }
  }'

# 202 Accepted
# { "job_id": "j_...", "status": "queued", "seed": 42 }

If you omit seed, the server picks one and returns it. Validation errors come back as RFC 9457 application/problem+json with a per-field errors array.

Poll until the job finishes

terminal
JOB_ID="j_..."   # from the create response

curl -s "$MOCK_MATRIX_API_URL/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $MOCK_MATRIX_API_KEY" | jq '{status, row_counts, usage}'

# Status moves queued -> running -> succeeded | failed | canceled.
# On success the response also carries "artifacts" and "manifest".

Download artifacts and verify checksums

Each artifact has a download_url (a signed, short-lived link — re-fetch the job to mint fresh ones) and a sha256 you can verify after download:

terminal
DETAIL=$(curl -s "$MOCK_MATRIX_API_URL/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $MOCK_MATRIX_API_KEY")

URL=$(echo "$DETAIL" | jq -r '.artifacts[0].download_url')
WANT=$(echo "$DETAIL" | jq -r '.artifacts[0].sha256')

curl -s -o appointments.csv "$URL"
echo "$WANT  appointments.csv" | sha256sum --check

# appointments.csv: OK

The job's manifest records the same checksums plus the spec hash, seed, and pack/engine versions — keep it next to your fixtures as the provenance record.

Determinism and CI

Generation is deterministic: the same spec, the same seed, and the same pack version produce byte-identical output. Pin the seed and pack_version in your spec and you can regenerate fixtures on demand instead of committing them. A minimal GitHub Actions step:

.github/workflows/fixtures.yml
- name: Generate synthetic fixtures
  env:
    MOCK_MATRIX_API_URL: ${{ secrets.MOCK_MATRIX_API_URL }}
    MOCK_MATRIX_API_KEY: ${{ secrets.MOCK_MATRIX_API_KEY }}
  run: |
    JOB=$(curl -s -X POST "$MOCK_MATRIX_API_URL/v1/jobs" \
      -H "Authorization: Bearer $MOCK_MATRIX_API_KEY" \
      -H "Content-Type: application/json" \
      --data @scenario.json | jq -r .job_id)
    for i in $(seq 1 60); do
      STATUS=$(curl -s "$MOCK_MATRIX_API_URL/v1/jobs/$JOB" \
        -H "Authorization: Bearer $MOCK_MATRIX_API_KEY" | jq -r .status)
      echo "job $JOB: $STATUS"
      [ "$STATUS" = "succeeded" ] && break
      case "$STATUS" in failed|canceled) exit 1;; esac
      sleep 5
    done
    curl -s "$MOCK_MATRIX_API_URL/v1/jobs/$JOB" \
      -H "Authorization: Bearer $MOCK_MATRIX_API_KEY" \
      | jq -r '.artifacts[].download_url' \
      | while read -r url; do curl -sSfO "$url"; done

Full API reference

The API serves an interactive OpenAPI reference at <api-url>/docs (for a local server, http://127.0.0.1:8000/docs) covering every endpoint: packs, scenarios, previews, jobs, artifacts, plan and usage, and billing. Rate limits and quotas depend on your plan — see Pricing.