{"openapi":"3.1.0","info":{"title":"Gotha API","description":"REST API nad Wikibase Gotha (gotha.wikibase.cloud) pro gotha-viewer a scan2structured pipeline. Všechny odpovědi mají tvar `{ok, status, data?, meta}` resp. `{ok:false, error, error_code, status}`.","version":"1.0.0"},"servers":[{"url":"/gotha/api"}],"paths":{"/v1/families":{"get":{"tags":["viewer"],"summary":"Seznam všech šlechtických rodů","description":"Vrátí rody (instance Q9) s labely cs/de/en, počtem členů a Wikidata ID. Cache 24 h, `?force=1` přepíše.","operationId":"families_v1_families_get","parameters":[{"name":"lang","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lang"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Families V1 Families Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/family/{qid}":{"get":{"tags":["viewer"],"summary":"Metadata jednoho rodu","description":"Hlavička detailu rodu: labely a Wikidata ID. 404, pokud entita neexistuje nebo není instance rodu. Cache 24 h.","operationId":"family_v1_family__qid__get","parameters":[{"name":"qid","in":"path","required":true,"schema":{"type":"string","title":"Qid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Family V1 Family  Qid  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/family/{qid}/members":{"get":{"tags":["viewer"],"summary":"Členové rodu + vztahy (pro genealogický strom)","description":"Přímí členové (P39) + potomci členů bez vlastního rodu (isMemberChild=true). Data narození/úmrtí zkrácena na YYYY-MM-DD, řazeno dle narození. Cache 24 h.","operationId":"family_members_v1_family__qid__members_get","parameters":[{"name":"qid","in":"path","required":true,"schema":{"type":"string","title":"Qid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Family Members V1 Family  Qid  Members Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/search":{"get":{"tags":["viewer"],"summary":"Plnosttextové vyhledávání nad labely","description":"Case-insensitive shoda podřetězce v labelech cs/de/en osob (Q5) a/nebo rodů (Q9). Výsledky deduplikovány dle id. Cache 1 h.","operationId":"search_v1_search_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Q"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}},{"name":"type","in":"query","required":false,"schema":{"type":"string","default":"all","title":"Type"}},{"name":"lang","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lang"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Search V1 Search Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/meta":{"get":{"tags":["viewer"],"summary":"Souhrnný stav API a SPARQL endpointu","description":"Agregovaný status pro monitoring: dostupnost SPARQL, počty rodů/osob a stav cache adresáře. Cache 5 minut; při výpadku SPARQL 503.","operationId":"meta_v1_meta_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Meta V1 Meta Get"}}}}}}},"/v1/persons/search":{"get":{"tags":["persons"],"summary":"Hledání osoby podle rodové linie a křestního jména","description":"Tokeny z `family` a `given` hledají v labelech i altLabelech (case-insensitive AND). Pokud je zadáno `birth_date`/`death_date` (YYYY, YYYY-MM nebo YYYY-MM-DD), proxy preferuje kandidáty se shodou v dané přesnosti; když žádný nekandiduje se shodou, vrátí všechny tokenové kandidáty. Cache 15 min.","operationId":"persons_search_v1_persons_search_get","parameters":[{"name":"family","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Family"}},{"name":"given","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Given"}},{"name":"birth_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Birth Date"}},{"name":"death_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Death Date"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":10,"title":"Limit"}},{"name":"lang","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lang"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Persons Search V1 Persons Search Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/persons/by-parent":{"get":{"tags":["persons"],"summary":"Potomci zadaného z rodiče","description":"Vrátí osoby, jejichž otec (P3) nebo matka (P4) je `parent`. Výstupní forma je shodná s persons/search; `gender`/`family_qid` jsou QIDy nebo null. Cache 15 min.","operationId":"persons_by_parent_v1_persons_by_parent_get","parameters":[{"name":"parent","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent"}},{"name":"family","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Family"}},{"name":"relation","in":"query","required":false,"schema":{"type":"string","default":"any","title":"Relation"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":3,"title":"Limit"}},{"name":"lang","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lang"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Persons By Parent V1 Persons By Parent Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/persons/duplicates":{"get":{"tags":["persons"],"summary":"Detekce příbuzných kandidátů (duplicit)","description":"Vrátí členy rodu (P39) s křestním jménem v cs labelu; výsledky se shodou `birth_year` jdou na začátek. Výstupní `source` je prozatím vždy `family_match`. Cache 15 min.","operationId":"persons_duplicates_v1_persons_duplicates_get","parameters":[{"name":"given","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Given"}},{"name":"family_qid","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Family Qid"}},{"name":"birth_year","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Birth Year"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":10,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Persons Duplicates V1 Persons Duplicates Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/persons/by-date":{"get":{"tags":["persons"],"summary":"Osoby podle data narození nebo úmrtí","description":"Hledá osoby s datem narození (P33) nebo úmrtí (P34): `birth_date`/`death_date` přijímají YYYY (celý rok), YYYY-MM (celý měsíc) i YYYY-MM-DD (přesný den), případně interval `from_date`–`to_date` (použije se na narození i úmrtí). Alespoň jeden parametr je povinný. Cache 15 min.","operationId":"persons_by_date_v1_persons_by_date_get","parameters":[{"name":"birth_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Birth Date"}},{"name":"death_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Death Date"}},{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From Date"}},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To Date"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}},{"name":"lang","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lang"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Persons By Date V1 Persons By Date Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/entity/{qid}":{"get":{"tags":["entities"],"summary":"Entita podle QID","description":"Vrací celou entitu přes `wbgetentities`. `display=compact` (výchozí): bez agregovaných labelů. `display=full`: u každého statementu přibude `property_label` (label vlastnosti), u item hodnot `value_uuid`/`value_label`/`value_url` (labely dle `lang` fallbacku) + `label`/`label_url` a `wiki_url` v rootu. Cache 5 min.","operationId":"entity_v1_entity__qid__get","parameters":[{"name":"qid","in":"path","required":true,"schema":{"type":"string","title":"Qid"}},{"name":"lang","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lang"}},{"name":"display","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Entity V1 Entity  Qid  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/entity/{qid}/llm-models":{"get":{"tags":["entities"],"summary":"LLM existence/model entity (P26 qualifier)","description":"Prohledá statementy instance (gp:P31) entity a vrátí hodnoty kvalifikátoru llm_model (P26). Výstupní modely jsou deduplikované; prázdné pole znamená, že entita žádný model nemá. Cache 5 min.","operationId":"llm_models_v1_entity__qid__llm_models_get","parameters":[{"name":"qid","in":"path","required":true,"schema":{"type":"string","title":"Qid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Llm Models V1 Entity  Qid  Llm Models Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/entity/{qid}/backlinks":{"get":{"tags":["entities"],"summary":"Příchozí odkazy na entitu (nový endpoint)","description":"Vrátí entity, které odkazují na zadanou entitu jako hodnotu statementu (subject + property). Výstup: qid, label (dle `lang` fallbacku), pid. Cache 5 min.","operationId":"backlinks_v1_entity__qid__backlinks_get","parameters":[{"name":"qid","in":"path","required":true,"schema":{"type":"string","title":"Qid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"lang","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lang"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Backlinks V1 Entity  Qid  Backlinks Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/entities/lookup":{"post":{"tags":["entities"],"summary":"Dávkový lookup entit (nový endpoint)","description":"Body `{qids: [...]}` (max 500). Vrací `data` = map qid → kompaktní entita (labels, aliases, claims s REST hodnotami, bez referencí). Neexistující/nevalidní QIDy jsou vynechány (hlášeno v meta). Cache 1 h.","operationId":"entities_lookup_v1_entities_lookup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityLookupRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Entities Lookup V1 Entities Lookup Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/items/lookup":{"post":{"tags":["items"],"summary":"Mapování CSV textové hodnoty na QID položky","description":"Body `{items: [{column, value, class}]}` (max 500). Hledá přesnou shodu dotazu (case-insensitive) v labelech i altLabelech položek dané třídy (volitelná). Výstup `data` = map `\"column value\"` → {qids[], labels[]}. Cache 1 h.","operationId":"items_lookup_v1_items_lookup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemsLookupRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Items Lookup V1 Items Lookup Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/images/by-part-id/{part_id}":{"get":{"tags":["images"],"summary":"Najít image entitu podle scan2structured partId","description":"Lookup image entity (P18 = partId) + navázaného recordu (P15). 404, když image s daným partId neexistuje. Cache 1 h.","operationId":"image_by_part_id_v1_images_by_part_id__part_id__get","parameters":[{"name":"part_id","in":"path","required":true,"schema":{"type":"string","title":"Part Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Image By Part Id V1 Images By Part Id  Part Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/images/{qid}":{"get":{"tags":["images"],"summary":"Metadata image entity pro načtení scanu","description":"Metadata image entity dle QID: partId (P18), localPage (P29), record (P15). 404, pokud image entita neexistuje nebo nemá partId. Cache 1 h.","operationId":"image_detail_v1_images__qid__get","parameters":[{"name":"qid","in":"path","required":true,"schema":{"type":"string","title":"Qid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Image Detail V1 Images  Qid  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/images/{qid}/raw":{"get":{"tags":["images"],"summary":"Raw wikitext lokální wiki stránky image entity","description":"Pro LLM scoring (train text). Z entity přečte P29 (local_page), pak stáhne raw wikitext hlavní slotu dané stránky z gotha.wikibase.cloud. 200 s content='' a missing=true, pokud entita nemá P29 nebo stránka neexistuje. Cache 1 h.","operationId":"image_raw_v1_images__qid__raw_get","parameters":[{"name":"qid","in":"path","required":true,"schema":{"type":"string","title":"Qid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Image Raw V1 Images  Qid  Raw Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/records/by-uuid/{uuid}":{"get":{"tags":["records"],"summary":"Stránkový záznam podle UUID","description":"Detail stránkového záznamu hledaného přes scan2structured UUID (property P18): cs label, pořadí stránky (P6 jako číslo) a QID dokumentu (P15). 404, pokud UUID neexistuje. Cache 1 h.","operationId":"record_by_uuid_v1_records_by_uuid__uuid__get","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","title":"Uuid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Record By Uuid V1 Records By Uuid  Uuid  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/records/{qid}/images":{"get":{"tags":["records"],"summary":"Image entity navázané na stránkový záznam","description":"Všechny Image entity (P15 = record QID) s partId (P18). Inverzní směr k /images/by-part-id. Cache 1 h.","operationId":"images_by_record_v1_records__qid__images_get","parameters":[{"name":"qid","in":"path","required":true,"schema":{"type":"string","title":"Qid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Images By Record V1 Records  Qid  Images Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/records":{"get":{"tags":["records"],"summary":"Stránkové záznamy dokumentu (seřazené)","description":"Všechny stránkové záznamy (P15 = document QID), seřazené podle pořadí stránky (P6).","operationId":"records_v1_records_get","parameters":[{"name":"document_qid","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Qid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Records V1 Records Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/documents":{"get":{"tags":["records"],"summary":"Seznam dokumentů (instance Q12)","description":"Dokumenty s cs label a pořadím v rodině (P6). Cache 24 h.","operationId":"documents_v1_documents_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Documents V1 Documents Get"}}}}}}},"/v1/properties":{"get":{"tags":["meta"],"summary":"Seznam property (P-čísel) s českým/německým/anglickým popisem a počty použití (nový)","description":"Agregace přes wikibase:directClaim: každá vlastnost s labely cs/de/en a počtem subjektů, kde je použita. Řazeno dle počtu použití sestupně. Drahý dotaz → cache 24 h.","operationId":"properties_v1_properties_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Properties V1 Properties Get"}}}}}}},"/v1/health/deep":{"get":{"tags":["meta"],"summary":"Hloubkový health check (SPARQL dostupnost)","description":"Lehký dotaz na WDQS; při nedostupnosti vrací 503 s error_code=unavailable.","operationId":"health_deep_v1_health_deep_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Health Deep V1 Health Deep Get"}}}}}}}},"components":{"schemas":{"EntityLookupRequest":{"properties":{"qids":{"items":{"type":"string"},"type":"array","maxItems":500,"minItems":1,"title":"Qids"}},"type":"object","required":["qids"],"title":"EntityLookupRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ItemLookupEntry":{"properties":{"column":{"type":"string","maxLength":200,"minLength":1,"title":"Column"},"value":{"type":"string","maxLength":500,"minLength":1,"title":"Value"},"class":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Class"}},"type":"object","required":["column","value"],"title":"ItemLookupEntry"},"ItemsLookupRequest":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ItemLookupEntry"},"type":"array","maxItems":500,"minItems":1,"title":"Items"}},"type":"object","required":["items"],"title":"ItemsLookupRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"viewer","description":"Endpointy pro gotha-viewer (rody, osoby, hledání)."},{"name":"persons","description":"Lookup osob pro scan2structured pipeline."},{"name":"entities","description":"Entity lookup (wbgetentities), backlinks, LLM modely."},{"name":"items","description":"Mapování CSV hodnot na QID položek."},{"name":"images","description":"Image entity a jejich partId/recorde vztahy."},{"name":"records","description":"Stránkové záznamy a dokumenty."},{"name":"meta","description":"Stav, health a agregace."}]}