Developer Documentation

API & MCP Integration

Access BantuNomics data programmatically via REST API or integrate directly into Claude, GPT, and other AI assistants via the Model Context Protocol (MCP).

REST API

Endpoints

GET /api/v1/conjugate
GET /api/v1/analyze
GET /api/v1/tonal-pairs
GET /api/v1/languages
GET /api/v1/syllables/{lang}
POST /api/v1/batch-generate

Authentication

API key authentication via header:

Authorization: Bearer <your-api-key>

Response Format

All responses return JSON with consistent schema:

{"status": "ok", "data": [...], "meta": {"count": 100, "page": 1}}

Example: Conjugate a Verb

# Python example
import requests

response = requests.get(
    "https://api.bantunomics.com/v1/conjugate",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "language": "bem",
        "root": "bomb",
        "subject": "ba",
        "tense": "present_progressive",
        "include_tones": True
    }
)

data = response.json()
# {
#   "surface_form": "balebomba",
#   "slots": { ... },
#   "tonal_analysis": { ... },
#   "english": "they are working"
# }

MCP Integration

The BantuNomics MCP server exposes 21 tools across 6 groups, letting AI assistants directly query morphological data, generate conjugations, and access tonal analysis.

Conjugation Tools
conjugate_verb
batch_conjugate
get_paradigm
Analysis Tools
analyze_form
decompose_morphemes
get_tonal_analysis
Data Access Tools
get_language_info
list_languages
get_syllable_inventory
Tonal Tools
get_tonal_pairs
predict_tones
get_minimal_pairs
HFST Tools
hfst_analyze
hfst_generate
hfst_list_models
Utility Tools
search_roots
get_cartridge_info
validate_form

Claude Desktop Configuration

{
  "mcpServers": {
    "bantunomics": {
      "command": "npx",
      "args": ["-y", "@bantunomics/mcp-server"],
      "env": {
        "BANTUNOMICS_API_KEY": "your-api-key"
      }
    }
  }
}

Rate Limits by Tier

Tier Requests/Day Batch Size MCP Access
Evaluation 100 10 —
Academic 500 50 Read-only
Startup 5,000 500 Full
Enterprise Unlimited Unlimited Full + dedicated