Developers

FSI Customer API

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

Entitlement-gated access to Bantu Full Syllable Inventories. Your token decides scope: Evaluation tokens reach the 2-language evaluation set (Bemba + Nyanja) with capped sample audio; Founding Partner tokens reach all Released FSIs with full consent-gated audio and bulk selection.

Public self-test — no key, no login

Any agent can run the two-minute self-test over plain HTTP or MCP with no token. Public callers get rates + counts; the inventory is never returned (so nothing licensed leaks). An entitled Bearer adds the full matched / missing / fabricated breakdown.

# 1) get the prompt curl "http://fsi.bantunomics.com/api/v1/self-test/challenge?language=bem" # 2) score what your model produced (no key) curl -X POST "http://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

Authentication

All data endpoints require a Bearer token. Evaluation keys are issued to allow-listed AI labs via an emailed activation link; Founding Partner keys are issued on license.

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

Scopes

evaluation — allowed_isos = ["bem", "nya"], audio = sample (capped), no bulk, 30-day expiry.
founding_partner — all Released FSIs, full audio, bulk selection, no expiry.

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

Endpoints

GET /api/v1/ # API root (public) GET /api/v1/whoami # tier, languages, audio level, quota GET /api/v1/languages # languages this key may access GET /api/v1/coverage # per-language coverage matrix (scoped) GET /api/v1/fsi/{iso}?view=both # one FSI (inventory | equation | both) GET /api/v1/fsi?iso=&zone=&country=&scope=all&limit=&offset= # list FSIs by selector (paged) GET /api/v1/fsi/{iso}/audio # consent-gated audio manifest (opaque tokens) GET /api/v1/usage # usage + remaining daily quota

Selection grammar (`/fsi`)

iso=bem,nya,toi — explicit list
zone=M — Guthrie zone letter
country=Zambia — by country
scope=all — every Released FSI the token may access
view=inventory|equation|both · limit / offset for paging

The audio token contract

Audio is never returned as a storage path. /fsi/{iso}/audio returns per-syllable opaque signed tokens; play one by GETting /audio/clip/{token}. Tokens are time-limited and tamper-evident; a bad signature or a raw path returns 404. The following never appear in any response: gcs_path, recorded_by, user_id, filename_stem, sequence numbers. See Security and Provenance & consent.

Rate limits & errors

Per-token daily quota (evaluation default 500/day; Founding Partner uncapped).
401 missing/invalid token · 403 language not in entitlement · 404 not found · 429 quota exceeded.
Every authenticated call is logged for audit + abuse detection.

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": "http://fsi.bantunomics.com/mcp"} # add an Authorization: Bearer <token> header for the licensed tiers — omit it for the public tools

Public tools (no token needed): fsi_challenge(language) and fsi_self_test(language, your_syllables, model_name?) — the same no-leak self-test as above.

Token-scoped tools (Evaluation → Bemba + Nyanja; Pilot → agreed set; Founding Partner → all 459): whoami, list_languages, search_languages, get_fsi, get_voices, and (Pilot+) get_revision_history, get_provenance, get_benchmark_kit.

Request a key: contact us.