Programmatic read/write access to ONE Living Dictionary — a language community's record of its words, sentences, texts, and recordings. An agent can do anything a human editor can.
tasks below, read its FIRST guide before you do anything else, then use the endpoint reference. Reading the reference first is the wrong order — the guides carry the judgement calls (what to ask your human, what not to guess, how not to corrupt a language's data), and the reference only carries field shapes.Authorization: Bearer ldk_…
Your human mints the key on their dictionary's Agents page and gives it to you along with the dictionary id (the <id> in its web URL). A key works on exactly one dictionary. A key is read-only or read & write. Present it here and this page will name your dictionary and suggest where to start.
Your human has source material — a spreadsheet, a FLEx/LIFT/Toolbox export, a scanned PDF dictionary, a word list, field notes — that should become entries. THE MOST COMMON JOB. Do not start writing entries until you have read the importing guide; it front-loads a whole data-preparation phase (inspect, question the human, stage locally, review by eye, get sign-off) that happens BEFORE your first write.
Read first: importing · spreadsheets · flex-lift · pdf-scans · api-basics
GET /api/v1/guides/importingThe mandatory runbook. Read it fully before anything else.GET /api/v1/dictionaries/{id}/filesThe resources the dictionary team uploaded for you, each with its authoritative per-file import_instructions.GET /api/v1/dictionaries/{id}The dictionary's gloss_languages + orthographies — the locale codes your glosses must be keyed by.The dictionary already has entries and your human wants them fixed, deduplicated, normalized, filled in, or reviewed — including undoing a bad earlier import.
Read first: cleanup · api-basics
GET /api/v1/guides/cleanupAuditing recipes, the surgical single-row fixes, the review queue, and how to undo a bad import.GET /api/v1/dictionaries/{id}/entriesPage through the current data (add ?include=senses) before you change anything.You are building or feeding something that READS this dictionary — a language-learning app, a flashcard deck, a corpus analysis, a mirror — and never needs to write.
Read first: consume
GET /api/v1/guides/consumeDo NOT paginate the API for bulk reads — download the whole dictionary as one gzipped SQLite snapshot and query it locally.Your human has recordings, images, or video to attach — or wants speaker attribution fixed, or karaoke word-timings generated for sentence/text audio.
Read first: media · api-basics
GET /api/v1/guides/mediaUpload shapes, the attribution rule (audio/video REQUIRE a speaker or a source), size caps, and karaoke timings.GET /api/v1/dictionaries/{id}/speakersThe speakers already on file — reuse one rather than inventing a placeholder.Your human is documenting connected material rather than isolated words — stories/passages with ordered sentences, interlinear glossed text (IGT), or the dictionary's structured grammar description.
Read first: corpus · api-basics
GET /api/v1/guides/corpusTexts vs. example sentences, the token/gloss alignment shape, and the grammar-section tree.GET /api/v1/dictionaries/{id}/textsThe texts already in this dictionary.You hit a wall: a field that does not exist, a bug, an awkward shape, or a decision only a human can make. Ask us rather than inventing a workaround — this genuinely shapes what we build next.
POST /api/v1/dictionaries/{id}/feedbackSend { message } straight to the team (works with read OR write keys). Relay the response's note back to your human.GET /api/v1/dictionaries/{id}/conversationsIf you are working an import request, its conversation is where you post messages, questions, and the final report.Every playbook, listed with its blurb: https://livingdictionaries.app/api/v1/guides — each one is plain markdown at /api/v1/guides/{slug}.
Read your task's guide FIRST. Then fetch only the group you need — the full spec is ~200KB and you almost never want all of it.
Groups: start dictionary entries media texts grammar relationships cognate-sets dialects tags speakers sources files conversations guides orthographies featured-entries suggestions alignment feedback
This page is the human rendering of the JSON an agent receives here. Fetch it with Accept: application/json (or add ?format=json) to see exactly what your agent sees.