API recipes

Copy-and-run flows. Each one is complete: no steps left as an exercise. All of them assume $TOKEN and $BASE:

BASE="${MATHFI_BASE_URL:?set it to https://<tenant>-api.mathfi.ai}"
TOKEN=$(curl -sS -X POST "$BASE/api/login" \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"$MATHFI_EMAIL\",\"password\":\"$MATHFI_PASSWORD\"}" | jq -r .access_token)

jq is used throughout for readability. Nothing depends on it.

Feature Refinery

Create, upload two files, start, poll, download.

1. Create the run

CREATED=$(curl -sS -X POST "$BASE/api/v1/feature-refinery" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "German Credit Risk",
        "numberOfBuckets": 10,
        "trainFileName": "train.csv",
        "testFileName": "test.csv"
      }')

FR_KEY=$(jq -r .featureRefinementKey <<<"$CREATED")

The name must be unique among your unfinished runs: letters, digits, spaces, hyphens, underscores, 1 to 100 characters. A clash is 409. numberOfBuckets must be 4, 10 or 20.

2. Upload both files

The response carries one uploadTargets entry per file. Each has a url and possibly a requiredHeader as a single Name:value string.

# upload <create-response-json> <TRAIN|TEST> <path>
upload() {
  local body=$1 kind=$2 path=$3
  local url hdr
  url=$(jq -r --arg k "$kind" '.uploadTargets[] | select(.kind==$k) | .url' <<<"$body")
  hdr=$(jq -r --arg k "$kind" '.uploadTargets[] | select(.kind==$k) | .requiredHeader // ""' <<<"$body")

  local args=(-sS -X PUT "$url" -H "Content-Type: text/csv" --data-binary "@$path")
  [[ -n $hdr ]] && args+=(-H "${hdr%%:*}: ${hdr#*:}")
  curl "${args[@]}"
}

upload "$CREATED" TRAIN train.csv
upload "$CREATED" TEST  test.csv

No Authorization header on these. The URL is already signed, and adding one gives 403.

3. Start it

curl -sS -X POST "$BASE/api/v1/feature-refinery/$FR_KEY/start" \
  -H "Authorization: Bearer $TOKEN"

400 means a file did not arrive, or the training file has more than 70 columns. 409 means it was already started. 429 means you already have 5 runs in flight.

4. Poll

while :; do
  P=$(curl -sS -H "Authorization: Bearer $TOKEN" \
        "$BASE/api/v1/feature-refinery/$FR_KEY/progress")
  STATE=$(jq -r .state <<<"$P")
  echo "$STATE $(jq -r '((.progressCompleted // 0) / (.progressTotal // 1) * 100 | floor)' <<<"$P")%"
  case $STATE in
    REFINEMENT_COMPLETED) break ;;
    ERROR|TIMEOUT|CANCELLED) jq -r '.errorReason // .state' <<<"$P" >&2; exit 1 ;;
  esac
  sleep 60
done

States run PENDING → SETUP_* → MEASURE_INITIAL_THRESHOLD* → BASELINE_RUN_* → REFINING_LOOP_* → CREATING_RESULT → REFINEMENT_COMPLETED. Match on the terminal states, not on the intermediate ones; those can change. This takes a while. Time scales with columns, not rows.

5. Collect the result

