{"openapi":"3.1.0","info":{"title":"Finans Haber | DETAI — Public API","version":"1.0.0","summary":"finanshaber.detai.ai portalının salt okunur, kimliksiz JSON API’si.","description":"finanshaber.detai.ai, DETAI’nin editör onaylı ekonomi haber portalıdır. Bu API yalnız portalın zaten yayımladığı makaleleri (iki insan onayından geçmiş) ve resmî ekonomik takvimi sunar; taslak, editör notu ya da kaynak gövdesi hiçbir uçta yer almaz.\n\nKimlik doğrulama yoktur (public, salt okunur). Oran sınırı: IP başına dakikada 120 istek. Aşımda HTTP 429 ve `Retry-After` (saniye) başlığı döner; her yanıtta `X-RateLimit-Limit` ve `X-RateLimit-Remaining` başlıkları bulunur. Gövde sınırı 1024 bayt (GET uçları gövde beklemez).\n\nAynı veri MCP üzerinden de sunulur: POST https://finanshaber.detai.ai/mcp (Streamable HTTP, yalnız JSON-RPC 2.0 POST; SSE yok). Her REST ucunun MCP karşılığı `x-mcp-tool` alanında yazılıdır.\n\nHer yanıt bir `disclaimer` alanı taşır. Yatırım tavsiyesi değildir. İçerik haber ve takvim bilgisidir; alım-satım önerisi içermez.\n\nTarih/saat alanları ISO 8601 UTC’dir (takvim günleri Türkiye takvimine göre). Makale listesi sunucu tarafında en çok 15 sn önbelleklenir; JSON yanıtları `Cache-Control: public, max-age=60` taşır.","x-disclaimer":"Yatırım tavsiyesi değildir."},"servers":[{"url":"https://finanshaber.detai.ai","description":"Üretim"}],"security":[],"tags":[{"name":"Bölümler"},{"name":"Makaleler"},{"name":"Takvim"}],"x-rate-limit":{"scope":"ip","requestsPerMinute":120,"windowSeconds":60,"maxBodyBytes":1024,"headers":["X-RateLimit-Limit","X-RateLimit-Remaining","Retry-After"]},"x-mcp":{"url":"https://finanshaber.detai.ai/mcp","transport":"streamable-http","methods":["POST"],"authentication":"none","tools":["list_sections","list_articles","get_article","search_articles","upcoming_events"]},"paths":{"/api/public/sections":{"get":{"operationId":"listSections","summary":"Bölümleri listele","description":"Portalın sekiz bölümünü (id, Türkçe etiket, URL, yayımlanmış makale sayısı) döndürür. Yatırım tavsiyesi değildir.","tags":["Bölümler"],"x-openai-isConsequential":false,"x-mcp-tool":"list_sections","parameters":[],"responses":{"200":{"description":"Başarılı.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SectionsResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"Haber kaynağı (VDS) geçici olarak erişilemez; gövde HTML olabilir."}}}},"/api/public/articles":{"get":{"operationId":"listArticles","summary":"Yayımlanmış makaleleri listele","description":"Editör onaylı, yayımlanmış makalelerin özetlerini yeniden eskiye listeler. `section` ile bölüme daraltılır; sayfalama `nextCursor` → `cursor` ile. Gövde metni bu uçta yoktur; tam metin için /api/public/articles/{slug}. Yatırım tavsiyesi değildir.","tags":["Makaleler"],"x-openai-isConsequential":false,"x-mcp-tool":"list_articles","parameters":[{"$ref":"#/components/parameters/section"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}],"responses":{"200":{"description":"Başarılı.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleListResponse"}}}},"400":{"description":"Geçersiz parametre.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"Haber kaynağı (VDS) geçici olarak erişilemez; gövde HTML olabilir."}}}},"/api/public/articles/{slug}":{"get":{"operationId":"getArticle","summary":"Makaleyi getir","description":"Slug ile tek bir yayımlanmış makalenin tam metnini, kaynaklarını (yayıncı, URL, tarih), yayın zamanını, portal URL’sini ve uyarı metnini döndürür. Yayımlanmamış ya da bilinmeyen slug → 404. Yatırım tavsiyesi değildir.","tags":["Makaleler"],"x-openai-isConsequential":false,"x-mcp-tool":"get_article","parameters":[{"$ref":"#/components/parameters/slug"}],"responses":{"200":{"description":"Başarılı.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Article"}}}},"400":{"description":"Geçersiz parametre.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Makale bulunamadı ya da yayımlanmamış.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"Haber kaynağı (VDS) geçici olarak erişilemez; gövde HTML olabilir."}}}},"/api/public/search":{"get":{"operationId":"searchArticles","summary":"Makalelerde ara","description":"Yayımlanmış makalelerde Türkçe duyarlı tam metin arama (başlık, konu, gövde). Sorgu sunucuda kaydedilmez. Yatırım tavsiyesi değildir.","tags":["Makaleler"],"x-openai-isConsequential":false,"x-mcp-tool":"search_articles","parameters":[{"$ref":"#/components/parameters/q"},{"$ref":"#/components/parameters/searchLimit"}],"responses":{"200":{"description":"Başarılı.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Geçersiz parametre.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"Haber kaynağı (VDS) geçici olarak erişilemez; gövde HTML olabilir."}}}},"/api/public/events":{"get":{"operationId":"upcomingEvents","summary":"Yaklaşan ekonomik takvim","description":"Bugünden itibaren verilen gün sayısı içindeki resmî takvim olayları (TCMB, Fed, ECB, TÜİK vb.); her olayda kurumun kaynak URL’si vardır. Bu bir takvimdir, veri açıklaması değildir. Yatırım tavsiyesi değildir.","tags":["Takvim"],"x-openai-isConsequential":false,"x-mcp-tool":"upcoming_events","parameters":[{"$ref":"#/components/parameters/days"}],"responses":{"200":{"description":"Başarılı.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsResponse"}}}},"400":{"description":"Geçersiz parametre.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"Haber kaynağı (VDS) geçici olarak erişilemez; gövde HTML olabilir."}}}}},"components":{"securitySchemes":{},"parameters":{"section":{"name":"section","in":"query","required":false,"description":"Bölüm id’si. Varsayılan gundem (tümü). Bilinmeyen id → 400.","schema":{"type":"string","enum":["gundem","ekonomi","kuresel","borsa","doviz-altin","sirketler","finans","analiz"]}},"limit":{"name":"limit","in":"query","required":false,"description":"Sayfa başına kayıt. Aralık dışı değerler sınıra çekilir; sayı olmayan değer 400 döndürür.","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},"cursor":{"name":"cursor","in":"query","required":false,"description":"Önceki yanıttaki nextCursor değeri (opak). Geçersiz → 400.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,16}$"}},"slug":{"name":"slug","in":"path","required":true,"description":"Makale slug’ı (portal URL’sindeki /haber/{slug} kısmı).","schema":{"type":"string","pattern":"^[a-z0-9-]{1,120}$"}},"q":{"name":"q","in":"query","required":true,"description":"Arama sorgusu (2–100 karakter).","schema":{"type":"string","minLength":2,"maxLength":100}},"searchLimit":{"name":"limit","in":"query","required":false,"description":"En çok sonuç. Aralık dışı değerler sınıra çekilir; sayı olmayan değer 400 döndürür.","schema":{"type":"integer","minimum":1,"maximum":20,"default":10}},"days":{"name":"days","in":"query","required":false,"description":"Kaç gün ileriye bakılacak (bugün dâhil). Aralık dışı değerler sınıra çekilir; sayı olmayan değer 400 döndürür.","schema":{"type":"integer","minimum":1,"maximum":60,"default":14}}},"headers":{"X-RateLimit-Limit":{"description":"Dakikalık istek bütçesi (IP başına).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Bu pencerede kalan istek.","schema":{"type":"integer"}},"Retry-After":{"description":"Kaç saniye sonra yeniden denenebilir.","schema":{"type":"integer"}}},"responses":{"RateLimited":{"description":"Oran sınırı aşıldı (IP başına 120/dk).","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error","disclaimer"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_parameter","not_found","method_not_allowed","payload_too_large","rate_limited","internal_error"]},"message":{"type":"string"}}},"disclaimer":{"type":"string","const":"Yatırım tavsiyesi değildir."}}},"Section":{"type":"object","required":["id","label","url","articleCount"],"properties":{"id":{"type":"string","enum":["gundem","ekonomi","kuresel","borsa","doviz-altin","sirketler","finans","analiz"]},"label":{"type":"string","description":"Türkçe bölüm etiketi."},"url":{"type":"string","format":"uri","description":"Bölümün portal sayfası."},"articleCount":{"type":"integer","minimum":0,"description":"Bölümdeki yayımlanmış makale sayısı."}}},"SectionsResponse":{"type":"object","required":["sections","disclaimer"],"properties":{"sections":{"type":"array","items":{"$ref":"#/components/schemas/Section"}},"disclaimer":{"type":"string"}}},"ArticleSummary":{"type":"object","required":["slug","headline","url","publishedAt","topics","sections","sourceCount"],"properties":{"slug":{"type":"string","pattern":"^[a-z0-9-]{1,120}$"},"headline":{"type":"string"},"url":{"type":"string","format":"uri","description":"Makalenin portal URL’si (https://finanshaber.detai.ai/haber/{slug}). Kullanıcıya aktarırken bağlayın."},"publishedAt":{"type":"string","format":"date-time","description":"Editör onay zamanı (UTC, ISO 8601)."},"topics":{"type":"array","items":{"type":"string"},"description":"Türkçe konu etiketleri."},"sections":{"type":"array","items":{"type":"string","enum":["ekonomi","kuresel","borsa","doviz-altin","sirketler","finans","analiz"]},"description":"Makalenin göründüğü bölüm id’leri (gundem hariç; gundem tümünü kapsar)."},"sourceCount":{"type":"integer","minimum":0}}},"Source":{"type":"object","required":["publisher"],"properties":{"publisher":{"type":"string"},"url":{"type":"string","format":"uri"},"publishedAt":{"type":"string","format":"date-time"}},"description":"Kaynak künyesi. Kaynak gövdesi (ham metin) hiçbir uçta verilmez."},"Article":{"allOf":[{"$ref":"#/components/schemas/ArticleSummary"},{"type":"object","required":["topicIds","body","sources","disclaimer"],"properties":{"topicIds":{"type":"array","items":{"type":"string"},"description":"Taksonomi id’leri (piyasalar, para_politikasi, enflasyon, doviz, emtia, bankacilik, sirketler, kamu_maliyesi, kuresel)."},"body":{"type":"string","description":"Makale gövdesi (düz metin, paragraflar boş satırla ayrılır). \"Kaynaklar:\" paragrafı portaldaki gibi çıkarılmıştır."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"disclaimer":{"type":"string","description":"Uyarı metni; her zaman \"Yatırım tavsiyesi değildir.\" içerir."}}}]},"ArticleListResponse":{"type":"object","required":["section","total","items","disclaimer"],"properties":{"section":{"type":"string","enum":["gundem","ekonomi","kuresel","borsa","doviz-altin","sirketler","finans","analiz"]},"total":{"type":"integer","minimum":0,"description":"Bölümdeki toplam yayımlanmış makale."},"items":{"type":"array","items":{"$ref":"#/components/schemas/ArticleSummary"}},"nextCursor":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,16}$","description":"Sonraki sayfa için `cursor` değeri; son sayfada yoktur."},"disclaimer":{"type":"string"}}},"SearchResponse":{"type":"object","required":["query","total","items","disclaimer"],"properties":{"query":{"type":"string","description":"Temizlenmiş sorgu."},"total":{"type":"integer","minimum":0,"description":"Eşleşen toplam makale."},"items":{"type":"array","items":{"$ref":"#/components/schemas/ArticleSummary"}},"disclaimer":{"type":"string"}}},"Event":{"type":"object","required":["date","country","countryLabel","title","category","categoryLabel","importance","importanceLabel","sourceUrl","sourceName","verifiedAt"],"properties":{"date":{"type":"string","format":"date","description":"Türkiye takvim günü (YYYY-MM-DD)."},"time":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Yalnız kaynakta belirtildiğinde; Türkiye saati."},"timeZone":{"type":"string","const":"Europe/Istanbul"},"country":{"type":"string","enum":["TR","US","EU"]},"countryLabel":{"type":"string"},"title":{"type":"string"},"category":{"type":"string","enum":["para_politikasi","enflasyon","buyume","istihdam","dis_ticaret","kamu_maliyesi","diger"]},"categoryLabel":{"type":"string"},"importance":{"type":"string","enum":["yuksek","orta","dusuk"]},"importanceLabel":{"type":"string"},"sourceUrl":{"type":"string","format":"uri","description":"Kurumun resmî takvim sayfası."},"sourceName":{"type":"string"},"verifiedAt":{"type":"string","format":"date","description":"Kaydın kaynaktan son doğrulandığı gün."}}},"EventsResponse":{"type":"object","required":["days","calendarUrl","events","disclaimer"],"properties":{"days":{"type":"integer","minimum":1,"maximum":60},"calendarUrl":{"type":"string","format":"uri"},"events":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"disclaimer":{"type":"string"}}}}}}