Goal: a running server and a real response. About five minutes.
- Node 20 or newer. Check with
node --version. - pnpm. If you do not have it:
npm install -g pnpm.
Nothing else. No database server, no Docker, no admin rights. The API stores everything in a single SQLite file.
pnpm installpnpm bootstrap --liteThis creates the tables and loads a small starter set of words (~3 MB) from DEXonline's freely licensed database dump.
Three ways to run it, pick one:
| Command | What it does | When |
|---|---|---|
pnpm bootstrap --no-seed |
Tables only, no words | Fastest. Words are fetched live on first request. |
pnpm bootstrap --lite |
Tables + ~8,000 senses | Recommended. Good balance. |
pnpm bootstrap --full |
Tables + the whole dictionary | Several hundred MB. Offline use. |
You can change your mind later; re-run with a different flag.
pnpm devYou should see it listening on port 3000. Leave this terminal running.
Open a second terminal:
curl 'localhost:3000/v1/healthz'Expected:
{ "status": "ok", "uptime": 0.12, "db": "ok", "breakers": {} }If you see that, everything works. Now look up a word:
curl 'localhost:3000/v1/word/casă'That is a lot of JSON. Install jq to read it
comfortably (brew install jq), then:
curl -s 'localhost:3000/v1/word/casă' | jq '.entries[0].senses[0].text'"Clădire care servește drept locuință."
curl -s 'localhost:3000/v1/tts/casă' -o casa.ogaPlay casa.oga with anything (afplay casa.oga on macOS). That is a real human
recording from Wikimedia Commons. See Pronunciation for
how the voice is chosen and how to change it.
Open http://localhost:3000/docs in a browser for the interactive reference.
casă contains ă, which is not an ASCII character. curl handles it, but if
a tool complains, percent-encode it: cas%C4%83.
You can also just type it without diacritics: casa finds casă: see
Search.
- Concepts: the vocabulary used everywhere else
- Word lookup: the main endpoint, in full
- Troubleshooting: if something above failed