API changelog

Changes to Translate Park's API contract and vocabulary content, newest first. This is a running history of edits. Each entry names the affected endpoints and any action consumers should take.

API guide · Markdown version

2026-10-17 — Preserve grammar statement and list boundaries

Type: Bug fix. Scope: HSK 2026 grammar source content, levels 1 and 3.

Affected endpoints

• GET /api/v1/standards/hsk-2026/syllabus/items/

Corrects the previous grammar normalization revision in three records: hsk-2026:grammar:1:040, hsk-2026:grammar:3:008, and hsk-2026:grammar:3:012. Meaningful statement/list breaks are restored as newlines. In particular, the two 状语 statements stay separate and the source's missing punctuation after 句 no longer produces the false token 句公斤. No punctuation is invented to repair the original source.

Full-width wrapping remains joined in 38 other records. IDs, counts, source locations, original page text, vocabulary and all other content are unchanged. The artifact revision changes. This correction supersedes unconditional newline removal described in the earlier normalization entry.

Consumer action: Refresh cached grammar when the revision changes and retain newlines in data.content when displaying separate statements or list entries.

Download the corrections (CSV)

2026-10-17 — Grammar text normalization and source-download integrity

Type: Bug fix / API contract. Scope: HSK 2026 source grammar and source PDF downloads.

Affected endpoints

• GET /api/v1/standards/hsk-2026/syllabus/items/
• GET /api/v1/standards/hsk-2026/syllabus/sources/{source}/pdf/

Grammar data.content now joins PDF layout line breaks so words such as 她们 are searchable and display intact. This changes 41 grammar rows compared with the initial complete syllabus import. IDs, counts, source pages and original page text are unchanged. The data revision changes; vocabulary meanings and identities are unaffected. Competency level extraction now validates printed labels, without changing the nine descriptions or their IDs.

PDF downloads verify their bytes against the published SHA-256 before serving. Missing or mismatched files return JSON 503 rather than an unverified download. Clarification: vocabulary position is the document-wide source number, not a level-local index; other kinds use a 1-based position within the kind and scope.

Consumer action: Refresh cached grammar content when the catalog revision changes. Use original source pages/PDFs for layout-sensitive review.

Download the changes (CSV)

2026-10-17 — Complete official syllabus source API

Type: API contract. Scope: HSK 2026, original Chinese source content, all published scopes.

Affected endpoints

• GET /api/v1/standards/hsk-2026/syllabus/
• GET /api/v1/standards/hsk-2026/syllabus/items/
• GET /api/v1/standards/hsk-2026/syllabus/sources/{source}/pages/{physical_page}/
• GET /api/v1/standards/hsk-2026/syllabus/sources/{source}/pdf/

Adds a catalog with revision, counts, source checksums and links; typed records for tasks, topics, vocabulary source rows, recognition characters, writing characters, grammar, competencies and a task section note; all 406 guide pages and the separate competency page; and pinned PDF downloads. Sources are guide and competencies. This is source content, not authored lessons or translated explanations. Existing vocabulary responses and word IDs are unchanged.

Records expose item_id, kind, level, position, data, source, and locations with physical and printed pages. Source vocabulary numbers are not existing API word IDs. Shared handwriting scope 1-2 is preserved; competency levels 7, 8 and 9 are separate from other sections' shared 7-9.

The items endpoint accepts exact kind and level filters, page (default 1), and page_size (default 100, maximum 500). Responses contain revision, count, next, previous, and results; follow links to retrieve every record. Unknown/repeated parameters, invalid filters and invalid pagination return 400; missing source/pages and out-of-range result pages return 404. Missing or partial imports return 503. Source text is Chinese only; base_language is rejected. Anonymous access uses the existing shared standards limit of 60 requests/minute per IP (429 when exceeded). Authenticated callers are unaffected by this throttle.

Consumer action: No migration required for vocabulary consumers. Discover syllabus types at the new catalog and use kind to distinguish characters, grammar and words. Cache by revision; do not join PDF numbers directly to word IDs. See the source record guide.

