Developer Documentation

Tiraab AI API Reference

Integrate Somali-first artificial intelligence — dictionary, translation, chat, and embeddings — into your applications with a single API key.

Quickstart

Generate a Test key

Open Tiraab → Settings → Developer. Test keys are free and instant.

Send your first request

Use the key in Authorization: Bearer <key> or the X-API-Key header.

Go live

Upgrade to a paid Developer plan to issue live keys with production limits.

# 1. Set your key
export TIRAAB_KEY="tiraab_test_k_..."

# 2. Call the dictionary
curl -X POST https://ellpmofddofkknyexlmq.supabase.co/functions/v1/tiraab-api-dictionary \
  -H "X-API-Key: $TIRAAB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"word":"gabay"}'

Authentication

Every request must include your API key. Test keys (tiraab_test_k_…) use the sandbox and are free. Live keys (tiraab_live_k_…) hit production and require a paid plan.

# Option A — Bearer
Authorization: Bearer tiraab_live_k_XXXXXXXXXXXXXXXXXX

# Option B — X-API-Key header
X-API-Key: tiraab_live_k_XXXXXXXXXXXXXXXXXX

Endpoints

POST

https://ellpmofddofkknyexlmq.supabase.co/functions/v1/tiraab-api-chat

Conversational Somali AI grounded in the Suugaan literary archive. Streams grounded answers with citations.

Request body

{
  "messages": [
    { "role": "user", "content": "Muxuu yahay gabay?" }
  ],
  "temperature": 0.7
}

cURL example

curl -X POST https://ellpmofddofkknyexlmq.supabase.co/functions/v1/tiraab-api-chat \
  -H "X-API-Key: tiraab_live_k_..." \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Muxuu yahay gabay?"}]}'

Rate limits

Test environment

20 req/min

Free. No card required.

Live environment

120 req/min

Paid Developer plan required.

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Error format

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid or expired API key",
    "request_id": "b6d3..."
  }
}

401 missing_api_key

No key supplied

401 invalid_api_key

Bad or revoked key

402 plan_required

Live key needs a paid plan

429 rate_limited

Slow down; back off and retry

400 invalid_request

Malformed body

502 ai_error

Upstream AI provider failed

Coming soon

Speech-to-Text (STT)

Somali audio → transcript

Text-to-Speech (TTS)

Tiraab Abwaan voices

Suugaan Analysis

Meter, form, and attribution detection

Questions or feedback?

developers@biciid.org