Lexodus for developers

Quickstart

Fetch a journey without a key (anonymous requests get 100 a day per IP):

curl https://lexodus.app/api/v1/words/amen

With a key from your account, send it as a Bearer token:

curl -H "Authorization: Bearer $LEXODUS_KEY" \
  "https://lexodus.app/api/v1/search?q=yohanan"

From JavaScript (CORS is open for GET, so this works in a browser too — but keep keys on your server):

const res = await fetch("https://lexodus.app/api/v1/words?category=trade&limit=5", {
  headers: { Authorization: `Bearer ${process.env.LEXODUS_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const { data, next_cursor } = await res.json();
for (const w of data) console.log(w.headword, w.from.name, "→", w.to.name, w.confidence);

Lists are paged with limit and cursor: pass the next_cursor of one page as the cursor of the next, until it is null.

Keys and limits

Create, name and revoke keys on your account page. A key is shown in full once, when you create it; we store only a hash. ?api_key= also works for quick tests, but it ends up in logs and browser history, so use the header in real code.

Days are UTC. Every response says where you stand: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (Unix seconds of the next midnight UTC) and X-RateLimit-Scope (key or ip). Past the limit you get a 429 with Retry-After. Every answered request counts, errors and 304s included. Responses carry an ETag; send it back as If-None-Match to get a body-less 304 when nothing changed.

Reading the data

Each step after the first has a confidence for the link into it — certain, probable, possible or disputed — and each word has an overall grade equal to its weakest link. A disputed journey is in the atlas because the claim is popular, not because it is true; many such words carry a myth field explaining the wrong story. Forms marked * are reconstructed, not attested. Please keep the grades visible when you show a journey; the method page explains them.

Every word has a provenance. curated words are written and checked by us; extracted ones (and everything under /x) were generated from Wiktionary and nobody has reviewed them yet. Years with approx: true are estimated from the language’s period.

License. Extracted items are derived from Wiktionary and licensed CC BY-SA 4.0: each carries a license object, and if you reuse them you must show its attribution and share adaptations alike. The license of the curated words is to be decided by the owner; until one is published, ask before republishing them in bulk.

Errors

Errors are JSON, { "error": { "code": "…", "message": "…" } }, with a matching HTTP status. The API is read-only: methods other than GET (and OPTIONS, for CORS) get a bare 405.

Endpoints

All under /api/v1. The machine-readable version is /api/v1/openapi.json.