{"openapi":"3.1.0","info":{"title":"Miloslav Hub Agent — veřejné API","version":"1.0.0","description":"Verzované read-only znalostní API pro uživatele, služby a AI klienty. Každý datový požadavek používá odvolatelný klientský klíč; obsah dotazů a odpovědí se do integračního auditního logu neukládá.","contact":{"name":"Miloslav Hub","email":"miloslav@miloslavhub.cz","url":"https://miloslavhub.cz"}},"servers":[{"url":"https://miloslavhub-agent.miloslav-hub.workers.dev"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/public/chat":{"post":{"operationId":"askMiloslavHubPublicKnowledge","summary":"Odpoví z veřejné znalostní báze","description":"Vrací vytvořenou odpověď, ne raw text dokumentů.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}}},"responses":{"200":{"description":"Odpověď a povolené citace."},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"429":{"$ref":"#/components/responses/ApiError"}}}},"/api/v1/public/feedback":{"post":{"operationId":"rateMiloslavHubPublicAnswer","summary":"Ohodnotí dřívější odpověď","description":"Ukládá jen strukturované hodnocení a důvod, nikoli volný komentář.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackRequest"}}}},"responses":{"200":{"description":"Hodnocení bylo přijato."},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"429":{"$ref":"#/components/responses/ApiError"}}}},"/api/v1/public/search":{"post":{"operationId":"searchMiloslavHubPublicKnowledge","summary":"Vyhledá povolené veřejné úryvky","description":"Prohledává jen dokumenty s allow_raw_api a raw_allowed.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"Nejvýše osm omezených úryvků."},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"429":{"$ref":"#/components/responses/ApiError"}}}},"/api/v1/public/documents":{"get":{"operationId":"listMiloslavHubPublicDocuments","summary":"Vypíše dokumenty povolené k veřejnému exportu","x-openai-isConsequential":false,"parameters":[{"name":"cursor","in":"query","schema":{"type":"integer","minimum":0}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Stránka metadat dokumentů."},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"429":{"$ref":"#/components/responses/ApiError"}}}},"/api/v1/public/documents/{id}":{"get":{"operationId":"getMiloslavHubPublicDocument","summary":"Vrátí stránku chunků jednoho exportovatelného dokumentu","x-openai-isConsequential":false,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"cursor","in":"query","schema":{"type":"integer","minimum":-1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Metadata a omezená stránka textových chunků."},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"429":{"$ref":"#/components/responses/ApiError"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Klientský klíč mh_live_… vydaný správcem. Klíč se zobrazí jen při vytvoření."}},"schemas":{"ChatRequest":{"type":"object","additionalProperties":false,"required":["query"],"properties":{"query":{"type":"string","minLength":1,"maxLength":2000},"history":{"type":"array","maxItems":8,"items":{"type":"object","additionalProperties":false,"required":["role","content"],"properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string","maxLength":4000}}}}}},"SearchRequest":{"type":"object","additionalProperties":false,"required":["query"],"properties":{"query":{"type":"string","minLength":1,"maxLength":1200},"limit":{"type":"integer","minimum":1,"maximum":8,"default":5}}},"FeedbackRequest":{"type":"object","additionalProperties":false,"required":["requestId","rating"],"properties":{"requestId":{"type":"string","format":"uuid"},"rating":{"type":"integer","enum":[-1,1]},"reason":{"type":"string","enum":["helpful","incorrect","incomplete","outdated","citation_issue","unsafe","other"]}}},"Error":{"type":"object","required":["status","error","requestId"],"properties":{"status":{"type":"string","const":"error"},"error":{"type":"string"},"requestId":{"type":"string","format":"uuid"}}}},"responses":{"ApiError":{"description":"Stabilní kód chyby bez interních detailů.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}