Save a word
save_wordCreates a word, or updates an existing word when itemId and expectedVersion are both provided. Matching text alone never updates an existing word. Updates are patches: omitted fields stay unchanged and null clears supported fields. definitions edits a meaning by ID or adds one without an ID; removeDefinitionIds deletes those meanings with their examples and meaning progress; removing every meaning keeps the word. Each retained meaning needs definition text or a translation. appendExamples keeps existing examples, replaceExamples replaces them ([] clears), and the two cannot be combined. addGroupIds and removeGroupIds change only the listed memberships. imageUrl accepts a durable public HTTPS image URL; null removes the image. requestId makes retries idempotent when the input is identical. Subject to the plan's word limit.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | ||
| itemId | No | ID of an existing word to update. Omit, together with expectedVersion, to create a word. | |
| comment | No | ||
| imageUrl | No | Durable public HTTPS URL of the image to set, or null to remove the image. Omitted keeps the current image. | |
| requestId | Yes | ||
| addGroupIds | No | ||
| definitions | No | Meaning patches. An existing definition ID edits that meaning; an entry without an ID adds a meaning. Omitted meanings and fields stay unchanged. | |
| languageCode | Yes | Code of the learning language, for example en-GB or es-ES. | |
| removeGroupIds | No | ||
| expectedVersion | No | Opaque revision token from the latest read or save of this item. A stale token returns WORD_CHANGED or GROUP_CHANGED without saving. | |
| removeDefinitionIds | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| item | No | ||
| text | No | ||
| itemId | No | ||
| status | No | ||
| message | No | ||
| version | No | ||
| examplesOmitted | No |