Download the changes (CSV)

2026-10-13 — Canonical public API hostname

Type: API contract. Scope: All API endpoints.

Affected endpoints

• All paths under /api/ on alternate production hostnames.

Alternate production hostnames now return a permanent HTTP 301 redirect to https://translatepark.com, preserving the path and query string. Previously they served the app directly. The canonical domain's responses are unchanged.

Consumer action: Use https://translatepark.com as the API base URL, especially for writes; some clients change POST to GET when following a 301.

2026-10-03 — Keep the vocabulary catalog available during difficulty failures

Type: Bug fix. Scope: HSK 2026 catalog and advanced difficulty filters, all base languages.

Affected endpoints

• GET /api/v1/standards/hsk-2026/levels/
• GET /api/v1/standards/hsk-2026/levels/7-9/?difficulty=easier|middle|harder

A failure in optional difficulty discovery now leaves the published catalog available with 200, omitting tp_difficulty options instead of returning 500. This includes conflicting level assignments discovered while checking advanced meanings. It does not change the handling of errors in the catalog's own required data.

Missing or corrupt difficulty artifacts are checked once per serving worker; subsequent requests reuse the failure rather than repeatedly reading and decompressing the artifact. Requested filters remain unavailable with 503. This artifact cache is separate from the 60-second vocabulary validation cache. Vocabulary content, difficulty assignments, counts and ordering are unchanged.

Consumer action: No migration or cache refresh required. Use advertised options and continue handling 503 for unavailable difficulty filtering.

2026-10-03 — Cache advanced difficulty availability checks

Type: Performance / Bug fix. Scope: HSK 2026 catalog and advanced difficulty filters, all base languages.

Affected endpoints

• GET /api/v1/standards/hsk-2026/levels/
• GET /api/v1/standards/hsk-2026/levels/7-9/?difficulty=easier|middle|harder

Difficulty availability validation is cached for up to 60 seconds, keyed by the meaning-release identity/checksum and difficulty dataset identity/checksum. Repeat catalog requests reuse the verdict instead of loading the full advanced English vocabulary. Filtered requests in another base language reuse the same verdict and build the requested language's list without rebuilding English. The response contract, assignments, counts, and ordering are unchanged.

Every request still checks the active meaning-release identity and checksum; release changes and rollback cannot reuse a previous release's verdict. Membership IDs are checked on every filtered response. When an English list is already loaded for the requested response, its meanings and identities are also checked and a changed list invalidates the cached verdict. Other in-place edits to stored data can take up to 60 seconds to change advertised availability or non-English filtering eligibility. Both successful and failed validation verdicts expire; corrected stored data is rechecked after expiry. This refines the availability behavior described in the earlier October 3 entry.

Consumer action: No migration or cache refresh required. Continue handling 503 for unavailable difficulty filtering and following the catalog's options.

2026-10-03 — Restore one vocabulary API and add advanced difficulty filters

Type: API contract (breaking) / Vocabulary classification. Scope: HSK 2026, all seven published groups; advanced difficulty estimates based on en-US meanings.

Affected endpoints

• GET /api/v1/standards/hsk-2026/levels/
• GET /api/v1/standards/hsk-2026/levels/{level}/
• GET /api/v1/standards/hsk-2026/levels/7-9/?difficulty=easier|middle|harder
• Removed: GET /api/v1/standards/hsk-2026/bands/ and /bands/{band}/
• Removed: GET /api/v1/standards/hsk-2026/levels/7/, /levels/8/, /levels/9/

The single vocabulary catalog again lists the seven published groups: 1 through 6 and shared advanced 7-9. It identifies items using level and canonical /levels/ URLs. The duplicate /bands/ family and individual advanced aliases return 404, without redirects or compatibility aliases. The band envelope/catalog field introduced on October 1 is removed. /levels/7-9/ is the canonical advanced URL and is no longer deprecated. This entry supersedes the October 1 migration guidance; that historical entry and its anchor remain available.

