{"name":"Living Dictionaries Write API (v1)","what":"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.","start":"You are at the front door. Find your job in `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.","auth":{"header":"Authorization: Bearer ldk_…","key":"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.","scopes":"A key is read-only or read & write. Present it here and this page will name your dictionary and suggest where to start."},"tasks":[{"id":"import","title":"Import material into a dictionary","when":"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.","guides":[{"slug":"importing","url":"https://livingdictionaries.app/api/v1/guides/importing"},{"slug":"spreadsheets","url":"https://livingdictionaries.app/api/v1/guides/spreadsheets"},{"slug":"flex-lift","url":"https://livingdictionaries.app/api/v1/guides/flex-lift"},{"slug":"pdf-scans","url":"https://livingdictionaries.app/api/v1/guides/pdf-scans"},{"slug":"api-basics","url":"https://livingdictionaries.app/api/v1/guides/api-basics"}],"next":[{"method":"GET","url":"https://livingdictionaries.app/api/v1/guides/importing","why":"The mandatory runbook. Read it fully before anything else."},{"method":"GET","url":"https://livingdictionaries.app/api/v1/dictionaries/{id}/files","why":"The resources the dictionary team uploaded for you, each with its authoritative per-file import_instructions."},{"method":"GET","url":"https://livingdictionaries.app/api/v1/dictionaries/{id}","why":"The dictionary's gloss_languages + orthographies — the locale codes your glosses must be keyed by."}]},{"id":"cleanup","title":"Audit, correct, or normalize an existing dictionary","when":"The dictionary already has entries and your human wants them fixed, deduplicated, normalized, filled in, or reviewed — including undoing a bad earlier import.","guides":[{"slug":"cleanup","url":"https://livingdictionaries.app/api/v1/guides/cleanup"},{"slug":"api-basics","url":"https://livingdictionaries.app/api/v1/guides/api-basics"}],"next":[{"method":"GET","url":"https://livingdictionaries.app/api/v1/guides/cleanup","why":"Auditing recipes, the surgical single-row fixes, the review queue, and how to undo a bad import."},{"method":"GET","url":"https://livingdictionaries.app/api/v1/dictionaries/{id}/entries","why":"Page through the current data (add ?include=senses) before you change anything."}]},{"id":"consume","title":"Read the dictionary for an app, study tool, or analysis","when":"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.","guides":[{"slug":"consume","url":"https://livingdictionaries.app/api/v1/guides/consume"}],"next":[{"method":"GET","url":"https://livingdictionaries.app/api/v1/guides/consume","why":"Do NOT paginate the API for bulk reads — download the whole dictionary as one gzipped SQLite snapshot and query it locally."}]},{"id":"media","title":"Attach or fix audio, photos, and video","when":"Your human has recordings, images, or video to attach — or wants speaker attribution fixed, or karaoke word-timings generated for sentence/text audio.","guides":[{"slug":"media","url":"https://livingdictionaries.app/api/v1/guides/media"},{"slug":"api-basics","url":"https://livingdictionaries.app/api/v1/guides/api-basics"}],"next":[{"method":"GET","url":"https://livingdictionaries.app/api/v1/guides/media","why":"Upload shapes, the attribution rule (audio/video REQUIRE a speaker or a source), size caps, and karaoke timings."},{"method":"GET","url":"https://livingdictionaries.app/api/v1/dictionaries/{id}/speakers","why":"The speakers already on file — reuse one rather than inventing a placeholder."}]},{"id":"corpus","title":"Work with texts, interlinear glossing, or the grammar","when":"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.","guides":[{"slug":"corpus","url":"https://livingdictionaries.app/api/v1/guides/corpus"},{"slug":"api-basics","url":"https://livingdictionaries.app/api/v1/guides/api-basics"}],"next":[{"method":"GET","url":"https://livingdictionaries.app/api/v1/guides/corpus","why":"Texts vs. example sentences, the token/gloss alignment shape, and the grammar-section tree."},{"method":"GET","url":"https://livingdictionaries.app/api/v1/dictionaries/{id}/texts","why":"The texts already in this dictionary."}]},{"id":"ask-us","title":"Ask the Living Dictionaries team","when":"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.","guides":[],"next":[{"method":"POST","url":"https://livingdictionaries.app/api/v1/dictionaries/{id}/feedback","why":"Send `{ message }` straight to the team (works with read OR write keys). Relay the response's note back to your human."},{"method":"GET","url":"https://livingdictionaries.app/api/v1/dictionaries/{id}/conversations","why":"If you are working an import request, its conversation is where you post messages, questions, and the final report."}]}],"guides_index":"https://livingdictionaries.app/api/v1/guides","reference":{"note":"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.","index":"https://livingdictionaries.app/api/v1/openapi.json","by_group":"https://livingdictionaries.app/api/v1/openapi.json?tag=entries","full":"https://livingdictionaries.app/api/v1/openapi.json?view=full","groups":["start","dictionary","entries","media","texts","grammar","relationships","cognate-sets","places","dialects","tags","speakers","sources","files","conversations","guides","orthographies","featured-entries","suggestions","alignment","feedback"]}}