Ulimi API Docs — Developer Reference

Ulimi API

A living, community-contributed dictionary of indigenous African words across languages, ethnic groups, and pre-colonial contexts. Free to use. Open source.

Base URLhttps://ulimi.dev/api/v1

Open API — All read endpoints are public and require no authentication. Submit endpoints (POST) accept anonymous contributions but authenticated users get contribution history.

Concepts

A concept is the core entity — the idea or thing, language-agnostic. Each concept has many translations across different languages and ethnic groups.

GET/concepts/List all verified concepts

Query parameters

categoryoptionalstringFilter by category slug — e.g. animals, culture

searchoptionalstringFilter by English term. For cross-language search use /search/ instead.

pageoptionalintegerPage number. Default: 1. Page size: 20.

curl

curl https://ulimi.dev/api/v1/concepts/
curl https://ulimi.dev/api/v1/concepts/?category=animals

GET/concepts/{slug}/Get a concept with all translations

Path parameters

slugrequiredstringURL-safe concept slug — e.g. lion, ubuntu

response · 200 OK

{
  "slug": "ubuntu",
  "english_term": "Ubuntu / Humanity",
  "category": "culture",
  "precolonial_context": "A pan-African philosophy...",
  "translations": [
    {
      "word": "Ubuntu",
      "phonetic": "oo-BOON-too",
      "language": { "code": "zu", "name": "Zulu" },
      "ethnic_group": { "name": "Zulu", "country_iso2": "ZA" }
    }
  ]
}

GET/concepts/search/Cross-language search — any word, any language

This is the key endpoint. Unlike /concepts/?search=, this searches across ALL translation words simultaneously — so searching “simba” finds the Lion concept just as searching “lion” does.

Query parameters

qrequiredstringThe search term. Minimum 2 characters.

categoryoptionalstringNarrow results to a category.

curl

curl "https://ulimi.dev/api/v1/concepts/search/?q=simba"
curl "https://ulimi.dev/api/v1/concepts/search/?q=ubuntu"

Languages

GET/languages/List all supported languages

curl

curl https://ulimi.dev/api/v1/languages/

Contributions

Anyone can submit new words or corrections. All submissions enter a pending state, can be upvoted by the community, and go live only after admin review.

POST/contributions/Submit a new word, translation, or correction

Three contribution types

new_concept · new_translation · correction

// Type 1: Brand new concept
{
  "contribution_type": "new_concept",
  "contributor_name": "Achieng Otieno",
  "contributor_note": "Native Luo speaker from Kisumu",
  "proposed_data": {
    "english_term": "Baobab tree",
    "category": "food",
    "word": "Uyombo",
    "language_code": "luo",
    "is_precolonial": true
  }
}

// Type 2: New translation for existing concept
{
  "contribution_type": "new_translation",
  "concept": "<concept-uuid>",
  "proposed_data": {
    "word": "Gyata",
    "language_code": "tw"
  }
}

// Type 3: Correction
{
  "contribution_type": "correction",
  "existing_translation": "<translation-uuid>",
  "proposed_data": {
    "phonetic": { "old": "SIM-ba", "new": "SIM-bah" }
  }
}

POST/contributions/{id}/vote/Upvote or flag a pending contribution

body

{ "vote_type": "up" }   // or "flag"

Slug	Label
`animals`	Animals
`food`	Food & Plants
`nature`	Nature
`family`	Family & Social
`culture`	Culture & Governance
`body`	Body & Health
`spiritual`	Spiritual & Ceremonial
`tools`	Tools & Technology
`geography`	Geography & Place