The optional difficulty filter returns one of three distinct advanced practice lists, each with 1,874 entries. Their disjoint union is the complete 5,622-entry advanced group, including 5,600 new and 22 returning entries. Unfiltered vocabulary content and published-number order are unchanged. Filtered lists preserve that order and every word's full meaning payload; filter.equals and meaning hsk_level tags remain 7-9.

When available, the advanced catalog item adds tp_difficulty, with dataset_id, is_estimate: true, basis_language: "en-US", description, and options. Each option contains difficulty, a filter url, and word_count, new_word_count, returning_word_count. Filtered responses add those three counts, glossed_count for the selected entries, and tp_difficulty containing the same estimate metadata plus selected. Other catalog counts remain counts of the complete published groups.

Dataset advanced-difficulty-groups-2026-10-03-v2 supplies Translate Park's estimates of advanced written reading difficulty after groups 1–6. These are not official HSK levels 7/8/9 or validated proficiency boundaries. Equal thirds split some tied scores; published IDs break ties reproducibly rather than demonstrating differences between those words. Classification is based on the reviewed English meanings and does not change with base_language.

A difficulty value must be exactly one of easier, middle, harder. Invalid, empty, repeated values or use on the catalog/groups 1–6 return 400. Filtered requests return 503 when the active meaning release or advanced vocabulary no longer matches the frozen dataset, or the artifact is unavailable; the catalog then omits difficulty options. Unfiltered vocabulary remains available. Existing language selection, translation-null behavior, access, read-only methods, and anonymous throttling are unchanged. Word lookup and its ?level=7-9 filter are unchanged.

The assignment download compares with the Translate Park serving API captured on October 3, 2026, before advanced difficulty filtering. Its old difficulty is unclassified; it does not invent previous official assignments. Word and sense identities, readings, meanings and official memberships are unchanged.

Consumer action: Replace /bands/{band}/ requests with /levels/{band}/. Replace /levels/7/, /8/, /9/ with /levels/7-9/ for the complete official pool, or follow tp_difficulty.options URLs for distinct practice lists. Refresh cached catalogs and remove assumptions that there are nine vocabulary lists. Store tp_difficulty.dataset_id with filtered-list caches and refresh when that version changes. Continue selecting taught meanings using filter.equals; do not treat difficulty names as official HSK level tags.

Download the assignments (CSV)

2026-10-01 — Separate vocabulary bands and individual levels

Type: API contract / Deprecation. Scope: HSK 2026, all bands and levels, all base languages.

Affected endpoints

• GET /api/v1/standards/hsk-2026/levels/
• GET /api/v1/standards/hsk-2026/levels/{level}/
• GET /api/v1/standards/hsk-2026/bands/ (new)
• GET /api/v1/standards/hsk-2026/bands/{band}/ (new)

The level catalog now lists nine individual levels, 1 through 9, instead of seven source bands. Each item adds band, retains its counts, and links to its individual level URL. The catalog no longer includes a 7-9 item. This changes catalog membership for consumers that iterate it.

The new band catalog returns a bands array for 1 through 6 and 7-9. Items use band rather than level, retain the existing per-band counts, and link to band URLs. Band vocabulary responses identify band instead of level.

Individual vocabulary responses retain the requested level and add band. Levels 1–6 serve their matching bands; levels 7, 8, and 9 each serve band 7-9 with identical words, meanings, and counts. Lists remain noncumulative, including returning words with newly introduced meanings. The meaning-level hsk_level tags retain official source-band labels. On activated meaning releases, use filter.equals to select taught meanings; it is 7-9 for all three advanced levels. The word lookup's ?level= filter continues to use source-band labels, including 7-9.

/levels/7-9/ is deprecated but retains its existing response, without adding band. No removal date is set. Word identities, vocabulary content, ordering, language selection, access, and error status codes are unchanged.

Consumer action: Refresh cached catalogs. Use /bands/ to iterate the seven published groups; use /levels/ for nine individually addressable levels. Replace /levels/7-9/ with /bands/7-9/ for band access. Do not sum level counts as a distinct vocabulary total: the shared advanced band appears three times. Select meanings using filter.equals rather than assuming that their hsk_level equals the requested level.

