Vocabulary merge: method and API
Open the vocabulary organizer →
Write, import and review
Write one word or phrase per line. Words stay unmeasured unless you explicitly choose a self-reported status in Input options. A source label applies to direct words or missing import sources. CSV and JSON fields stay as supplied; input options never overwrite their statuses.
Preview the union, then keep conflicting statements together or skip a new record. Previous records stay unchanged. Skipping is reversible; keeping statements together records an editorial review, not a finding about knowledge. The conflict still exists in the evidence. Amber saves only selected additions after an explicit save, with an import source; it does not remove existing records or change accepted reading versions.
Exports and reimport
Records JSON and CSV include every selected record, regardless of search or the number of displayed rows. Full report uses vocabulary-merge-review/1 with method amber-vocabulary-merge-review/1.0. It contains previous and incoming arrays, the original merge report, decisions (excluded record indices and keptTogether conflict indices), and the recomputed output. Indices refer to the original merge report. Review choices are session edits; the report preserves them for audit.
The organizer can import a record array, a vocabulary-merge/1 report, or a full review report. Importing a review report recomputes its selected records from the original inputs and choices; claimed output counts are ignored. It imports the selected records, not the earlier editing session. The public API still accepts the original record arrays or text, not report objects. For large exports, extract or split the records into inputs of at most 600,000 characters and 10,000 records. Amber allows 500 imported records per save.
Input format and an example
CSV must have a word header. Optional columns: status, source, id, at, granularity, sense, context, meaning, assisted, articleId, location. Quote fields containing commas or line breaks; double embedded quotation marks. Plain text uses one word or phrase per line.
word,status,source,id bank,known,my list,bank-1 yield,unknown,my list,yield-1
Statuses: known (self-report), unknown, saved, lookup, usage-unfamiliar, assisted, independent-correct, independent-wrong, unmeasured. A missing status stays unmeasured; a missing time stays blank. Time is Unix milliseconds. Assisted is true or false.
Optional location is a JSON object with version, sentenceId, sourceParagraph and sourceStart (a UTF-16 offset in the original paragraph). It requires articleId and context or sense granularity. CSV stores it as quoted JSON. A location preserves origin; it does not prove knowledge.
Granularity is word, context or sense. A sense requires its original key and context. Supplying a context alone keeps context granularity. Different inflections and different senses stay separate. Word forms normalize case, whitespace and curly apostrophes; this is not lemmatization.
Download a complete request and result example. The example keeps three records, removes one exact duplicate and reports one status conflict.
How merging works
Only records identical in every normalized field are deduplicated. Sources, IDs, times, assistance and contexts stay attached. Opposing known/unknown statements for the same word and granularity, sense, context and article are conflicts; a reused source and ID with different contents is also a conflict. All conflicting records remain. A later timestamp does not silently win.
These are vocabulary records, not a mastery score. Reference lists are unmeasured unless a status is explicitly supplied. Imported labels do not prove a response was assessed. Amber uses this same merge core for assessment, reading and external records, while only its original eligible responses can support assessment evidence. Conflicting native sense evidence is withheld from new review evidence; existing accepted snapshots remain unchanged.
JSON record downloads are the lossless interchange format. CSV adds an apostrophe before spreadsheet formula prefixes; use JSON when you need an exact round trip for those fields. The change report separately includes additions, duplicates and conflicts.
Method amber-vocabulary-merge/1.0 · October 10, 2026. The CSV workflow was compared with Lute's import documentation; this tool uses its own field names and status meanings, so map other formats explicitly.
API for agents and developers
POST JSON to /api/tools/vocabulary-merge with previous and incoming. Each is a text string or an array of records with the fields above. Both are required; either can be empty. Unknown fields fail validation. Response: schema vocabulary-merge/1, method, records, changes, conflicts and summary.
curl -X POST https://amberenglish.app/api/tools/vocabulary-merge -H 'Content-Type: application/json' -d '{"previous":[{"word":"bank","status":"known","source":"old list"}],"incoming":[{"word":"bank","status":"unknown","source":"new mark"}]}'No account or model call is required. Inputs are not stored; responses use no-store and noindex. Request body limit: 1,800,000 bytes. Each input and the merged result: 10,000 records; strings: 600,000 UTF-16 characters. Field limits: word 120, status 40, source 300, id/sense 200, context 5,000, meaning 3,000, articleId 160 characters.
400: fix the JSON, CSV or record fields. 413: split the input. 415: send application/json. 500: retry the same input. Repeating the request has no saved side effects. Status and ID conflicts return 200 with a conflict report, not an error. Results are deterministic for the same input and method.