Developers

FSI Customer API

OpenAPI 3.1 · machine-readable spec: /api/v1/openapi.json

Your access

Public

No key, no login. Run the scored Alphabet Test and the public L26 tracks — you get rates and grades; the inventory is never returned.

Not signed in — this is the public documentation. Sign in to see the docs for your own key.

What your access includes

Every item below is checked against the same gate the API enforces, so this list is exactly what your key can do today — nothing more, nothing less.

GET /api/v1/ — API root
GET /api/v1/self-test/challenge?language= — Alphabet-Test prompt — never the answer key
POST /api/v1/self-test — score the syllables your model produced — rates + counts
GET /api/v1/l26/tracks — L26 Lite: every track in the suite
GET /api/v1/l26/challenge — L26 Lite: the FULL suite (no track) or one track
POST /api/v1/l26/run — L26 Lite: score one track's cold + assisted lists
GET /api/v1/whoami — your tier, languages, quotaneeds any key
GET /api/v1/languages — the languages this key may useneeds any key
GET /api/v1/l26/results — L26 Lite: your tabulated boardneeds any key
POST /api/v1/l26/reflect — L26 Lite: optional feedback on a runneeds any key
GET /api/v1/usage — usage + remaining daily quotaneeds any key
GET /api/v1/coverage — per-language coverage matrixneeds Validation Pilot
GET /api/v1/fsi/{iso}?view=both — one full FSI (inventory | equation | both)needs Validation Pilot
GET /api/v1/fsi/{iso}/audio — consent-gated audio manifest (opaque tokens)needs Validation Pilot
GET /api/v1/fsi?iso=&zone=&country=&scope=all — select FSIs in bulk (paged)needs Full Annual Subscription

Not included at your tier

Saved history — scores are returned but not tracked until you have a key.
The inventories, audio, and downloads.

The Alphabet Test — no key, no login

Any agent can run the scored self-test over plain HTTPS or MCP with no token. You get rates, a deterministic grade and failure classes; the inventory is never returned, so nothing licensed leaks.

# 1) get the prompt curl "https://fsi.bantunomics.com/api/v1/self-test/challenge?language=bem" # 2) score what your model produced (no key) curl -X POST "https://fsi.bantunomics.com/api/v1/self-test" \ -H "Content-Type: application/json" \ -d '{"language":"bem","syllables":["ba","be","bi","mba"],"model_name":"your-model"}'

Agent entry point: /llms.txt · MCP discovery: /.well-known/mcp.json

L26 Lite — the alphabet-recital suite

L26 Lite is a suite, not a single-language test. You run every track — English and Mandarin Pinyin as controls, then the Bantu tracks — each one closed-book (no tools at all) and then tool-assisted. Each track is scored out of 26; the gap between the two passes is your tool-lift, which shows whether your model knows an alphabet or merely looks it up.

Call GET /api/v1/l26/challenge with no track to get the full battery.
Submit each track with POST /api/v1/l26/run — both lists in one call, so the cold score can never influence the assisted attempt.
Your result is withheld until every track is complete; each response tells you which tracks remain.
The answer key is never returned — the test stays re-runnable without contamination.

Runs are scored but not saved without a key.

Authentication

Keyed endpoints take a Bearer token. Evaluation keys are self-serve; Pilot and Full Annual Subscription keys are issued with the agreement.

curl -H "Authorization: Bearer <your-token>" \ https://fsi.bantunomics.com/api/v1/whoami

whoami is the honest mirror of this page: it returns your tier, the languages you may use, your quota, and what the next tier adds.

Rate limits & errors

Per-token daily quota. The Full Annual Subscription is uncapped.
401 missing/invalid token · 403 language not in your entitlement · 404 not found · 429 quota exceeded.
Every authenticated call is logged for audit + abuse detection.

A request can never widen access beyond the token's entitlement, and the licensing gate (only Released for Licensing languages) is applied on every call.

Agents (MCP)

The same product is available to agents over a hosted Streamable-HTTP MCP at POST /mcp. Register it exactly like any MCP endpoint:

{"url": "https://fsi.bantunomics.com/mcp"} # add an Authorization: Bearer <token> header for your key — omit it for the public tools

fsi_challenge(language) — the Alphabet-Test task
fsi_self_test(language, syllables[]) — deterministic score — rates + grade
fsi_phased_test(language, cold[], assisted[]) — cold vs tool-assisted + tool-lift
l26_lite_challenge() — the FULL L26 Lite suite (omit track); one track if named
l26_lite_run(track, cold[], assisted[]) — score a track — call once per track
l26_lite_results — your tabulated L26 Lite boardneeds any key
l26_reflect(phase_group, pros[], cons[]) — optional feedback on a runneeds any key
whoami — your tier + capabilitiesneeds any key
list_languages / search_languages — the languages this key may useneeds any key
get_fsi(iso, view) — the full inventory for a languageneeds Validation Pilot
get_voices(iso) — consented, de-identified speaker voicesneeds Validation Pilot
get_revision_history / get_provenance / get_benchmark_kit — curation trail, NSI/ASI provenance, reproducibility kitneeds Validation Pilot
raise_issue(iso, description) — file an FSI Change Requestneeds Validation Pilot

What Evaluation adds

the scored Alphabet Test on the assigned evaluation languages plus the full L26 Lite suite, with saved history — no inventory, audio, or downloads (those begin at Pilot)

Questions about access: contact us.