2026-09-24 — Two gloss fixes: 摄影 and 解除

Type: Vocabulary content. Scope: HSK 2026, levels 5 and 7–9, en-US.

Affected endpoints

• GET /api/v1/standards/hsk-2026/levels/{level}/

• GET /api/v1/standards/hsk-2026/words/{word_id}/

• 摄影 verb is now “to take a photograph; to shoot (a movie)”. Its noun use, “photography”, is a separate meaning with hsk_level: null.

• 解除 is now “to remove; to lift (a ban); to cancel (a contract); to relieve (of duties)”, replacing the misleading “to sack”.

Consumer action: Refresh cached meanings for these two words.

Download the changes (CSV)

2026-09-24 — One meaning list per word

Type: API contract (breaking). Scope: HSK 2026, all seven bands.

Affected endpoints

• GET /api/v1/standards/hsk-2026/levels/{level}/
• GET /api/v1/standards/hsk-2026/words/{word_id}/

Every word now lists all of its meanings, dictionary style, in one meanings array. Each meaning has sense_id, part_of_speech, gloss and a new hsk_level: the one level that teaches it, or null when HSK never teaches it. Meanings are ordered by level, with null last. On the level 1 list, 分 now shows its level 1 classifier and its level 3 verb and noun.

Level responses add filter ({"field": "hsk_level", "equals": "<level>"} plus a description) and a parts_of_speech code-to-label registry. The word endpoint also returns the registry; its level= filter matches hsk_level.

Fields that repeated meanings or other data are removed:

Consumer action: Filter meanings by hsk_level for level-specific content, and read counts from the catalog. Cached level lists and word lookups need a full refresh.

2026-09-24 — Corrected HSK 2026 meanings and dictionary-style entries

Type: Vocabulary content. Scope: HSK 2026, all seven bands, en-US.

Affected endpoints

• GET /api/v1/standards/hsk-2026/levels/{level}/
• GET /api/v1/standards/hsk-2026/words/{word_id}/

A review of all 480 proposed wording changes corrected 272 meanings across 271 words and kept 209 current glosses.

• Wrong or misleading meanings fixed: 可以 as an adjective is now “not bad; acceptable; pretty good” instead of “possible”; 对联 no longer says couplets rhyme.
• Missing common uses added: 课 adds “lesson”; 请客 adds “to treat someone”.
• Wording and formatting: 秒 is now “second (unit of time)”; stray spacing removed.

Where a gloss mixed parts of speech, the meaning HSK assigns stays under its own part of speech, and the other meaning is added as its own entry with hsk_level: null, so no meaning learners need is lost. For example, 希望 is now verb “to hope” (hsk_level: "2") and noun “hope; wish (有希望, there is hope)” (hsk_level: null). This adds 60 meanings across 59 words.

Word IDs, level memberships and existing sense IDs are unchanged. The download lists each changed or added meaning by sense_id, compared with the Translate Park serving API captured on September 24, 2026, before launch-review corrections.

Consumer action: Refresh cached meanings for the listed words.

Download the changes (CSV)

2026-09-24 — Remove repeated alternatives from combined glosses

Type: Bug fix. Scope: HSK 2026, all bands; combined gloss display.

Affected endpoints

• GET /api/v1/standards/hsk-2026/levels/{level}/
• GET /api/v1/standards/hsk-2026/words/{word_id}/

Combined glosses omit exact repeated alternatives across meaning groups. For example, 天 displays “day; sky” instead of “day; sky; day”. Its structured noun and measure-word meanings remain distinct and retain their own translations. Whitespace around displayed alternatives is trimmed. Semicolons inside parenthesized usage notes remain part of the note.

This is a display correction; it does not remove POS assignments or structured meaning records. Missing translations continue to produce gloss: null. The download compares level responses with the serving API captured on September 24, 2026, before this correction.

