API overview

Base URL

Every customer has their own tenant, so there is no single shared host. Yours is issued when the tenant is created:

https://<tenant>-api.mathfi.ai

Examples in these docs write $BASE. Set it once and the rest copies and runs:

export MATHFI_BASE_URL="https://<tenant>-api.mathfi.ai"
BASE="$MATHFI_BASE_URL"

Two path prefixes:

Prefix	Used by
`/api/login`	Authentication
`/api/v1/...`	Everything else

Never hard-code the host. A client that will be handed to someone on a different tenant should take it as configuration, alongside the credentials.

Authentication

Bearer token. Exchange your email and password for a JWT, then send it on every call.

TOKEN=$(curl -s -X POST "$BASE/api/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"[email protected]","password":"YOUR_PASSWORD"}' | jq -r .access_token)

curl -s -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/v1/datasets?offset=0&limit=10"

There are no API keys today. Details and token lifetime in Authentication.

Everything is asynchronous

Nothing blocks and nothing streams. Every long-running operation follows the same shape:

Create

POST the thing. You get a key back, plus signed URLs where files are expected.

Upload

PUT each file straight to its signed URL. This does not go through the API.

Start

POST to start, where the resource has a separate start step.

Poll

GET .../progress until the state is terminal.

Collect

GET the result. Download URLs are short-lived and signed.

Training and prediction have no separate start: creating them starts them.

Uploading files

When a create response carries uploadTargets, each entry is a place to PUT one file.

# target = { "kind": "TRAIN",
#            "url": "https://storage.googleapis.com/...",
#            "requiredHeader": "X-Goog-Content-Length-Range:10,534773760" }

curl -s -X PUT "$URL" \
  -H "Content-Type: text/csv" \
  -H "X-Goog-Content-Length-Range: 10,534773760" \
  --data-binary @train.csv

Three rules, and breaking any of them gives 403 SignatureDoesNotMatch:

Send Content-Type: text/csv.
Send the header named in requiredHeader, split on the first colon. It may be null, in which case send nothing extra.
Do not send an Authorization header. The signature covers the request. Your bearer token does not belong here and will break it.

Signed URLs expire 60 minutes after the create call. There is no re-sign endpoint: if the window closes, create the resource again.

Polling

Poll .../progress and stop when the state is terminal.

Resource	Terminal states
Feature refinement	`REFINEMENT_COMPLETED`, `ERROR`, `TIMEOUT`, `CANCELLED`
Dataset	`COMPLETED`, `FAILED`
Training job	`COMPLETED`, `TIMED_OUT`, `CANCELLED`, `FAILED`, `NOT_COMPLETED`
Prediction	`COMPLETED`, `FAILED`, `TIMEOUT`

Training progress returns nextPollAfterSeconds. Honour it. When it is absent, the job has finished and there is nothing left to wait for. Sensible intervals elsewhere: 15 to 30 seconds for datasets and predictions, 30 to 60 seconds for a refinement, which runs for tens of minutes or longer. Refinement progress also carries progressCompleted and progressTotal. The unit is internal and has no standalone meaning, so rely on the ratio of the two and never on the raw numbers.

Errors

Standard HTTP status codes. The body carries a message written for a person.

Code	Means	What to do
`400`	Bad input. The message says which.	Fix and retry. Not retryable as-is.
`401`	No token, or it expired.	Log in again.
`403`	On a signed URL: the signature does not match.	Check your headers, or the URL expired.
`404`	Unknown key, or not yours.	Do not retry.
`409`	Wrong state. An input is missing, a name is taken, already started.	Read the message; it distinguishes the cases.
`429`	Too many of your runs are in flight.	Wait for one to finish. Nothing was created.
`500`	Server error.	Retry with backoff.

A 409 on POST /datasets/{key}/clean has two distinct causes, and the message tells them apart: an input file has not arrived yet, or the dataset was already cleaned. The second is usually harmless.

Limits

Limit	Value
Token lifetime	60 minutes idle, 24 hours absolute
Max upload size	510 MB
Signed URL lifetime	60 minutes
Columns per refinement training file	70
Concurrent refinements per user	5
Concurrent training jobs per user	5
Models kept per training run	3

Conventions

Keys are UUIDs and opaque. Pass them back exactly as given.
List endpoints require offset and limit. They are not optional. limit is capped at 100 on refinements.
Timestamps are ISO-8601 UTC, for example 2026-09-14T16:27:03.028Z.
A null metric means undefined, not zero. A test slice with no positive cases leaves recall undefined. Treat it as absent; reporting 0 says something different and wrong.
Multipart uploads use a part named _file. The underscore is not a typo. It is the only name the server binds.

Authentication

Tokens, lifetime, and handling expiry.

Recipes

Complete curl flows for both products.

Build an agent or CLI

The full contract in one page, written to be read by a machine.

Endpoint reference

Every endpoint, generated from the spec.

Getting started

Authentication

Feature Refinery

Model Crucible

Base URL

Authentication

Everything is asynchronous

Uploading files

Polling

Errors

Limits

Conventions

Next

Authentication

Recipes

Build an agent or CLI

Endpoint reference

​Base URL

​Authentication

​Everything is asynchronous

​Uploading files

​Polling

​Errors

​Limits

​Conventions

​Next

Authentication

Recipes

Build an agent or CLI

Endpoint reference

Base URL

Authentication

Everything is asynchronous

Uploading files

Polling

Errors

Limits

Conventions

Next