Skip to content

Lemma Editor API Contract (Canonical)

Scope

This contract documents the required admin endpoints used by the Lemma Editor and their table-level effects.

All endpoints are mounted in admin middleware chain (rate-limit + admin auth + admin logging) and return the standard admin envelope used by Content Bank operations.

Required endpoints

Core editor resources

  • GET /admin/content-bank/lemmas/:id
  • GET /admin/content-bank/lemmas/editor-metadata
  • POST /admin/content-bank/lemmas/:id/editor-save

Senses

  • GET /admin/content-bank/lemmas/:id/senses
  • POST /admin/content-bank/lemmas/:id/senses
  • PATCH /admin/content-bank/lemmas/:id/senses/:senseId
  • DELETE /admin/content-bank/lemmas/:id/senses/:senseId

Sentences

  • GET /admin/content-bank/lemmas/:id/sentences
  • POST /admin/content-bank/lemmas/:id/examples
  • DELETE /admin/content-bank/lemmas/:id/examples/:sentenceId

Semantic relations

  • GET /admin/content-bank/lemmas/:id/relations
  • POST /admin/content-bank/lemmas/:id/collocations
  • DELETE /admin/content-bank/lemmas/:id/collocations/:relationId

Translations

  • GET /admin/content-bank/lemmas/:id/translations

Pronunciation / TTS

  • GET /admin/content-bank/lemmas/:id/audio

editor-save payload contract

POST /admin/content-bank/lemmas/:id/editor-save performs atomic persistence for Core + Taxonomies.

Request payload

{
  "lemma": "run",
  "editorial_status": "draft",
  "image_url": "https://cdn.example/image.png",
  "audio_url": "https://cdn.example/audio.mp3",
  "spelled_form": null,
  "numeric_value": null,
  "taxonomy_value_ids": [
    "2ad6cbca-57d6-4cc5-8f83-6fc2f79e17f9",
    "b43d4fcb-f2fd-47bd-8f6d-f5c928cc8dd9"
  ]
}

Validation and semantics

  • :id must be UUID.
  • lemma is required and trimmed.
  • taxonomy_value_ids must be UUID array; duplicates are removed.
  • Core fields are written to lemmas.
  • Existing lemma taxonomy links are replaced in content_item_taxonomies (content_type='lemma', content_id=:id).
  • Operation executes atomically in a transaction block.

Response

{
  "ok": true,
  "data": {
    "lemma_id": "<uuid>",
    "taxonomy_value_ids": ["<uuid>", "<uuid>"],
    "saved": true
  }
}

Tab-to-endpoint matrix

  • CoreTab → GET /lemmas/:id, POST /lemmas/:id/editor-save
  • TaxonomiesTab → GET /lemmas/editor-metadata, POST /lemmas/:id/editor-save
  • MorphologyTab → same lemma editor context + morphology endpoints (/morphology/forms) when enabled by implementation
  • SensesTab → senses CRUD endpoints
  • TranslationsTab → GET /lemmas/:id/translations
  • SentencesTab → sentence endpoints (/sentences, /examples)
  • SemanticRelationsTab → relations and collocation endpoints
  • PronunciationTab → GET /lemmas/:id/audio
  • ChunksTab → chunk usage surfaced from lemma context and persisted in chunk tables by dedicated workflows

Governance and non-regression

  • This API contract exists to preserve the Lemma Editor architecture and prevent accidental regression to simplified CRUD flows.
  • Protected files must only receive minimal patches:
  • web/src/app/admin/content-bank/lemmas/[id]/page.tsx
  • web/src/app/components/content-bank/LemmaEditor.tsx
  • Automation must never fully rewrite protected files.