Consumer action: Refresh cached combined gloss text. Preserve word IDs, level memberships and structured meaning records.

Download the changes (CSV)

2026-09-24 — Complete level lists and meanings by part of speech

Type: Bug fix / API contract / Vocabulary content. Scope: HSK 2026, all seven bands, en-US.

Affected endpoints

• GET /api/v1/standards/hsk-2026/levels/
• GET /api/v1/standards/hsk-2026/levels/{level}/
• New: GET /api/v1/standards/hsk-2026/words/{word_id}/

Level lists now include earlier words when the standard introduces another part of speech at that level. Previously those returning memberships were missing.

word_count counts the complete list. New fields new_word_count and returning_word_count distinguish its two components. There are still 11,000 unique word IDs, now represented by 11,105 level memberships.

Each level's gloss and part_of_speech now cover only its assigned parts of speech. For example, 分 retains its level-1 uses and also appears at level 3 with the verb meaning “to divide”. New fields include parts_of_speech (codes), meanings (sense IDs, POS codes, labels and glosses), introduction_level, is_new, and level_assignments. The catalog supplies a POS code/label registry. also_at_level is deprecated because one value cannot describe every later use; it remains present, holding the first later assignment or null.

The new word endpoint returns all reviewed learner meanings, grouped by POS. Optional part_of_speech=verb and level=3 filters intersect. Unknown words return 404; invalid POS or level filters return 400. A valid filter with no matching sense returns an empty meaning list. Base-language selection behaves as on level endpoints. Missing translations remain null, without substituting another POS, level or language. glossed_count now counts entries with complete translations for all meanings selected by that level.

The current official source also corrects source numbering and readings, including 线上 → xiànshàng, and prints six previously optional forms directly. as_printed now includes the current source number, level and full POS annotation. Published word_id and number values remain stable; lists retain published-number order. Source numbering changes do not create new word identities. Optional-form fields are null where the current source prints no optional form.

The download compares with the Translate Park serving API captured on September 24, 2026, before this change. It records added memberships, revised meanings, display forms/readings, POS representation and source metadata.

Consumer action: Refresh complete level lists and cached meanings. Use (word_id, level) for teaching membership and retain word_id for word identity. Do not assume a known word means every POS has been learned. Use level_assignments instead of also_at_level, and structured meanings when building POS-specific learning activities.

Download the changes (CSV)

2026-09-23 — Complete English gloss coverage verified in production

Type: Vocabulary availability confirmation. Scope: HSK 2026, all seven bands, en-US.

Affected endpoints

• GET /api/v1/standards/hsk-2026/levels/
• GET /api/v1/standards/hsk-2026/levels/{level}/

The English release has been imported into the production API at https://translatepark.com. On September 23, 2026, all 11,000 live English glosses were verified against the reviewed release files by word_id. Coverage was 300, 200, 500, 1,000, 1,600, 1,800 and 5,600 for bands 1, 2, 3, 4, 5, 6 and combined 7-9 respectively.

These meanings are available now from that public service. The existing change CSV downloads compare against the HSK 2026 English seed before the September 2026 review; their baseline is unchanged by this production verification.

Consumer action: Refresh cached en-US vocabulary now and read the gloss field. Continue keying records on word_id. English is the default base language; coverage in other base languages is reported separately by glossed_count.

2026-09-23 — HSK 2026 levels 2–9 English meanings

Type: Vocabulary content. Scope: HSK 2026, levels 2, 3, 4, 5, 6 and combined 7–9, en-US.

Affected endpoints

• GET /api/v1/standards/hsk-2026/levels/{level}/
• GET /api/v1/standards/hsk-2026/levels/ (glossed_count)

This content release supplies reviewed English meanings for the remaining 10,700 entries. With the unchanged level-1 release, all 11,000 entries have English meanings available from https://translatepark.com, verified September 23, 2026. Per-band coverage is 300, 200, 500, 1,000, 1,600, 1,800 and 5,600. The advanced endpoint uses 7-9, not separate levels 7, 8 and 9.

