{"openapi":"3.1.0","info":{"title":"ETHGlossary API","version":"0.1.0","description":"Ethereum terminology glossary and style guide. Canonical translations for 24 languages, English usage rules, and content-aware term filtering for translation pipelines.","license":{"name":"MPL-2.0","url":"https://www.mozilla.org/en-US/MPL/2.0/"}},"servers":[{"url":"https://glossary.ethereum.org"}],"components":{"securitySchemes":{"cookieAuth":{"type":"apiKey","in":"cookie","name":"ethglossary-session","description":"Set by signing in at /signin. Same-origin only."}},"schemas":{"Info":{"type":"object","properties":{"version":{"type":"string","example":"1.0.0"},"termCount":{"type":"number","example":486},"languageCount":{"type":"number","example":24},"lastUpdated":{"type":"string","example":"2026-04-12T00:00:00Z"},"languages":{"type":"array","items":{"type":"string"}}},"required":["version","termCount","languageCount","lastUpdated","languages"]},"StyleGuideList":{"type":"object","properties":{"termCount":{"type":"number","example":486},"terms":{"type":"array","items":{"$ref":"#/components/schemas/StyleGuideTerm"}}},"required":["termCount","terms"]},"StyleGuideTerm":{"type":"object","properties":{"id":{"type":"string","example":"onchain"},"term":{"type":"string","example":"onchain"},"category":{"type":"string","example":"general"},"termRole":{"type":"string","enum":["concept","brand-or-project","person-name","programming-language","os-platform","cryptographic-primitive","network-name","file-extension","cli-command","ticker-or-standard","identifier"],"example":"ticker-or-standard","description":"v1 policy term role (informs default script_rule). Optional; see docs/translation-policy.md section 4."},"casing":{"type":"string","enum":["standard","proper","uppercase","fixed"],"example":"standard"},"definition":{"type":"string","example":"Refers to actions or data that exist on the blockchain."},"references":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"url":{"type":"string"}},"required":["label","url"]},"example":[{"label":"Gas and fees","url":"https://ethereum.org/gas/"}],"description":"Further reading for this term. Present only when the term has any; `definition` never contains markup links."},"avoid":{"type":"array","items":{"type":"string"},"example":["on chain","on-chain","On Chain"]},"aliases":{"type":"array","items":{"type":"object","properties":{"term":{"type":"string"},"status":{"type":"string","enum":["preferred","accepted"]},"note":{"type":"string"}},"required":["term","status"]}},"note":{"type":"string","example":"Always one word, no hyphen, lowercase unless starting a sentence."},"scriptRule":{"type":"string","example":"translate"},"hasTooltip":{"type":"boolean","example":true}},"required":["id","term","category","casing","definition","scriptRule","hasTooltip"]},"SearchResult":{"type":"object","properties":{"query":{"type":"string","example":"staking"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"term":{"type":"string"},"matchedOn":{"type":"string","enum":["term","alias","avoid","definition","morphological"],"example":"term"},"score":{"type":"number","example":1}},"required":["id","term","matchedOn","score"]}}},"required":["query","results"]},"Error":{"type":"object","properties":{"error":{"type":"string","example":"Term not found"},"suggestions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"term":{"type":"string"},"score":{"type":"number"}},"required":["id","term","score"]},"description":"Close matches when term is not found"}},"required":["error"]},"LanguagesList":{"type":"object","properties":{"languages":{"type":"array","items":{"$ref":"#/components/schemas/LanguageInfo"}}},"required":["languages"]},"LanguageInfo":{"type":"object","properties":{"code":{"type":"string","example":"es"},"name":{"type":"string","example":"Spanish"},"translatedTerms":{"type":"number","example":486},"totalTerms":{"type":"number","example":486},"completionPercent":{"type":"number","example":100},"confidenceBreakdown":{"type":"object","properties":{"high":{"type":"number"},"medium":{"type":"number"},"low":{"type":"number"}},"required":["high","medium","low"]}},"required":["code","name","translatedTerms","totalTerms","completionPercent","confidenceBreakdown"]},"TranslationFile":{"type":"object","properties":{"language":{"type":"string","example":"es"},"termCount":{"type":"number","example":486},"terms":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/TranslationTerm"}}},"required":["language","termCount","terms"]},"TranslationTerm":{"type":"object","properties":{"term":{"type":"string","example":"staking"},"contexts":{"type":"object","properties":{"prose":{"type":"object","properties":{"term":{"type":"string"},"example":{"type":"string"}},"required":["term"]},"heading":{"type":"object","properties":{"term":{"type":"string"}},"required":["term"]},"tag":{"type":"object","properties":{"term":{"type":"string"}},"required":["term"]},"ui":{"type":"object","properties":{"term":{"type":"string"}},"required":["term"]}}},"plurals":{"type":"object","properties":{"one":{"type":["string","null"]},"two":{"type":["string","null"]},"few":{"type":["string","null"]},"many":{"type":["string","null"]},"other":{"type":["string","null"]}},"required":["one","other"]},"grammar":{"type":"object","properties":{"gender":{"type":"string"},"partOfSpeech":{"type":"string"},"formality":{"type":"string"}}},"confidence":{"type":"string","enum":["high","medium","low"],"example":"high"},"notes":{"type":"string"}},"required":["term","confidence"]},"SingleTranslation":{"type":"object","properties":{"english":{"type":"object","properties":{"id":{"type":"string"},"term":{"type":"string"},"definition":{"type":"string"}},"required":["id","term","definition"]},"translation":{"$ref":"#/components/schemas/TranslationTerm"}},"required":["english","translation"]},"FilterResponse":{"type":"object","properties":{"language":{"type":"string","example":"es"},"matchedTerms":{"type":"number","example":5},"totalScanned":{"type":"number","example":486},"terms":{"type":"array","items":{"type":"object","properties":{"english":{"type":"string","example":"staking"},"translation":{"type":"string","example":"staking"},"note":{"type":"string"},"example":{"type":"string"},"occurrences":{"type":"number","example":3}},"required":["english","translation","occurrences"]}}},"required":["language","matchedTerms","totalScanned","terms"]},"FilterRequest":{"type":"object","properties":{"content":{"type":"string","maxLength":1048576,"example":"Staking is the act of depositing 32 ETH to activate validator software...","description":"Source text to filter against (max 1MB)"},"language":{"type":"string","minLength":2,"maxLength":5,"example":"es","description":"Target language code"},"fileType":{"type":"string","enum":["markdown","json"],"default":"markdown","example":"markdown","description":"Source content type (affects text extraction)"},"includeExamples":{"type":"boolean","default":false,"description":"Include example sentences for high-frequency terms (2+ occurrences)"}},"required":["content","language"]},"FeedbackVotesResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"tallies":{"type":"array","items":{"type":"object","properties":{"context":{"type":"string","enum":["prose","heading","tag","ui","plurals"],"description":"The translation slot the feedback is about","example":"prose"},"hash":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"Content hash of the value as rendered; the server refuses with 409 if it no longer matches","example":"2e69ecb0f9b3fb9dd37c0ed376166171"},"up":{"type":"integer"},"down":{"type":"integer"},"mine":{"type":["string","null"],"enum":["up","down",null]}},"required":["context","hash","up","down","mine"]}}},"required":["ok","tallies"]},"FeedbackError":{"type":"object","properties":{"error":{"type":"string"},"current":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"Content hash of the value as rendered; the server refuses with 409 if it no longer matches","example":"2e69ecb0f9b3fb9dd37c0ed376166171"},"context":{"type":"string","enum":["prose","heading","tag","ui","plurals"],"description":"The translation slot the feedback is about","example":"prose"},"field":{"type":"string","enum":["definition"],"description":"The English field the feedback is about","example":"definition"}},"required":["error"]},"FeedbackVotes":{"type":"object","properties":{"votes":{"type":"array","items":{"type":"object","properties":{"context":{"type":"string","enum":["prose","heading","tag","ui","plurals"],"description":"The translation slot the feedback is about","example":"prose"},"hash":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"Content hash of the value as rendered; the server refuses with 409 if it no longer matches","example":"2e69ecb0f9b3fb9dd37c0ed376166171"},"direction":{"type":"string","enum":["up","down","none"],"description":"`none` clears your vote"}},"required":["context","hash","direction"]},"minItems":1,"maxItems":5}},"required":["votes"]},"FeedbackFieldVotesResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"tallies":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["definition"],"description":"The English field the feedback is about","example":"definition"},"hash":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"Content hash of the value as rendered; the server refuses with 409 if it no longer matches","example":"2e69ecb0f9b3fb9dd37c0ed376166171"},"up":{"type":"integer"},"down":{"type":"integer"},"mine":{"type":["string","null"],"enum":["up","down",null]}},"required":["field","hash","up","down","mine"]}}},"required":["ok","tallies"]},"FeedbackFieldVotes":{"type":"object","properties":{"votes":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["definition"],"description":"The English field the feedback is about","example":"definition"},"hash":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"Content hash of the value as rendered; the server refuses with 409 if it no longer matches","example":"2e69ecb0f9b3fb9dd37c0ed376166171"},"direction":{"type":"string","enum":["up","down","none"],"description":"`none` clears your vote"}},"required":["field","hash","direction"]},"minItems":1,"maxItems":5}},"required":["votes"]},"FeedbackSuggestionResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"duplicate":{"type":"boolean","description":"True when you had already suggested this exact value"}},"required":["id","duplicate"]},"FeedbackSuggestion":{"type":"object","properties":{"context":{"type":"string","enum":["prose","heading","tag","ui","plurals"],"description":"The translation slot the feedback is about","example":"prose"},"hash":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"Content hash of the value as rendered; the server refuses with 409 if it no longer matches","example":"2e69ecb0f9b3fb9dd37c0ed376166171"},"value":{"type":"string","minLength":1,"maxLength":700,"description":"Up to 200 characters, except plurals: `category=form` pairs joined by `|`, up to 100 per form","example":"cuenta"},"reason":{"type":"string","maxLength":1000,"description":"Why this is better. Optional."}},"required":["context","hash","value"]},"FeedbackProposalResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"]},"FeedbackProposal":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["new_term"]},"lang":{"type":"string","minLength":2,"maxLength":5,"description":"Language being reviewed, if a translation is seeded"},"payload":{"type":"object","properties":{"term":{"type":"string","minLength":1,"maxLength":120},"definition":{"type":"string","maxLength":2000},"translation":{"type":"object","properties":{"lang":{"type":"string","minLength":2,"maxLength":5},"prose":{"type":"string","minLength":1,"maxLength":200}},"required":["lang","prose"]}},"required":["term"]},"reason":{"type":"string","maxLength":1000}},"required":["kind","payload"]},{"type":"object","properties":{"kind":{"type":"string","enum":["redundant"]},"termId":{"type":"string","minLength":1,"maxLength":200,"description":"A term id, name, alias or variant","example":"gas"},"hash":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"Content hash of the value as rendered; the server refuses with 409 if it no longer matches","example":"2e69ecb0f9b3fb9dd37c0ed376166171"},"payload":{"type":"object","properties":{"with":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200,"description":"A term id, name, alias or variant","example":"gas"},"minItems":1,"maxItems":10}},"required":["with"]},"reason":{"type":"string","maxLength":1000}},"required":["kind","termId","payload"]},{"type":"object","properties":{"kind":{"type":"string","enum":["split"]},"termId":{"type":"string","minLength":1,"maxLength":200,"description":"A term id, name, alias or variant","example":"gas"},"hash":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"Content hash of the value as rendered; the server refuses with 409 if it no longer matches","example":"2e69ecb0f9b3fb9dd37c0ed376166171"},"payload":{"type":"object","properties":{"into":{"type":"array","items":{"type":"object","properties":{"term":{"type":"string","minLength":1,"maxLength":120},"definition":{"type":"string","maxLength":2000}},"required":["term"]},"minItems":2,"maxItems":10}},"required":["into"]},"reason":{"type":"string","maxLength":1000}},"required":["kind","termId","payload"]},{"type":"object","properties":{"kind":{"type":"string","enum":["definition"]},"termId":{"type":"string","minLength":1,"maxLength":200,"description":"A term id, name, alias or variant","example":"gas"},"hash":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"Content hash of the value as rendered; the server refuses with 409 if it no longer matches","example":"2e69ecb0f9b3fb9dd37c0ed376166171"},"payload":{"type":"object","properties":{"definition":{"type":"string","minLength":1,"maxLength":2000}},"required":["definition"]},"reason":{"type":"string","maxLength":1000}},"required":["kind","termId","hash","payload"]},{"type":"object","properties":{"kind":{"type":"string","enum":["note"]},"termId":{"type":"string","minLength":1,"maxLength":200,"description":"A term id, name, alias or variant","example":"gas"},"hash":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"Content hash of the value as rendered; the server refuses with 409 if it no longer matches","example":"2e69ecb0f9b3fb9dd37c0ed376166171"},"payload":{"type":"object","properties":{"note":{"type":["string","null"],"minLength":1,"maxLength":1000,"description":"`null` proposes removing the note"}},"required":["note"]},"reason":{"type":"string","maxLength":1000}},"required":["kind","termId","hash","payload"]},{"type":"object","properties":{"kind":{"type":"string","enum":["references"]},"termId":{"type":"string","minLength":1,"maxLength":200,"description":"A term id, name, alias or variant","example":"gas"},"hash":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"Content hash of the value as rendered; the server refuses with 409 if it no longer matches","example":"2e69ecb0f9b3fb9dd37c0ed376166171"},"payload":{"type":"object","properties":{"add":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":120},"url":{"type":"string","format":"uri"}},"required":["label","url"]},"maxItems":10},"remove":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":10}}},"reason":{"type":"string","maxLength":1000}},"required":["kind","termId","hash","payload"]},{"type":"object","properties":{"kind":{"type":"string","enum":["avoid"]},"termId":{"type":"string","minLength":1,"maxLength":200,"description":"A term id, name, alias or variant","example":"gas"},"hash":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"Content hash of the value as rendered; the server refuses with 409 if it no longer matches","example":"2e69ecb0f9b3fb9dd37c0ed376166171"},"payload":{"type":"object","properties":{"add":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":10},"remove":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":10}}},"reason":{"type":"string","maxLength":1000}},"required":["kind","termId","hash","payload"]},{"type":"object","properties":{"kind":{"type":"string","enum":["alias"]},"termId":{"type":"string","minLength":1,"maxLength":200,"description":"A term id, name, alias or variant","example":"gas"},"hash":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"Content hash of the value as rendered; the server refuses with 409 if it no longer matches","example":"2e69ecb0f9b3fb9dd37c0ed376166171"},"payload":{"type":"object","properties":{"add":{"type":"array","items":{"type":"object","properties":{"term":{"type":"string","minLength":1,"maxLength":120},"status":{"type":"string","enum":["preferred","accepted","deprecated"]}},"required":["term"]},"maxItems":10},"remove":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":10}}},"reason":{"type":"string","maxLength":1000}},"required":["kind","termId","hash","payload"]},{"type":"object","properties":{"kind":{"type":"string","enum":["casing"]},"termId":{"type":"string","minLength":1,"maxLength":200,"description":"A term id, name, alias or variant","example":"gas"},"hash":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"Content hash of the value as rendered; the server refuses with 409 if it no longer matches","example":"2e69ecb0f9b3fb9dd37c0ed376166171"},"payload":{"type":"object","properties":{"casing":{"type":"string","enum":["standard","proper","uppercase","fixed"]}},"required":["casing"]},"reason":{"type":"string","maxLength":1000}},"required":["kind","termId","hash","payload"]},{"type":"object","properties":{"kind":{"type":"string","enum":["category"]},"termId":{"type":"string","minLength":1,"maxLength":200,"description":"A term id, name, alias or variant","example":"gas"},"hash":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"Content hash of the value as rendered; the server refuses with 409 if it no longer matches","example":"2e69ecb0f9b3fb9dd37c0ed376166171"},"payload":{"type":"object","properties":{"category":{"type":"string","minLength":1,"maxLength":40}},"required":["category"]},"reason":{"type":"string","maxLength":1000}},"required":["kind","termId","hash","payload"]},{"type":"object","properties":{"kind":{"type":"string","enum":["script_rule"]},"termId":{"type":"string","minLength":1,"maxLength":200,"description":"A term id, name, alias or variant","example":"gas"},"hash":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"Content hash of the value as rendered; the server refuses with 409 if it no longer matches","example":"2e69ecb0f9b3fb9dd37c0ed376166171"},"payload":{"type":"object","properties":{"script_rule":{"type":"string","enum":["translate","calque","transliterate","keep_latin","always_latin","transliterate_with_translation"]}},"required":["script_rule"]},"reason":{"type":"string","maxLength":1000}},"required":["kind","termId","hash","payload"]}]},"FeedbackProposalBatchResponse":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["ids"]},"FeedbackProposalBatch":{"type":"object","properties":{"proposals":{"type":"array","items":{"$ref":"#/components/schemas/FeedbackProposal"},"minItems":1,"maxItems":10}},"required":["proposals"]}},"parameters":{}},"paths":{"/api/v1/info":{"get":{"tags":["Info"],"summary":"API metadata and health check","responses":{"200":{"description":"API metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Info"}}}}}}},"/api/v1/style-guide":{"get":{"tags":["Style Guide"],"summary":"Full English style guide","description":"All terms with canonical forms, casing rules, avoid lists, and usage notes.","parameters":[{"schema":{"type":"string","example":"defi,scaling","description":"Filter by category (comma-separated)"},"required":false,"description":"Filter by category (comma-separated)","name":"category","in":"query"}],"responses":{"200":{"description":"Style guide terms","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StyleGuideList"}}}}}}},"/api/v1/style-guide/search":{"get":{"tags":["Style Guide"],"summary":"Search the style guide","description":"Fuzzy search across terms, definitions, aliases, and avoid lists.","parameters":[{"schema":{"type":"string","minLength":1,"example":"staking","description":"Search query"},"required":true,"description":"Search query","name":"q","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Max results (default: 20)"},"required":false,"description":"Max results (default: 20)","name":"limit","in":"query"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"}}}}}}},"/api/v1/style-guide/{termId}":{"get":{"tags":["Style Guide"],"summary":"Look up a single term","description":"Intelligent matching: resolves aliases, avoid forms, and morphological variants.","parameters":[{"schema":{"type":"string","minLength":1,"example":"staking","description":"Term ID, alias, or variant (intelligent matching)"},"required":true,"description":"Term ID, alias, or variant (intelligent matching)","name":"termId","in":"path"}],"responses":{"200":{"description":"The style guide entry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StyleGuideTerm"}}}},"404":{"description":"Term not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/languages":{"get":{"tags":["Translations"],"summary":"List supported languages with completion stats","responses":{"200":{"description":"Supported languages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LanguagesList"}}}}}}},"/api/v1/translations/{lang}":{"get":{"tags":["Translations"],"summary":"Full glossary for a language","description":"All translated terms with contextual forms, plurals, and grammar.","parameters":[{"schema":{"type":"string","minLength":2,"maxLength":5,"example":"es","description":"Language code (e.g., es, ja, zh-tw)"},"required":true,"description":"Language code (e.g., es, ja, zh-tw)","name":"lang","in":"path"}],"responses":{"200":{"description":"Full translation file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslationFile"}}}},"404":{"description":"Language not supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/translations/{lang}/{termId}":{"get":{"tags":["Translations"],"summary":"Single term translation","description":"Look up a term translation with intelligent matching. Returns English source alongside translation.","parameters":[{"schema":{"type":"string","minLength":2,"maxLength":5,"example":"es","description":"Language code (e.g., es, ja, zh-tw)"},"required":true,"description":"Language code (e.g., es, ja, zh-tw)","name":"lang","in":"path"},{"schema":{"type":"string","minLength":1,"example":"staking","description":"Term ID, alias, or variant (intelligent matching)"},"required":true,"description":"Term ID, alias, or variant (intelligent matching)","name":"termId","in":"path"}],"responses":{"200":{"description":"Term translation with English source","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleTranslation"}}}},"404":{"description":"Term or language not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/filter":{"post":{"tags":["Filter"],"summary":"Filter glossary terms for source content","description":"Send source text and get back the glossary terms relevant to that content. Strips code blocks, inline code, and URLs before matching. Max 1MB content size.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilterRequest"}}}},"responses":{"200":{"description":"Matching glossary terms","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilterResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/schema":{"get":{"tags":["Schema"],"summary":"Glossary data schema","description":"JSON Schema definition for the glossary data structure.","responses":{"200":{"description":"The glossary JSON schema","content":{"application/json":{"schema":{}}}}}}},"/api/v1/feedback/translations/{lang}/{termId}/votes":{"put":{"tags":["Feedback"],"summary":"Vote on one or more translation slots","description":"One vote per person per slot value. `up`, `down`, or `none` to clear. Each item carries the hash of the value as rendered; a stale hash is refused with 409. Requires a session cookie.","security":[{"cookieAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":5,"example":"es","description":"Language code (e.g., es, ja, zh-tw)"},"required":true,"description":"Language code (e.g., es, ja, zh-tw)","name":"lang","in":"path"},{"schema":{"type":"string","minLength":1,"example":"staking","description":"Term ID, alias, or variant (intelligent matching)"},"required":true,"description":"Term ID, alias, or variant (intelligent matching)","name":"termId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackVotes"}}}},"responses":{"200":{"description":"Current tallies for the slots voted on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackVotesResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"403":{"description":"Cross-origin request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"404":{"description":"Unknown term or language","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"409":{"description":"The value changed since the page loaded; reload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"415":{"description":"Body is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"429":{"description":"Too many writes; wait","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"503":{"description":"Database unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}}}}},"/api/v1/feedback/style-guide/{termId}/votes":{"put":{"tags":["Feedback"],"summary":"Vote on a term's English definition","description":"The style-guide counterpart of translation votes: one vote per person per version of the field. Each item carries the hash of the field as rendered; a stale hash is refused with 409. Requires a session cookie.","security":[{"cookieAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"example":"staking","description":"Term ID, alias, or variant (intelligent matching)"},"required":true,"description":"Term ID, alias, or variant (intelligent matching)","name":"termId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackFieldVotes"}}}},"responses":{"200":{"description":"Current tallies for the fields voted on","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackFieldVotesResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"403":{"description":"Cross-origin request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"404":{"description":"Unknown term or language","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"409":{"description":"The value changed since the page loaded; reload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"415":{"description":"Body is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"429":{"description":"Too many writes; wait","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"503":{"description":"Database unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}}}}},"/api/v1/feedback/translations/{lang}/{termId}/suggestions":{"post":{"tags":["Feedback"],"summary":"Suggest a different translation for one slot","description":"Visible only to you and to the maintainers. Suggesting the same value twice is a no-op that reports `duplicate: true`. Requires a session cookie.","security":[{"cookieAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":5,"example":"es","description":"Language code (e.g., es, ja, zh-tw)"},"required":true,"description":"Language code (e.g., es, ja, zh-tw)","name":"lang","in":"path"},{"schema":{"type":"string","minLength":1,"example":"staking","description":"Term ID, alias, or variant (intelligent matching)"},"required":true,"description":"Term ID, alias, or variant (intelligent matching)","name":"termId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackSuggestion"}}}},"responses":{"201":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackSuggestionResponse"}}}},"400":{"description":"Suggestion equals the current value","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"403":{"description":"Cross-origin request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"404":{"description":"Unknown term or language","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"409":{"description":"The value changed since the page loaded; reload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"415":{"description":"Body is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"429":{"description":"Too many writes; wait","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"503":{"description":"Database unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}}}}},"/api/v1/feedback/suggestions/{id}":{"delete":{"tags":["Feedback"],"summary":"Withdraw one of your open suggestions","security":[{"cookieAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Withdrawn"},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"404":{"description":"Not yours, not open, or not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}}}}},"/api/v1/feedback/suggestions/{id}/reopen":{"post":{"tags":["Feedback"],"summary":"Re-submit one of your withdrawn suggestions","security":[{"cookieAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Open again"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"403":{"description":"Cross-origin request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"404":{"description":"No such withdrawn suggestion of yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"409":{"description":"The value changed since the page loaded; reload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"415":{"description":"Body is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"429":{"description":"Too many writes; wait","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"503":{"description":"Database unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}}}}},"/api/v1/feedback/proposals/{id}/reopen":{"post":{"tags":["Feedback"],"summary":"Re-submit one of your withdrawn proposals","security":[{"cookieAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Open again"},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"403":{"description":"Cross-origin request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"404":{"description":"No such withdrawn proposal of yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"409":{"description":"The value changed since the page loaded; reload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"415":{"description":"Body is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"429":{"description":"Too many writes; wait","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"503":{"description":"Database unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}}}}},"/api/v1/feedback/proposals":{"post":{"tags":["Feedback"],"summary":"Propose a new term, flag a term as redundant or in need of a split, or suggest a change to a term's English metadata","description":"One endpoint, one payload shape per `kind`. Metadata kinds carry the hash of the English entry as rendered and are refused with 409 when it has changed. Requires a session cookie.","security":[{"cookieAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackProposal"}}}},"responses":{"201":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackProposalResponse"}}}},"400":{"description":"A referenced term does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"403":{"description":"Cross-origin request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"404":{"description":"Unknown term or language","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"409":{"description":"The value changed since the page loaded; reload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"415":{"description":"Body is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"429":{"description":"Too many writes; wait","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"503":{"description":"Database unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}}}}},"/api/v1/feedback/proposals/batch":{"post":{"tags":["Feedback"],"summary":"Record several proposals in one transaction","description":"Every item is checked first; any refusal answers for the whole batch and nothing is recorded. Counts against the proposals limit once per item. Requires a session cookie.","security":[{"cookieAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackProposalBatch"}}}},"responses":{"201":{"description":"Recorded, ids in request order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackProposalBatchResponse"}}}},"400":{"description":"A referenced term does not exist, or an item is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"403":{"description":"Cross-origin request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"404":{"description":"Unknown term or language","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"409":{"description":"The value changed since the page loaded; reload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"415":{"description":"Body is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"429":{"description":"Too many writes; wait","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"503":{"description":"Database unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}}}}},"/api/v1/feedback/proposals/{id}":{"delete":{"tags":["Feedback"],"summary":"Withdraw one of your open proposals","security":[{"cookieAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Withdrawn"},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}},"404":{"description":"Not yours, not open, or not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackError"}}}}}}}},"webhooks":{}}