API Documentation

Reference for stored English vocabulary, lesson, and assessment endpoints. One API key, structured JSON responses.

SDKs

Install the official SDK for your language:

npm install wordorb

pip install wordorb

Both SDKs work without an API key for basic usage. Add a key for higher rate limits.

// JavaScript
import { WordOrb } from 'wordorb'
const orb = new WordOrb()
const word = await orb.lookup('courage')

# Python
from wordorb import WordOrb
orb = WordOrb()
word = orb.lookup("courage")

Authentication

Most read endpoints work without an API key (200 calls/day per IP). For production use, get a free key at /pricing for 10,000 calls/day.

Authorization: Bearer wo_YOUR_API_KEY

GET /api/word/courage?key=wo_YOUR_API_KEY

API keys start with wo_. One key works across all three products.

Rate Limits

Starter is $9/month with metered billing: 150,000 calls are included per UTC calendar month, then $0.0006 per additional call. This allowance resets on the first day of the month, separately from your subscription renewal. When metered billing is active, the displayed 5,000-call daily baseline does not block additional calls. See your dashboard for usage and the pricing page for other plans.

Free includes 10,000 calls/day, a 10-request/minute limit and up to 10 words per batch. Paid plans support up to 50 words per batch and remove the Free plan's 10-request/minute cap. The Starter included monthly volume is lower than Free's potential monthly volume; choose it for the features you need and review its overage rate. Daily limits reset at midnight UTC; Starter included usage resets monthly. A Retry-After header indicates when a limited request can be retried.

Check current usage with GET /api/keys/me.

Word Orb

Stored, AI-assisted records for English headwords. Translations span 47 language codes across a subset of the headwords; field and language coverage varies by word.

Look up a word Try it →

# Look up a word
curl -H "Authorization: Bearer wo_YOUR_KEY" \
  https://wordorb.ai/api/word/courage

// JavaScript (fetch)
const res = await fetch("https://wordorb.ai/api/word/courage", {
  headers: { "Authorization": "Bearer wo_YOUR_KEY" }
});
const word = await res.json();
console.log(word.def);    // definition
console.log(word.langs);  // available translations; may be empty

# Python (requests)
import requests

r = requests.get("https://wordorb.ai/api/word/courage",
    headers={"Authorization": "Bearer wo_YOUR_KEY"})
word = r.json()
print(word["def"])    # definition
print(word["langs"])  # available translations; may be empty

List all words

curl -H "Authorization: Bearer wo_YOUR_KEY" https://wordorb.ai/api/words

Try a stored-only check on your own vocabulary before integrating. It shows missing records and fields; paying does not change content coverage.

Batch word lookup

# Evaluate stored words
curl -X POST -H "Authorization: Bearer wo_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"words":["courage","wisdom","resilience"]}' \
  https://wordorb.ai/api/words/batch

Lesson Orb

Structured lesson infrastructure. structured daily lessons across 19 lesson languages, 4 tracks, 3 age groups, and 10 teaching archetypes.

Get a lesson Try it →

curl -H "Authorization: Bearer wo_YOUR_KEY" \
  "https://wordorb.ai/api/lesson?day=47&track=learn&age=adult&archetype=explorer"

const res = await fetch(
  "https://wordorb.ai/api/lesson?day=47&track=learn&age=adult&archetype=explorer",
  { headers: { "Authorization": "Bearer wo_YOUR_KEY" } }
);
const lesson = await res.json();
console.log(lesson.phases.hook);    // opening hook
console.log(lesson.phases.wisdom);  // closing wisdom

r = requests.get("https://wordorb.ai/api/lesson",
    params={"day": 47, "track": "learn", "archetype": "explorer"},
    headers={"Authorization": "Bearer wo_YOUR_KEY"})
lesson = r.json()
# lesson["phases"]["hook"], ["story"], ["wonder"], ["action"], ["wisdom"]

List lessons

Reference data

Quiz Orb

Assessment infrastructure. 45,916 interactions across 6 question types: quiz, mc (multiple choice), tf (true/false), ab (comparison), open (open-ended), reflection.

Get quiz by day

curl -H "Authorization: Bearer wo_YOUR_KEY" \
  "https://wordorb.ai/api/quiz?day=47&track=learn"

Random questions

Batch questions

Knowledge Graph

Stored connections link a subset of English headwords to lesson content. Use the graph to check available word-to-lesson links; a headword may have no linked lessons or assessments.

Word → Lessons

curl -H "Authorization: Bearer wo_YOUR_KEY" \
  "https://wordorb.ai/api/graph/word?word=courage"

# Returns: { word, appears_in: 15, lessons: [{ day, track, phase, context, importance }...] }

Lesson → Words

Account

Check usage

curl -H "Authorization: Bearer wo_YOUR_KEY" https://wordorb.ai/api/keys/me

# Returns: { key, email, tier, daily_limit, calls_today, calls_total, remaining_today }

Sign up

curl -X POST -H "Content-Type: application/json" \
  -d '{"email":"you@company.com"}' \
  https://wordorb.ai/api/signup

MCP Server

Word Orb exposes a Model Context Protocol server. One config line connects to Claude Desktop, ChatGPT, Cursor, Gemini, and any MCP-compatible AI client.

// Add to your MCP client config:
{
  "mcpServers": {
    "word-orb": {
      "url": "https://wordorb.ai/mcp"
    }
  }
}

The MCP server exposes all three products as tools that AI agents can discover and call automatically.

Error Codes

All errors return JSON: { "error": "message", "code": "error_code" }