Compared with the HSK 2026 English seed before the September 2026 review, 7,425 missing meanings are filled and 1,145 meanings change; 2,130 remain unchanged. The downloadable CSV compares the checked-in publisher seed against normalized official identities. Its old_gloss values come from that repository seed, not a historical production snapshot. This baseline describes the differences in the download; the reviewed meanings are already live on the public API.

Meanings distinguish official homographs and readings, use clear learner wording, and omit unrelated or unsuitable reference senses. Word IDs, ordering, membership, readings, response fields and other base languages are unchanged. In particular, the previously documented source reading discrepancy for 线上 is not corrected by this English content release. Clients comparing gloss strings will see changes.

Consumer action: Refresh cached en-US meanings from the public API now. Coverage counts are not revision identifiers.

Download the changes (CSV)

2026-09-22 — HSK 2026 level 1 English meanings

Type: Vocabulary content. Scope: HSK 2026, level 1, en-US.

Affected endpoints

• GET /api/v1/standards/hsk-2026/levels/1/
• GET /api/v1/standards/hsk-2026/levels/ (level-1 glossed_count)

All 300 level-1 entries have reviewed English meanings, selected for clear beginner usage with CC-CEDICT as a reference. Compared with the repository's previous seed data, 98 meanings change and one missing meaning is filled; 201 remain unchanged. The reviewed level has glossed_count: 300.

Examples:

The review also removes distracting specialist meanings, explains grammar particles and measure words, and restores common senses missing from the seed. Word IDs, membership, ordering, Chinese spellings, and pinyin are unchanged by this content update. Other levels and base languages are outside its scope.

Consumer action: Refresh cached level-1 English meanings. Fetch the full level again; retain learner records keyed by word_id. Refresh any locally generated flashcards or quiz options that contain old meanings. glossed_count measures coverage, not a content version: equal counts do not imply unchanged text.

Download all 99 seed-to-reviewed differences (CSV). The CSV's old_gloss values come from the HSK 2026 English seed before the September 2026 review, not a historical production snapshot. These describe the download's comparison baseline; the reviewed level-1 meanings are live on the public API. Empty old_gloss means the seed provided no meaning.

Reference: CC-CEDICT contributors, distributed by MDBG. Reference-informed gloss selections/adaptations are shared under CC BY-SA 4.0.

2026-09-22 — Standard-based vocabulary and meaning fields

Type: API contract and vocabulary content. Scope: HSK 2026, all levels.

Affected endpoints

• GET /api/v1/standards/hsk-2026/levels/
• GET /api/v1/standards/hsk-2026/levels/{level}/

Vocabulary membership comes from the official HSK 2026 file. The seven non-cumulative bands contain 300 / 200 / 500 / 1,000 / 1,600 / 1,800 / 5,600 words. The final band is named 7-9.

Response fields and query behavior

• Each word includes gloss, containing the meaning in the requested base language, or null if no meaning is recorded.
• ?base_language=en-US selects the meaning language. The default is en-US. Unknown or inactive language tags return HTTP 400; the API does not silently substitute another language.
• Both responses identify base_language. The vocabulary response includes glossed_count; the catalog includes a glossed_count for each level.
• Each word includes also_written, also_written_pinyin, and as_printed: {word, pinyin}. Alternate-form fields are null when absent. Optional notation is resolved for display in word and pinyin.

Changed display forms: hsk-2026:123 没(有) → 没有; hsk-2026:266 有(一)点儿 → 有一点儿; hsk-2026:481 有时(候) → 有时候; hsk-2026:1073 差(一)点儿 → 差一点儿; hsk-2026:3336 要不(然) → 要不然; hsk-2026:3971 凡(是) → 凡是. Their display pinyin changes correspondingly.

Consumer action: Allow the added response fields, handle gloss: null, and display word directly rather than stripping parentheses yourself. Use also_written to recognize the shorter spelling. Refresh cached vocabulary and continue keying learner records by the stable word_id.

This changelog begins with these changes; it is not a complete history of earlier API behavior.