EN YO
Join

Yoruba.tech

Developer docs

Call the Àtùmọ̀ Tech dictionary, embed search on your site, and meter usage with prepaid credits.

Open developer apps OpenAPI

Start here

  1. Create an app Get a Client ID and API key from the developer portal. New apps include 1,000 starter credits.
  2. Call the API Send Authorization: Bearer yt_… (or X-API-Key). Each successful request spends credits.
  3. Watch balance Use response headers, GET /credits.php, or the app page chart. Top up with Paystack when needed.

Auth & scopes

Every API request needs the secret key shown once when you create or regenerate an app.

Authorization: Bearer yt_…

or

X-API-Key: yt_…

Scopes

  • dictionary:read
  • dictionary:write

Credits

Prepaid pay-as-you-go. Empty balance → 402 with top_up_url.

Starter grant
1,000 credits
API cost
1 / request
Embed cost
1 / search
Top-up
Paystack on the app page

Packs

  • Starter 2,000 credits ₦1,000
  • Growth 10,000 credits ₦4,000
  • Scale 50,000 credits ₦15,000

Response headers

Included on billed calls. Also readable from browser JS via CORS expose headers.

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
X-Credit-Balance
X-Credit-Cost
X-Commercial-Use

Endpoints

GET /api/v1/credits.php

Balance and 7-day usage. Does not spend credits and does not tick the hourly throttle. Does not spend credits

curl -H "Authorization: Bearer yt_…" \
  "https://techinyoruba.ai/api/v1/credits.php"

Returns credit_balance, costs, and usage (spent_today, spent_7d, API vs embed, runway estimate, by_day).

GET /api/v1/dictionary.php

Requires dictionary:read. Search approved terms.

ParamDescription
qSearch English or Yoruba
categoryCategory label or slug
slugExact term slug (at most one)
letterA–Z filter on English term
limitMax results (default 100, max 500)

Each item includes id, slug, url, english, yoruba, definitions, category, example, and media URLs.

curl -H "Authorization: Bearer yt_…" \
  "https://techinyoruba.ai/api/v1/dictionary.php?q=api&limit=10"
curl -H "Authorization: Bearer yt_…" \
  "https://techinyoruba.ai/api/v1/dictionary.php?category=AI&letter=M&limit=20"

POST /api/v1/suggest.php

Requires dictionary:write. Queues an edit suggestion for staff review.

curl -X POST -H "Authorization: Bearer yt_…" -H "Content-Type: application/json" \
  -d '{"slug":"cloud","suggested_yoruba":"ìkùràwọ́","notes":"tone fix"}' \
  "https://techinyoruba.ai/api/v1/suggest.php"

Whitelists

Optional per app. Leave empty to allow all.

IP whitelist
Exact IPs or CIDR (e.g. 203.0.113.10, 198.51.100.0/24). Others get 403.
Origin whitelist
Browser origins or hosts (e.g. https://app.example.com, *.example.com). Required for production embeds. Server-to-server calls without Origin are still allowed.

Partner webhooks

Configure HTTPS endpoints on an app’s detail page. Deliveries include:

X-YorubaTech-Event: dictionary.term.approved
X-YorubaTech-Signature: sha256=…

Signature is HMAC-SHA256 of the raw JSON body using the webhook secret.

  • dictionary.term.approved
  • dictionary.suggestion.accepted
  • dictionary.term.submitted

Dictionary embed

Add Yoruba.tech dictionary search to your site with your developer app client ID.

Embed searches use the same prepaid credits (1 per search). Add your site origin under the app’s origin whitelist for production.

Quick start

Paste this before the closing body tag. Use your developer app client ID.

<script src="https://techinyoruba.ai/embed/dictionary.js"
        data-base="https://techinyoruba.ai"
        data-client-id="app_YOUR_CLIENT_ID"
        data-container="yt-dict-embed"
        defer></script>
<div id="yt-dict-embed"></div>

Create a developer app to get your client ID: Developers.

Options

AttributeDescription
data-client-id Required. Your developer app client ID (app_…).
data-base Yoruba.tech site URL (defaults from script src).
data-container DOM id for the widget container.

Search endpoint: GET https://techinyoruba.ai/embed/search?client_id=…&q=… (CORS + origin whitelist).

Live demo

Sign in and create a developer app to try the live demo here.

Sign in

Errors

{"ok": false, "error": "…"}
StatusMeaning
401Missing or invalid API key
403Missing scope, revoked app, or whitelist block
402Insufficient credits (includes top_up_url)
429Hourly safety throttle exceeded

Download openapi.yaml for machine-readable schemas.