{"openapi":"3.1.0","tags":[{"name":"start","description":"The front door (`GET /api/v1`) — the task-routing document you should have read before this spec."},{"name":"dictionary","description":"Read the dictionary's metadata (gloss languages, orthographies, entry count) — call this first — and write its own catalog fields: the About prose, citation, where it is spoken, language codes, and the home-page cover photo."},{"name":"entries","description":"Create, read, update, and delete entries, their senses, and example sentences."},{"name":"media","description":"Attach or remove audio, photos, and videos on entries, senses, sentences, and texts."},{"name":"texts","description":"Connected passages/stories with their own ordered sentences, `…/texts/collections` hierarchical grouping (series › book › chapter), plus `…/texts/{textId}/tags` classification (genre/motif/tale-type)."},{"name":"grammar","description":"Structured, hierarchical grammar sections: parallel-language markdown prose linked to entries/senses, example sentences by reference, clause-template slots, usage conditions, and the glossing-abbreviations legend."},{"name":"relationships","description":"Typed links between two entries (optionally narrowed to senses), plus the per-dictionary custom-type registry (`…/relationship-types`)."},{"name":"cognate-sets","description":"Cognate sets (\"word families\"): N-ary groups of entries descending from one ancestor form, with the reconstruction, its level, sources, and per-member uncertainty."},{"name":"places","description":"Places: named, located localities (village, town, county, river valley…) with coordinate precision and nesting, linked to the entries attested there, the texts recorded there, the dialects spoken there, and the speakers who live there — the data behind map views."},{"name":"dialects","description":"Dialect labels and their areal-extent geometry."},{"name":"tags","description":"Entry tags."},{"name":"speakers","description":"Speaker records for audio/video attribution."},{"name":"sources","description":"The citation/source registry entries and sentences reference by slug."},{"name":"files","description":"Uploaded import resources (original spreadsheets, FLEx/LIFT exports, PDF scans…) with per-file import instructions — list, download, upload, link to sources. Write scope required for everything (never public)."},{"name":"conversations","description":"Import conversations: the durable page where a dictionary manager and the Living Dictionaries team work one import request together — claim/resolve the job, post messages, file the report artifact, and ask answerable questions."},{"name":"guides","description":"The task playbooks (markdown) — the primary documentation layer: api-basics, the import runbook + its format guides, cleanup, consume, media, corpus."},{"name":"orthographies","description":"Alternate writing systems."},{"name":"featured-entries","description":"The starred entries shown on the dictionary home page."},{"name":"suggestions","description":"The word→entry matching review queue: unmatched/ambiguous/ignored forms aggregated across all tokenized sentences, plus per-token and form-wide review actions."},{"name":"alignment","description":"Forced alignment: auto-generate karaoke word-timings for text/sentence audio from the dictionary's tokenized sentences (requires team-configured romanization)."},{"name":"feedback","description":"Send feedback/requests to the Living Dictionaries team."}],"info":{"title":"Living Dictionaries Write API","version":"1.0.0","description":"COMPACT INDEX of the Living Dictionaries Write API (the default view). Each path lists its method(s), one-line summary, and tag.\nFIRST, THOUGH: `GET /api/v1` is the front door — a small doc that routes you to the GUIDE for the job you are doing. Read that guide before this reference; it carries the judgement calls, this carries only field shapes. `GET /api/v1/guides/api-basics` covers auth, multilingual fields, idempotency, errors, and limits.\nEvery request needs `Authorization: Bearer ldk_…` (an API key scoped to one dictionary).\nFetch the operations WITH full request/response schemas for a group via `?tag=<name>` (e.g. `openapi.json?tag=entries`); the tag names are in the top-level `tags` list. `?view=full` returns the complete ~200KB document. `schema_names` lists every component schema."},"servers":[{"url":"https://livingdictionaries.app"}],"paths":{"/api/v1/dictionaries/{id}/entries/{entryId}/audio":{"post":{"summary":"Attach audio to an entry","tags":["media"]}},"/api/v1/dictionaries/{id}/entries/{entryId}/audio/{audioId}":{"delete":{"summary":"Delete a audio from this entry","tags":["media"]}},"/api/v1/dictionaries/{id}/senses/{senseId}/photos":{"post":{"summary":"Attach a photo to a sense","tags":["media"]}},"/api/v1/dictionaries/{id}/senses/{senseId}/photos/{photoId}":{"delete":{"summary":"Delete a photo from this sense","tags":["media"]}},"/api/v1/dictionaries/{id}/senses/{senseId}/videos":{"post":{"summary":"Attach a video to a sense","tags":["media"]}},"/api/v1/dictionaries/{id}/senses/{senseId}/videos/{videoId}":{"delete":{"summary":"Delete a video from this sense","tags":["media"]}},"/api/v1/dictionaries/{id}/sentences/{sentenceId}/audio":{"post":{"summary":"Attach audio to a sentence","tags":["media"]}},"/api/v1/dictionaries/{id}/sentences/{sentenceId}/audio/{audioId}":{"delete":{"summary":"Delete a audio from this sentence","tags":["media"]},"patch":{"summary":"Set/update an audio's timings on this sentence","tags":["media"]}},"/api/v1/dictionaries/{id}/sentences/{sentenceId}/photos":{"post":{"summary":"Attach a photo to a sentence","tags":["media"]}},"/api/v1/dictionaries/{id}/sentences/{sentenceId}/photos/{photoId}":{"delete":{"summary":"Delete a photo from this sentence","tags":["media"]}},"/api/v1/dictionaries/{id}/sentences/{sentenceId}/videos":{"post":{"summary":"Attach a video to a sentence","tags":["media"]}},"/api/v1/dictionaries/{id}/sentences/{sentenceId}/videos/{videoId}":{"delete":{"summary":"Delete a video from this sentence","tags":["media"]}},"/api/v1/dictionaries/{id}/texts/{textId}/audio":{"post":{"summary":"Attach audio to a text","tags":["media"]}},"/api/v1/dictionaries/{id}/texts/{textId}/audio/{audioId}":{"delete":{"summary":"Delete a audio from this text","tags":["media"]},"patch":{"summary":"Set/update an audio's timings on this text","tags":["media"]}},"/api/v1/dictionaries/{id}/texts/{textId}/videos":{"post":{"summary":"Attach a video to a text","tags":["media"]}},"/api/v1/dictionaries/{id}/texts/{textId}/videos/{videoId}":{"delete":{"summary":"Delete a video from this text","tags":["media"]}},"/api/v1/dictionaries/{id}/texts/{textId}/audio/{audioId}/align":{"post":{"summary":"Auto-align this text's audio (forced alignment)","tags":["alignment"]}},"/api/v1/dictionaries/{id}/sentences/{sentenceId}/audio/{audioId}/align":{"post":{"summary":"Auto-align this sentence's audio (forced alignment)","tags":["alignment"]}},"/api/v1/dictionaries/{id}/align-jobs/{jobId}":{"get":{"summary":"Poll an alignment job","tags":["alignment"]}},"/api/v1/dictionaries/{id}/media/{storagePath}":{"get":{"summary":"Download media bytes by storage_path","tags":["media"]}},"/api/v1/dictionaries/{id}":{"get":{"summary":"Dictionary metadata","tags":["dictionary"]},"patch":{"summary":"Update the dictionary's catalog fields","tags":["dictionary"]}},"/api/v1/dictionaries/{id}/cover-image":{"post":{"summary":"Set the dictionary cover photo","tags":["dictionary"]},"delete":{"summary":"Remove the dictionary cover photo","tags":["dictionary"]}},"/api/v1/dictionaries/{id}/entries":{"get":{"summary":"List/filter entries","tags":["entries"]},"post":{"summary":"Create entries (bulk)","tags":["entries"]}},"/api/v1/dictionaries/{id}/entries/{entryId}":{"get":{"summary":"Read one entry (full nested)","tags":["entries"]},"patch":{"summary":"Update an entry (field-merge)","tags":["entries"]},"delete":{"summary":"Delete an entry (cascades senses/junctions)","tags":["entries"]}},"/api/v1/dictionaries/{id}/entries/batch-delete":{"post":{"summary":"Delete every entry from one bulk import (dry-run + confirm)","tags":["entries"]}},"/api/v1/dictionaries/{id}/entries/batch-update":{"post":{"summary":"Patch many entries in one request (ordered per-item results, retry-safe)","tags":["entries"]}},"/api/v1/dictionaries/{id}/entries/{entryId}/tags/{tagId}":{"delete":{"summary":"Unlink a tag from this entry","tags":["entries"]}},"/api/v1/dictionaries/{id}/relationships":{"get":{"summary":"List an entry's relationships","tags":["relationships"]},"post":{"summary":"Create relationships (single or batch)","tags":["relationships"]}},"/api/v1/dictionaries/{id}/relationships/{relationshipId}":{"delete":{"summary":"Delete a relationship","tags":["relationships"]}},"/api/v1/dictionaries/{id}/relationship-types":{"get":{"summary":"List custom relationship types","tags":["relationships"]}},"/api/v1/dictionaries/{id}/relationship-types/{typeId}":{"patch":{"summary":"Edit a custom relationship type","tags":["relationships"]},"delete":{"summary":"Delete a custom relationship type","tags":["relationships"]}},"/api/v1/dictionaries/{id}/entries/{entryId}/dialects/{dialectId}":{"delete":{"summary":"Unlink a dialect from this entry","tags":["entries"]}},"/api/v1/dictionaries/{id}/sentences":{"post":{"summary":"Create a standalone sentence","tags":["entries"]}},"/api/v1/dictionaries/{id}/sentences/{sentenceId}":{"get":{"summary":"Read one sentence","tags":["entries"]},"patch":{"summary":"Edit one sentence","tags":["entries"]},"delete":{"summary":"Delete one sentence","tags":["entries"]}},"/api/v1/dictionaries/{id}/senses/{senseId}":{"delete":{"summary":"Delete one sense","tags":["entries"]}},"/api/v1/dictionaries/{id}/texts":{"get":{"summary":"List texts","tags":["texts"]},"post":{"summary":"Create a text (with ordered sentences)","tags":["texts"]}},"/api/v1/dictionaries/{id}/texts/{textId}":{"get":{"summary":"Read one text (sentences + tags + audio + speakers)","tags":["texts"]},"patch":{"summary":"Update a text (title / append / reorder)","tags":["texts"]},"delete":{"summary":"Delete a text (and its sentences)","tags":["texts"]}},"/api/v1/dictionaries/{id}/texts/collections":{"get":{"summary":"List text collections","tags":["texts"]},"post":{"summary":"Create a text collection (series / book / chapter grouping)","tags":["texts"]}},"/api/v1/dictionaries/{id}/texts/collections/{collectionId}":{"get":{"summary":"Read one collection","tags":["texts"]},"patch":{"summary":"Update a collection (rename / re-parent / reorder)","tags":["texts"]},"delete":{"summary":"Delete a collection (children + texts detach, never deleted)","tags":["texts"]}},"/api/v1/dictionaries/{id}/sentences/{sentenceId}/tokens/actions":{"post":{"summary":"Review token↔entry links on one sentence","tags":["suggestions"]}},"/api/v1/dictionaries/{id}/suggestions":{"get":{"summary":"The suggestions queue (unmatched / ambiguous / ignored word forms)","tags":["suggestions"]}},"/api/v1/dictionaries/{id}/suggestions/actions":{"post":{"summary":"Act on a word form everywhere (ignore / restore / link / create_entry)","tags":["suggestions"]}},"/api/v1/dictionaries/{id}/analyze":{"post":{"summary":"Re-run word→entry matching on demand (the API twin of \"Refresh matches\")","tags":["suggestions"]}},"/api/v1/dictionaries/{id}/feedback":{"post":{"summary":"Send feedback to the LD team","tags":["feedback"]}},"/api/v1/dictionaries/{id}/speakers":{"get":{"summary":"List speakers","tags":["speakers"]},"post":{"summary":"Create a speaker","tags":["speakers"]}},"/api/v1/dictionaries/{id}/speakers/{speakerId}":{"patch":{"summary":"Edit a speaker","tags":["speakers"]},"delete":{"summary":"Delete an unused speaker","tags":["speakers"]}},"/api/v1/dictionaries/{id}/speakers/{speakerId}/merge":{"post":{"summary":"Merge a duplicate speaker into another","tags":["speakers"]}},"/api/v1/dictionaries/{id}/tags":{"get":{"summary":"List tags","tags":["tags"]},"post":{"summary":"Find-or-create a tag","tags":["tags"]}},"/api/v1/dictionaries/{id}/tags/{tagId}":{"patch":{"summary":"Rename a tag / set private","tags":["tags"]},"delete":{"summary":"Delete an unused tag","tags":["tags"]}},"/api/v1/dictionaries/{id}/tags/{tagId}/merge":{"post":{"summary":"Merge a duplicate tag into another","tags":["tags"]}},"/api/v1/dictionaries/{id}/featured-entries":{"get":{"summary":"List featured (starred) entries","tags":["featured-entries"]},"post":{"summary":"Star an entry","tags":["featured-entries"]},"patch":{"summary":"Reorder the featured strip","tags":["featured-entries"]}},"/api/v1/dictionaries/{id}/featured-entries/{entryId}":{"delete":{"summary":"Unstar an entry","tags":["featured-entries"]}},"/api/v1/dictionaries/{id}/dialects":{"get":{"summary":"List dialects","tags":["dialects"]},"post":{"summary":"Find-or-create a dialect","tags":["dialects"]}},"/api/v1/dictionaries/{id}/dialects/{dialectId}":{"patch":{"summary":"Rename a dialect","tags":["dialects"]},"delete":{"summary":"Delete an unused dialect","tags":["dialects"]}},"/api/v1/dictionaries/{id}/dialects/{dialectId}/merge":{"post":{"summary":"Merge a duplicate dialect into another","tags":["dialects"]}},"/api/v1/dictionaries/{id}/gloss-languages":{"post":{"summary":"Add a gloss language","tags":["dictionary"]}},"/api/v1/dictionaries/{id}/gloss-languages/{code}":{"delete":{"summary":"Remove a gloss language","tags":["dictionary"]}},"/api/v1/dictionaries/{id}/orthographies":{"get":{"summary":"List orthographies","tags":["orthographies"]},"post":{"summary":"Add an orthography","tags":["orthographies"]},"put":{"summary":"Reorder orthographies","tags":["orthographies"]}},"/api/v1/dictionaries/{id}/orthographies/{code}":{"patch":{"summary":"Relabel an orthography","tags":["orthographies"]},"delete":{"summary":"Delete an orthography","tags":["orthographies"]}},"/api/v1/dictionaries/{id}/sources":{"get":{"summary":"List sources","tags":["sources"]},"post":{"summary":"Create a source","tags":["sources"]}},"/api/v1/dictionaries/{id}/sources/{sourceId}":{"patch":{"summary":"Edit source metadata","tags":["sources"]},"delete":{"summary":"Delete a source","tags":["sources"]}},"/api/v1/dictionaries/{id}/files":{"get":{"summary":"List uploaded import resources","tags":["files"]},"post":{"summary":"Register an upload","tags":["files"]}},"/api/v1/dictionaries/{id}/files/{fileId}":{"get":{"summary":"Download the resource bytes","tags":["files"]},"patch":{"summary":"Update file metadata / complete it under a source","tags":["files"]},"delete":{"summary":"Delete an uploaded resource","tags":["files"]}},"/api/v1/dictionaries/{id}/files/{fileId}/confirm":{"post":{"summary":"Confirm an upload landed","tags":["files"]}},"/api/v1/dictionaries/{id}/files/request-import":{"post":{"summary":"Ask the Living Dictionaries team to import these files","tags":["files"]}},"/api/v1/dictionaries/{id}/files/requests/{threadId}":{"patch":{"summary":"Update an import request note","tags":["files"]}},"/api/v1/dictionaries/{id}/conversations":{"get":{"summary":"List import conversations","tags":["conversations"]}},"/api/v1/dictionaries/{id}/conversations/{threadId}":{"get":{"summary":"Read one import conversation","tags":["conversations"]},"patch":{"summary":"Claim or resolve the job","tags":["conversations"]}},"/api/v1/dictionaries/{id}/conversations/{threadId}/brief":{"get":{"summary":"Build the import job kickoff brief","tags":["conversations"]}},"/api/v1/dictionaries/{id}/conversations/{threadId}/messages":{"post":{"summary":"Post a message","tags":["conversations"]}},"/api/v1/dictionaries/{id}/conversations/{threadId}/read":{"post":{"summary":"Mark the conversation read","tags":["conversations"]}},"/api/v1/dictionaries/{id}/conversations/{threadId}/withdraw":{"post":{"summary":"Withdraw an unstarted request","tags":["conversations"]}},"/api/v1/dictionaries/{id}/conversations/{threadId}/artifacts":{"get":{"summary":"List the conversation's artifacts","tags":["conversations"]},"post":{"summary":"File a report (or preview) HTML artifact","tags":["conversations"]}},"/api/v1/dictionaries/{id}/conversations/{threadId}/artifacts/{artifactId}":{"get":{"summary":"Download an artifact","tags":["conversations"]}},"/api/v1/dictionaries/{id}/conversations/{threadId}/questions":{"get":{"summary":"List the conversation's questions","tags":["conversations"]},"post":{"summary":"Ask answerable questions","tags":["conversations"]}},"/api/v1/dictionaries/{id}/conversations/{threadId}/questions/{questionId}":{"patch":{"summary":"Answer or close a question","tags":["conversations"]}},"/api/v1":{"get":{"summary":"START HERE — the front door","tags":["start"]}},"/api/v1/guides":{"get":{"summary":"List the task playbooks","tags":["guides"]}},"/api/v1/guides/{slug}":{"get":{"summary":"Read one guide (markdown)","tags":["guides"]}},"/api/v1/dictionaries/{id}/grammar/sections":{"get":{"summary":"List grammar sections","tags":["grammar"]},"post":{"summary":"Create a grammar section","tags":["grammar"]}},"/api/v1/dictionaries/{id}/grammar/sections/{sectionId}":{"get":{"summary":"Read a grammar section","tags":["grammar"]},"patch":{"summary":"Update / move a grammar section","tags":["grammar"]},"delete":{"summary":"Delete a grammar section","tags":["grammar"]}},"/api/v1/dictionaries/{id}/grammar/sections/{sectionId}/sentences":{"post":{"summary":"Attach an example sentence to a section","tags":["grammar"]}},"/api/v1/dictionaries/{id}/grammar/sections/{sectionId}/sentences/{sentenceId}":{"delete":{"summary":"Detach an example sentence from a section","tags":["grammar"]}},"/api/v1/dictionaries/{id}/grammar/clause-slots":{"get":{"summary":"List clause-template slots","tags":["grammar"]},"post":{"summary":"Create a clause-template slot","tags":["grammar"]}},"/api/v1/dictionaries/{id}/grammar/clause-slots/{slotId}":{"patch":{"summary":"Rename / reorder a clause slot","tags":["grammar"]},"delete":{"summary":"Delete a clause slot","tags":["grammar"]}},"/api/v1/dictionaries/{id}/entries/{entryId}/grammar":{"get":{"summary":"List grammar sections documenting an entry","tags":["grammar"]}},"/api/v1/dictionaries/{id}/grammar/glossing-abbreviations":{"get":{"summary":"List glossing abbreviations","tags":["grammar"]},"post":{"summary":"Add a glossing abbreviation (find-or-create)","tags":["grammar"]}},"/api/v1/dictionaries/{id}/grammar/glossing-abbreviations/{code}":{"patch":{"summary":"Edit a glossing abbreviation","tags":["grammar"]},"delete":{"summary":"Delete a glossing abbreviation","tags":["grammar"]}},"/api/v1/dictionaries/{id}/cognate-sets":{"get":{"summary":"List cognate sets (word families)","tags":["cognate-sets"]},"post":{"summary":"Create cognate sets (single or batch)","tags":["cognate-sets"]}},"/api/v1/dictionaries/{id}/cognate-sets/{setId}":{"get":{"summary":"Read a cognate set","tags":["cognate-sets"]},"patch":{"summary":"Update a cognate set","tags":["cognate-sets"]},"delete":{"summary":"Delete a cognate set","tags":["cognate-sets"]}},"/api/v1/dictionaries/{id}/cognate-sets/{setId}/members":{"post":{"summary":"Add or update a set member","tags":["cognate-sets"]}},"/api/v1/dictionaries/{id}/cognate-sets/{setId}/members/{entryId}":{"delete":{"summary":"Remove an entry from a set","tags":["cognate-sets"]}},"/api/v1/dictionaries/{id}/places":{"get":{"summary":"List places","tags":["places"]},"post":{"summary":"Create places (single or batch)","tags":["places"]}},"/api/v1/dictionaries/{id}/places/{placeId}":{"get":{"summary":"Read a place","tags":["places"]},"patch":{"summary":"Update a place","tags":["places"]},"delete":{"summary":"Delete a place","tags":["places"]}},"/api/v1/dictionaries/{id}/places/{placeId}/links":{"post":{"summary":"Link a place to entries, texts, dialects, speakers and the language","tags":["places"]},"delete":{"summary":"Unlink a place","tags":["places"]}},"/api/v1/dictionaries/{id}/entries/{entryId}/etymologies":{"get":{"summary":"List an entry's etymology records","tags":["entries"]},"post":{"summary":"Add an etymology record","tags":["entries"]}},"/api/v1/dictionaries/{id}/entries/{entryId}/etymologies/{etymologyId}":{"get":{"summary":"Read an etymology record","tags":["entries"]},"patch":{"summary":"Update an etymology record","tags":["entries"]},"delete":{"summary":"Delete an etymology record","tags":["entries"]}},"/api/v1/dictionaries/{id}/texts/{textId}/tags":{"get":{"summary":"List a text's classification tags","tags":["texts"]},"post":{"summary":"Tag a text (find-or-create)","tags":["texts"]}},"/api/v1/dictionaries/{id}/texts/{textId}/embeds":{"get":{"summary":"List the texts heard inside a text","tags":["texts"]},"post":{"summary":"Place a text inside another","tags":["texts"]}},"/api/v1/dictionaries/{id}/texts/{textId}/embeds/{embedId}":{"delete":{"summary":"Take an embedded text out","tags":["texts"]}},"/api/v1/dictionaries/{id}/texts/{textId}/tags/{tagId}":{"delete":{"summary":"Untag a text","tags":["texts"]}}},"schema_names":["MultiString","LngLat","GeoPoint","GeoRegion","Coordinates","SentenceInput","SenseInput","EntryInput","SensePatch","SentencePatch","EntryPatch","OrthographyInput","ToneLetters","SourceInput","SourceFile","ImportRequest","EntryWriteResult","EntriesWriteResponse","SenseSummary","EntrySummary","EntriesListResponse","SentenceFull","SenseFull","EntryReview","EntryReviewComparison","EntryReviewComparisonSide","EntryReviewApply","EntryMain","EntryFull","EntryResponse","TextSentenceInput","TextInput","TextSentenceFull","TextSummary","TextFull","TextPatch","TextCollection","TextCollectionInput","TextCollectionPatch","SuggestionRow","TokenAction","AlignJob","AlignCoverage","HostedElsewhere","SpeakerBrief","SpeakerFull","MediaTimings","AudioMedia","TextAudioClip","PhotoMedia","VideoMedia","RelationshipCustomType","RelationshipInput","RelationshipView","RelationshipTypeView","GrammarSectionInput","GrammarSectionPatch","SectionSentenceRef","GrammarSectionFull","ClauseSlotInput","ClauseSlotFull","TextTagInput","TextTagView","TextEmbed","TextEmbedInput","SourceCitation","TranslationProvenance","Morpheme","SentenceTokenInput","SentenceTokenFull","DictionaryCatalogPatch","GlossingAbbreviationInput","GlossingAbbreviationFull","CognateSetMemberInput","CognateSetInput","CognateSetPatch","CognateSetMemberFull","CognateSetFull","CognateSetSummary","PlaceInput","PlacePatch","PlaceFull","PlaceSummary","PlaceLinksInput","PlaceUnlinkInput","EtymologyInput","EtymologyPatch","EtymologyFull"]}