{"components":{"responses":{"RateLimited":{"description":"Rate-Limit \u00fcberschritten (Retry-After-Header gesetzt)."},"Unauthorized":{"description":"API-Key fehlt oder ist ung\u00fcltig."}},"schemas":{"ArticleReference":{"properties":{"article_id":{"type":"integer"},"municipality":{"type":"string"},"municipality_id":{"type":"integer"},"municipality_name":{"type":"string"},"scout_url":{"description":"Direkter Scout-Artikellink; Browserlogin erforderlich.","type":"string"},"url":{"description":"Originalquelle, nicht der Scout-Link.","type":"string"}},"type":"object"}},"securitySchemes":{"bearerAuth":{"description":"API-Key als Bearer-Token.","scheme":"bearer","type":"http"}}},"info":{"description":"Volltextsuche und RAG (Vektor-Retrieval, Frage/Antwort) \u00fcber amtliche Gemeindemitteilungen. Synchrone JSON-Antworten.","title":"Scout Public API","version":"1.0.0"},"openapi":"3.0.3","paths":{"/v1/documents/read":{"post":{"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"article_id":{"minimum":1,"type":"integer"},"document_id":{"description":"Opaque selector from attachments/documents; omit for article.","pattern":"^[a-f0-9]{64}$","type":"string"},"documents_offset":{"default":0,"maximum":100000,"minimum":0,"type":"integer"},"max_chars":{"default":20000,"maximum":20000,"minimum":1,"type":"integer"},"municipality_id":{"minimum":1,"type":"integer"},"page":{"default":1,"maximum":100000,"minimum":1,"type":"integer"},"text_offset":{"default":0,"maximum":10000000,"minimum":0,"type":"integer"}},"required":["municipality_id","article_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"article_id":{"type":"integer"},"content_kind":{"enum":["article_original","pdf_extracted","legacy_extracted"],"type":"string"},"date":{"type":"string"},"document_id":{"type":"string"},"documents":{"items":{"additionalProperties":false,"properties":{"availability":{"enum":["stored_reference","text_reference","not_stored"],"type":"string"},"document_id":{"type":"string"},"filename":{"type":"string"},"page_count":{"type":"integer"},"title":{"type":"string"},"url":{"type":"string"}},"required":["document_id","url","title","filename","page_count","availability"],"type":"object"},"maxItems":100,"type":"array"},"municipality":{"type":"string"},"municipality_id":{"type":"integer"},"municipality_name":{"type":"string"},"next":{"additionalProperties":false,"nullable":true,"properties":{"page":{"type":"integer"},"text_offset":{"type":"integer"}},"required":["page","text_offset"],"type":"object"},"next_documents_offset":{"nullable":true,"type":"integer"},"page":{"nullable":true,"type":"integer"},"page_count":{"nullable":true,"type":"integer"},"scout_url":{"type":"string"},"source_url":{"type":"string"},"status":{"enum":["available","text_unavailable","not_stored","page_has_no_text","page_provenance_unavailable","unsafe_storage_path","file_too_large","pdf_unreadable_or_limit_exceeded","file_unreadable"],"type":"string"},"text":{"type":"string"},"title":{"type":"string"},"truncated":{"type":"boolean"},"url":{"type":"string"}},"required":["title","url","date","document_id","source_url","text","municipality","municipality_name","scout_url","municipality_id","article_id","documents","next_documents_offset","content_kind","status","page","page_count","truncated","next"],"type":"object"}}},"description":"Originalinhalt oder expliziter Verf\u00fcgbarkeitsstatus."},"400":{"description":"Ung\u00fcltige Parameter."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Schl\u00fcssel deaktiviert."},"404":{"description":"Nicht vorhanden oder nicht freigegeben."},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Dokumentabruf fehlgeschlagen."}},"summary":"Gespeicherten Originaltext und PDF-Seiten lesen (Suchlimit)"}},"/v1/municipalities":{"get":{"parameters":[{"description":"Filter: Namens-Teilstring (case-insensitive).","in":"query","name":"q","schema":{"type":"string"}},{"description":"Filter: Region/Bundesland, z. B. Brandenburg.","in":"query","name":"canton","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"count":{"type":"integer"},"municipalities":{"items":{"properties":{"canton":{"type":"string"},"district":{"nullable":true,"type":"string"},"municipality_id":{"description":"Amtlicher Gemeindeschl\u00fcssel \u2014 f\u00fcr municipality_ids-Filter verwenden.","type":"integer"},"name":{"type":"string"}},"type":"object"},"type":"array"}},"type":"object"}}},"description":"Liste der (im Key-Scope) verf\u00fcgbaren Gemeinden."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"bearerAuth":[]}],"summary":"Gemeinde-Lookup: IDs (Gemeindeschl\u00fcssel) zu Klarnamen und Region"}},"/v1/rag/ask":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"date_from":{"format":"date","type":"string"},"date_to":{"format":"date","type":"string"},"has_pdf":{"default":false,"type":"boolean"},"history":{"description":"Optionale Gespr\u00e4chshistorie [{role: user|assistant, content}].","items":{"properties":{"content":{"type":"string"},"role":{"enum":["user","assistant"],"type":"string"}},"type":"object"},"type":"array"},"municipality_ids":{"description":"Gemeindeschl\u00fcssel (siehe /v1/municipalities).","items":{"type":"integer"},"type":"array"},"query":{"type":"string"}},"required":["query"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"sources":{"items":{"$ref":"#/components/schemas/ArticleReference"},"type":"array"}},"type":"object"}}},"description":"answer (Markdown), sources[] mit Gemeindenamen/scout_url, usage (Token)."},"400":{"description":"query fehlt / history ung\u00fcltig."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"description":"LLM-Antwort fehlgeschlagen."}},"summary":"Synchrone RAG-Frage/Antwort mit Quellenangaben (stateless)"}},"/v1/rag/search":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"date_from":{"format":"date","type":"string"},"date_to":{"format":"date","type":"string"},"include_attachments":{"default":false,"description":"Normalisierte Dokumentreferenzen erg\u00e4nzen.","type":"boolean"},"include_media":{"default":false,"type":"boolean"},"municipality_ids":{"description":"Gemeindeschl\u00fcssel (siehe /v1/municipalities).","items":{"type":"integer"},"type":"array"},"query":{"type":"string"},"top_k":{"default":10,"maximum":50,"type":"integer"}},"required":["query"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"items":{"$ref":"#/components/schemas/ArticleReference"},"type":"array"}},"type":"object"}}},"description":"results[] mit Score (rank), Gemeindenamen und scout_url."},"400":{"description":"query fehlt."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Vektor-Retrieval (semantische Suche)"}},"/v1/search":{"get":{"parameters":[{"description":"Volltext-Suchbegriff (deutsch, FTS).","in":"query","name":"q","required":true,"schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"default":25,"maximum":100,"type":"integer"}},{"in":"query","name":"offset","schema":{"default":0,"type":"integer"}},{"description":"Normalisierte Dokumentreferenzen mit get_document-Selektoren erg\u00e4nzen.","in":"query","name":"include_attachments","schema":{"enum":["1"],"type":"string"}},{"description":"Kommagetrennte Gemeindeschl\u00fcssel (siehe /v1/municipalities).","in":"query","name":"municipality_ids","schema":{"type":"string"}},{"in":"query","name":"canton","schema":{"type":"string"}},{"in":"query","name":"district","schema":{"type":"string"}},{"description":"Intervall 'YYYY-MM-DD..YYYY-MM-DD' (offene Enden erlaubt), mehrfach = OR.","in":"query","name":"date_range","schema":{"type":"string"}},{"in":"query","name":"date_from","schema":{"format":"date","type":"string"}},{"in":"query","name":"date_to","schema":{"format":"date","type":"string"}},{"description":"Quelltyp (url_type der Gemeinde), mehrfach = OR.","in":"query","name":"source_type","schema":{"type":"string"}},{"in":"query","name":"author","schema":{"type":"string"}},{"description":"mehrfach = OR","in":"query","name":"ai_category","schema":{"type":"string"}},{"in":"query","name":"ai_relevance","schema":{"type":"string"}},{"in":"query","name":"ai_label","schema":{"type":"string"}},{"in":"query","name":"has_pdf","schema":{"enum":["1"],"type":"string"}},{"in":"query","name":"has_image","schema":{"enum":["1"],"type":"string"}},{"description":"Range-DSL: gt:N, lt:N, eq:N oder A-B.","in":"query","name":"image_count","schema":{"type":"string"}},{"in":"query","name":"document_count","schema":{"type":"string"}},{"in":"query","name":"word_count","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"results":{"items":{"$ref":"#/components/schemas/ArticleReference"},"type":"array"}},"type":"object"}}},"description":"Suchtreffer mit total/count/offset/limit und results[] (Artikel-Metadaten, AI-Felder, Snippets)."},"400":{"description":"q fehlt."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Volltextsuche mit Filtern, Pagination und Snippets"}}},"security":[{"bearerAuth":[]}],"servers":[{"url":"https://hugoscout.mad.stg.sternwald.cloud"}]}