{"openapi":"3.1.0","info":{"title":"Tubeofile API","version":"1.0.0","description":"Public read-only JSON API for Tubeofile — vacuum tube specifications, pinouts, equivalents, and rolling (substitution) analysis. All endpoints are unauthenticated, CORS-open, and cacheable. See https://tubeofile.com/api-docs for human-readable documentation.","contact":{"name":"Tubeofile","url":"https://tubeofile.com/contact"},"license":{"name":"CC BY-SA 4.0","url":"https://creativecommons.org/licenses/by-sa/4.0/"}},"servers":[{"url":"https://tubeofile.com","description":"Production"}],"tags":[{"name":"tubes","description":"Tube data and search"}],"paths":{"/api/tubes/index":{"get":{"tags":["tubes"],"operationId":"listAllTubes","summary":"List all tubes","description":"Returns a lightweight listing of every tube in the database. Start here to discover all available type numbers, then call `/api/tubes/{type_number}` for full data on specific tubes.","responses":{"200":{"description":"Full index of tubes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TubeIndex"}}}}}}},"/api/tubes/{type_number}":{"get":{"tags":["tubes"],"operationId":"getTube","summary":"Get a single tube","description":"Returns full structured data for one tube — specs, pinout, equivalents, similar tubes, and source references. URL-encode type numbers that contain `/` or `,` (e.g. `5A%2F152M` for `5A/152M`).","parameters":[{"name":"type_number","in":"path","required":true,"description":"The canonical tube type number (URL-encoded).","schema":{"type":"string"},"examples":{"EL34":{"value":"EL34"},"12AX7":{"value":"12AX7"},"slash":{"value":"5A%2F152M","summary":"5A/152M (URL-encoded)"}}}],"responses":{"200":{"description":"Full tube data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tube"}}}},"404":{"description":"No tube with that type_number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tubes":{"get":{"tags":["tubes"],"operationId":"searchTubes","summary":"Search and filter tubes","description":"Full-text search and filtering over the tube database. Returns an array of summary tube objects. Use `autocomplete=1` for prefix-match type_number autocomplete.","parameters":[{"name":"q","in":"query","description":"Full-text search query (searches type_number, description, notes, manufacturer).","schema":{"type":"string"}},{"name":"autocomplete","in":"query","description":"Set to `1` for prefix-match autocomplete (requires `q`).","schema":{"type":"string","enum":["1"]}},{"name":"type","in":"query","description":"Filter by tube_type_key.","schema":{"type":"string","enum":["power_triode","small_signal_triode","power_pentode","ss_pentode","beam_tetrode","rectifier","voltage_regulator","diode","compound"]}},{"name":"base_id","in":"query","description":"Filter by tube base UUID.","schema":{"type":"string","format":"uuid"}},{"name":"vh","in":"query","description":"Filter by heater voltage. Use `other` to match non-standard voltages.","schema":{"type":"string","examples":["2.5","4","5","6.3","12.6","other"]}},{"name":"dht","in":"query","description":"`1` for directly heated only, `0` for indirectly heated only.","schema":{"type":"string","enum":["0","1"]}},{"name":"limit","in":"query","description":"Max results (default 50, max 200).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","description":"Pagination offset (default 0).","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Matching tubes","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TubeSummary"}}}}}}}}},"components":{"schemas":{"TubeIndex":{"type":"object","required":["count","generated_at","tubes"],"properties":{"count":{"type":"integer","description":"Total tube count"},"generated_at":{"type":"string","format":"date-time"},"tubes":{"type":"array","items":{"$ref":"#/components/schemas/TubeIndexEntry"}}}},"TubeIndexEntry":{"type":"object","required":["type_number","url","api_url"],"properties":{"type_number":{"type":"string","example":"EL34"},"manufacturer":{"type":"string","nullable":true},"tube_type_key":{"type":"string","nullable":true,"example":"power_pentode"},"tube_type":{"type":"string","nullable":true,"example":"Power pentode"},"base":{"type":"string","nullable":true,"example":"Octal"},"is_directly_heated":{"type":"boolean","nullable":true},"completeness":{"type":"string","nullable":true,"enum":["high","medium","low"],"description":"Data quality tier. high = all core data present, medium = ≥60% of core data, low = significant gaps."},"url":{"type":"string","format":"uri","description":"Human-readable HTML page"},"api_url":{"type":"string","format":"uri","description":"Full JSON data endpoint"}}},"TubeSummary":{"type":"object","description":"Summary shape returned by the search endpoint — includes core fields used by the UI browse list.","properties":{"id":{"type":"string","format":"uuid"},"type_number":{"type":"string"},"manufacturer":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"tube_type_key":{"type":"string","nullable":true},"tube_type_display_name":{"type":"string","nullable":true},"base_name":{"type":"string","nullable":true},"is_directly_heated":{"type":"boolean","nullable":true}}},"Tube":{"type":"object","required":["type_number","canonical_url","pins","specs"],"properties":{"type_number":{"type":"string","example":"EL34"},"canonical_url":{"type":"string","format":"uri"},"manufacturer":{"type":"string","nullable":true},"tube_type_key":{"type":"string","nullable":true},"tube_type_display_name":{"type":"string","nullable":true},"base_name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"is_directly_heated":{"type":"boolean","nullable":true},"completeness":{"type":"string","nullable":true,"enum":["high","medium","low"],"description":"Data quality tier assigned by the import skill."},"notes":{"type":"array","items":{"type":"string"}},"references":{"type":"array","items":{"type":"string","format":"uri"}},"source_urls":{"type":"object","properties":{"r_type":{"type":"string","format":"uri","nullable":true},"tdsl":{"type":"string","format":"uri","nullable":true},"radiomuseum":{"type":"string","format":"uri","nullable":true}}},"raw_equivalents":{"type":"array","items":{"type":"string"}},"equivalents":{"type":"array","items":{"type":"object","properties":{"type_number":{"type":"string"},"equivalence_type":{"type":"string","enum":["direct","near"]},"notes":{"type":"string","nullable":true}}}},"similar":{"type":"array","items":{"type":"object","properties":{"type_number":{"type":"string"},"reason":{"type":"string"},"has_detail_page":{"type":"boolean"}}}},"pins":{"type":"array","items":{"$ref":"#/components/schemas/Pin"}},"specs":{"type":"array","description":"Flat specs (non-compound tubes, or heater-level params shared across sections).","items":{"$ref":"#/components/schemas/Spec"}},"sections":{"type":"array","description":"Section-scoped specs for compound tubes (e.g. ECL82 triode+pentode). Empty for simple tubes.","items":{"type":"object","properties":{"section_number":{"type":"integer"},"section_label":{"type":"string"},"tube_type_key":{"type":"string"},"specs":{"type":"array","items":{"$ref":"#/components/schemas/Spec"}}}}},"synced_at":{"type":"string","format":"date-time"}}},"Pin":{"type":"object","properties":{"pin_number":{"type":"string","example":"1"},"function":{"type":"string","nullable":true,"example":"Suppressor grid"},"function_code":{"type":"string","nullable":true,"example":"g3"},"notes":{"type":"string","nullable":true}}},"Spec":{"type":"object","properties":{"key":{"type":"string","nullable":true,"description":"Canonical parameter key (e.g. Vh, mu, gm, ra, mAa, Pa_max)"},"display_name":{"type":"string","nullable":true},"value":{"type":"string","nullable":true,"description":"Raw string value as captured from the datasheet"},"numeric_value":{"type":"number","nullable":true,"description":"Parsed numeric value for computation"},"unit":{"type":"string","nullable":true},"param_group":{"type":"string","nullable":true,"enum":["heater","absolute_max","typical_operating","output","capacitances","rectifier","noise_rf","voltage_regulator"]}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"not_found"},"message":{"type":"string"}}}}}}