Quickstart
Make your first request to the Arabic Words API in under 5 minutes.
Create an account and get your API key
Head to the KalimaLab dashboard and create a free account. Once signed in, navigate to Dashboard → API Keys and click "Create API Key".
Copy your key immediately
Your API key is shown only once. Store it in a password manager or .env file right away.
Your key will look like this: klmt_live_••••••••••••••••••••
Install the SDK
Install the official @kalimalab/sdk package. Works in Node.js, Deno, Bun, and any modern JavaScript runtime.
npm install @kalimalab/sdkpnpm add @kalimalab/sdkyarn add @kalimalab/sdkbun add @kalimalab/sdkThe SDK requires Node.js 18+ or any runtime with native fetch support.
Make your first request
Add your API key to environment variables, then write your first script:
KALIMALAB_API_KEY=klmt_live_your_key_hereimport { KalimaLab } from '@kalimalab/sdk'const client = new KalimaLab({ apiKey: process.env.KALIMALAB_API_KEY! })// Get a random Arabic wordconst word = await client.words.random()console.log(word.arabic) // e.g. "كَتَبَ"console.log(word.meaning_en) // "to write"console.log(word.root) // "كتب"console.log(word.pattern) // "فَعَلَ"// Search for 5-letter nounsconst results = await client.words.search({ letters: 5, pos: 'noun', limit: 10 })console.log(`Found ${results.meta.total} words`)results.data.forEach((w) => console.log(w.arabic))ℹUsing the REST API directly?
Explore the response
Here is what a typical word response looks like. Every word object includes linguistic metadata:
{ "data": { "id": "word_01j9abc123", "arabic": "كَتَبَ", "root": "كتب", "pattern": "فَعَلَ", "pos": "verb", "meaning_en": "to write", "meaning_ar": "قام بالكتابة", "transliteration": "kataba", "frequency_rank": 143, "example_sentence": "كَتَبَ الطالبُ الدرسَ" }, "error": null, "meta": { "requestId": "req_01j9xyz...", "responseTimeMs": 8 }}arabicThe word with full diacritics.rootThe Arabic root — trilateral or quadrilateral base.patternThe morphological pattern (وزن) in verb form.posPart of speech: verb, noun, adjective, or particle.transliterationALA-LC transliteration.frequency_rankUsage frequency rank (1 = most frequent).Filtered search response
When filtering words — for example by letter count or root — the API returns a paginated list. This is the full shape of a GET /v1/words?letters=3&root=كتب response:
{ "data": [ { "id": "wrd_001", "word": "كَتَبَ", "meaning_en": "to write", "meaning_ar": "قام بفعل الكتابة", "part_of_speech": "verb", "letter_count": 3, "root": "كتب", "pattern": "فَعَلَ", "frequency_rank": 47, "is_verb": true } ], "error": null, "meta": { "requestId": "req_abc123", "responseTimeMs": 12, "page": 1, "limit": 20, "total": 47, "totalPages": 3 }}meta.pageCurrent page number (starts at 1).meta.limitNumber of results per page (up to 100).meta.totalTotal number of matching words across all pages.meta.totalPagesTotal pages available for this query.meta.responseTimeMsServer-side processing time in milliseconds.Error handling
Always check that the response succeeded before using data. The two most common errors are 401 Unauthorized (wrong or missing key) and 429 Too Many Requests (rate limit exceeded).
import { KalimaLab, AuthError, RateLimitError } from '@kalimalab/sdk'const client = new KalimaLab({ apiKey: process.env.KALIMALAB_API_KEY! })async function safeSearch(letters: number, root: string) { try { const results = await client.words.search({ letters, root, limit: 20 }) return results.data } catch (err) { if (err instanceof AuthError) { // 401 — key is missing, invalid, or revoked console.error('Check your KALIMALAB_API_KEY environment variable.') throw err } if (err instanceof RateLimitError) { // 429 — too many requests; wait until the limit resets const waitMs = err.resetAt.getTime() - Date.now() console.warn(`Rate limited. Retrying in ${Math.ceil(waitMs / 1000)}s.`) await new Promise((r) => setTimeout(r, waitMs)) return safeSearch(letters, root) // retry once } throw err // unexpected error — let it bubble up }}const words = await safeSearch(3, 'كتب')console.log(words)ℹFull error reference
Next steps
Learn about API key security, rotation, and environment best practices.
Explore every method in the TypeScript SDK with full parameter tables.
Understand plan limits and how to handle 429 errors gracefully.
Try any endpoint in the browser with your real API key.
You're all set! If you run into any issues, contact support.