{"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://ethglossary.visual-20-hoists.workers.dev"}],"components":{"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."},"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"]},"code":{"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":102400,"example":"Staking is the act of depositing 32 ETH to activate validator software...","description":"Source text to filter against (max 100KB)"},"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"]}},"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 100KB 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":{}}}}}}}},"webhooks":{}}