RESULT=$(curl -sS -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/v1/feature-refinery/$FR_KEY/result")

# Which columns were dropped
jq -r '.columnStatus[] | select(.outcome=="REMOVE") | .columnName' <<<"$RESULT"

# The reduced files (signed, short-lived)
curl -sS -o refined-train.csv "$(jq -r .refinedTrainUrl <<<"$RESULT")"
curl -sS -o refined-test.csv  "$(jq -r .refinedPredictionUrl <<<"$RESULT")"
curl -sS -o column-status.csv "$(jq -r .refinedColumnStatusUrl <<<"$RESULT")"

The download URLs are null until the state is REFINEMENT_COMPLETED, and they expire. Fetch the result again for fresh ones. You do not need to download anything if the next step is training: hand the key straight over.

Model Crucible

DS=$(curl -sS -X POST "$BASE/api/v1/datasets" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"datasetName\":\"German Credit refined\",\"featureRefinementKey\":\"$FR_KEY\"}")

DATASET_KEY=$(jq -r .datasetKey <<<"$DS")

uploadTargets comes back empty. The refined files, the bucket count and the measured target all come across with the refinement.

Do not call /clean on this route. Creating the dataset already started it. Calling /clean earns a 409 already cleaned.

1b. Dataset from your own files

DS=$(curl -sS -X POST "$BASE/api/v1/datasets" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"datasetName":"My Dataset","numberOfBuckets":10}')

DATASET_KEY=$(jq -r .datasetKey <<<"$DS")

# the same upload helper as above, pointed at this create response
upload "$DS" TRAIN train.csv
upload "$DS" TEST  test.csv

curl -sS -X POST "$BASE/api/v1/datasets/$DATASET_KEY/clean" \
  -H "Authorization: Bearer $TOKEN"

Here /clean is required, and only after both files have landed.

2. Wait for the dataset

until [[ $(curl -sS -H "Authorization: Bearer $TOKEN" \
           "$BASE/api/v1/datasets/$DATASET_KEY" | jq -r .status) == COMPLETED ]]; do
  sleep 15
done

FAILED is terminal too. Check for it, and read .errors when it happens.

3. Train

Read the target off the dataset rather than inventing one.

DETAIL=$(curl -sS -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/datasets/$DATASET_KEY")
THRESHOLD=$(jq -r '.recommendedThreshold // 0.8' <<<"$DETAIL")

JOB=$(curl -sS -X POST "$BASE/api/v1/training/datasets/$DATASET_KEY" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"performanceThreshold\": $THRESHOLD, \"scalingFactor\": 19}")

JOB_KEY=$(jq -r .trainingJobKey <<<"$JOB")

recommendedThreshold is present only on a dataset that came from a refinement. When it is absent, you are choosing the target, and choosing badly is the most expensive mistake available. A target far above what the data supports produces a model that predicts one class for every row: plausible accuracy, F1 of zero. Always check F1 and recall on the result, not just accuracy.

4. Poll the run

while :; do
  P=$(curl -sS -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/training/$JOB_KEY/progress")
  STATUS=$(jq -r .status <<<"$P")
  [[ $STATUS =~ ^(COMPLETED|TIMED_OUT|CANCELLED|FAILED|NOT_COMPLETED)$ ]] && break
  sleep "$(jq -r '.nextPollAfterSeconds // 15' <<<"$P")"
done
echo "$STATUS"

5. Look at what it offers

RUN=$(curl -sS -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/training/$JOB_KEY")

jq -r '.performance.candidates[]
       | [.version, .attemptNumber, .falseDecisions, .accuracy, .f1Score, .recall]
       | @tsv' <<<"$RUN"

MODEL_KEY=$(jq -r .modelKey <<<"$RUN")

Candidates come back best first, ranked by fewest falseDecisions. v1 is champion by default.

6. Change the champion, if you want a different trade

curl -sS -X POST "$BASE/api/v1/training/$JOB_KEY/champion" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"attemptNumber": 7, "observations": "Higher recall matters more than total error here"}'

attemptNumber must be one the run actually offers, or you get 400. Nothing is rebuilt; a flag moves. Predictions already run keep the version they ran against.

7. Predict

PRED=$(curl -sS -X POST \
  "$BASE/api/v1/predictions?modelKey=$MODEL_KEY&applyColumnStatusFilter=true" \
  -H "Authorization: Bearer $TOKEN" \
  -F "[email protected];type=text/csv")

PRED_KEY=$(jq -r .predictionKey <<<"$PRED")

until [[ $(curl -sS -H "Authorization: Bearer $TOKEN" \
           "$BASE/api/v1/predictions/$PRED_KEY/progress" | jq -r .status) =~ ^(COMPLETED|FAILED|TIMEOUT)$ ]]; do
  sleep 15
done

curl -sS -o result.csv "$(curl -sS -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/v1/predictions/$PRED_KEY" | jq -r .predictionResultDownloadUrl)"

The multipart part is named _file. The underscore is required. applyColumnStatusFilter=true drops the columns the refinement removed, going by position, so you can send your original unlabelled file unchanged. It only works where the model’s dataset came from a refinement; anywhere else it is a 400. A file you already stripped yourself passes through untouched.

Common problems

Symptom	Cause
`403 SignatureDoesNotMatch` on upload	An `Authorization` header was sent, a required header was missed, or the URL expired
`400` on `/start`	A file did not land, or the training file exceeds 70 columns
`409` on dataset create	The run name is taken by an unfinished run
`409 already cleaned`	`/clean` was called on a refinement handoff, where it is not needed
`429`	5 runs already in flight. Nothing was created; retry after one finishes
Champion has F1 of `0`	The training target was far above what the data supports
`401` mid-run	An idle token lapsed. Log in again and continue

Build a CLI or agent from this

The same contract, written for a machine to consume.

Getting started

Authentication

Feature Refinery

Model Crucible

Feature Refinery

1. Create the run

2. Upload both files

3. Start it

4. Poll

5. Collect the result

Model Crucible

1a. Dataset from a finished refinement

1b. Dataset from your own files

2. Wait for the dataset

3. Train

4. Poll the run

5. Look at what it offers

6. Change the champion, if you want a different trade

7. Predict

Common problems

Build a CLI or agent from this

​Feature Refinery

​1. Create the run

​2. Upload both files

​3. Start it

​4. Poll

​5. Collect the result

​Model Crucible

​1a. Dataset from a finished refinement

​1b. Dataset from your own files

​2. Wait for the dataset

​3. Train

​4. Poll the run

​5. Look at what it offers

​6. Change the champion, if you want a different trade

​7. Predict

​Common problems

Build a CLI or agent from this

Feature Refinery

1. Create the run

2. Upload both files

3. Start it

4. Poll

5. Collect the result

Model Crucible

1a. Dataset from a finished refinement

1b. Dataset from your own files

2. Wait for the dataset

3. Train

4. Poll the run

5. Look at what it offers

6. Change the champion, if you want a different trade

7. Predict

Common problems