{"openapi":"3.1.0","info":{"title":"huqsi API","description":"Azərbaycan qanunvericiliyi (e-qanun.az korpusu) üçün ictimai REST API. Auth: `X-API-Key` başlığı. Açar: https://api.huqsi.az kabinetindən. MCP (`/mcp`) həm də OAuth 2.1 ilə qoşulur.","version":"0.1.0"},"servers":[{"url":"https://api.huqsi.az"}],"paths":{"/v1/search":{"post":{"tags":["v1"],"summary":"Qanunvericilikdə mətn axtarışı","description":"Azərbaycan qanunvericiliyində (e-qanun.az korpusu) semantik maddə axtarışı. Qüvvədə olan əsas aktların cari redaksiyası üzrə. Hər nəticədə maddənin tam mətni yox, sorğuya uyğun qısa parça (`snippet`) qayıdır; tam mətn — GET /v1/articles/{id}.","operationId":"search_v1_search_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"401":{"description":"API açarı yoxdur / etibarsızdır / ləğv edilib / müddəti bitib","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Endpoint bu plan üçün bağlıdır","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Dəqiqəlik limit, IP tavanı və ya aylıq kvota aşılıb","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Qanun bazası əlçatmazdır","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/articles/{article_id}":{"get":{"tags":["v1"],"summary":"Maddənin qüvvədə olan mətni","description":"Maddənin cari mətni, metadata və son dəyişiklik aktları. id formatı: «{qanun_id}:p{hissə}:{maddə}», məs. «46947:p1:177». Çox uzun mətn (tək-mətnli akt) həddə qədər kəsilir: `truncated: true`, `text_length`.","operationId":"article_v1_articles__article_id__get","parameters":[{"name":"article_id","in":"path","required":true,"schema":{"type":"string","description":"Maddə id-si, məs. 46947:p1:177","title":"Article Id"},"description":"Maddə id-si, məs. 46947:p1:177"},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Article"}}}},"401":{"description":"API açarı yoxdur / etibarsızdır / ləğv edilib / müddəti bitib","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Endpoint bu plan üçün bağlıdır","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Dəqiqəlik limit, IP tavanı və ya aylıq kvota aşılıb","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Qanun bazası əlçatmazdır","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/articles/{article_id}/history":{"get":{"tags":["v1"],"summary":"Maddənin dəyişiklik tarixçəsi","description":"Bu maddəni dəyişdirən aktlar (ən yenisi əvvəl) və saxlanan versiya sayı.","operationId":"history_v1_articles__article_id__history_get","parameters":[{"name":"article_id","in":"path","required":true,"schema":{"type":"string","description":"Maddə id-si, məs. 46947:p1:177","title":"Article Id"},"description":"Maddə id-si, məs. 46947:p1:177"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleHistory"}}}},"401":{"description":"API açarı yoxdur / etibarsızdır / ləğv edilib / müddəti bitib","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Endpoint bu plan üçün bağlıdır","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Dəqiqəlik limit, IP tavanı və ya aylıq kvota aşılıb","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Qanun bazası əlçatmazdır","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Amendment":{"properties":{"act_id":{"type":"integer","title":"Act Id","description":"Dəyişiklik aktının e-qanun framework id-si."},"act_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Act Title"},"act_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Act Date","description":"Aktın qəbul tarixi (YYYY-MM-DD)."},"act_no":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Act No"},"act_status":{"type":"string","title":"Act Status","description":"Aktın statusu: «Qüvvədədir» və s."},"kinds":{"items":{"type":"string"},"type":"array","title":"Kinds","description":"dəyişdirilib | əlavə edilib | çıxarılıb | ləğv edilib | yeni redaksiya"},"source_url":{"type":"string","title":"Source Url"}},"type":"object","required":["act_id","act_status","source_url"],"title":"Amendment"},"AmendmentRef":{"properties":{"act_id":{"type":"integer","title":"Act Id","description":"Dəyişiklik aktının e-qanun framework id-si."},"act_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Act Title"},"act_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Act Date","description":"Aktın qəbul tarixi (YYYY-MM-DD)."},"act_no":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Act No"},"source_url":{"type":"string","title":"Source Url"}},"type":"object","required":["act_id","source_url"],"title":"AmendmentRef"},"Article":{"properties":{"article_id":{"type":"string","title":"Article Id"},"law":{"$ref":"#/components/schemas/LawInfo"},"article_no":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Article No"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"part_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Part Title","description":"Sənədin hissə başlığı (çoxhissəli sənədlərdə; yoxdursa null)."},"section_path":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Section Path","description":"Bölmə/fəsil yolu. Hazırda null: mənbədə iyerarxiya yoxlanılır, düzələnə qədər verilmir."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text","description":"Qüvvədə olan mətn. Ləğv edilmiş maddədə null ola bilər. Həddən uzundursa cümlə sərhədində kəsilir (`truncated`)."},"truncated":{"type":"boolean","title":"Truncated","description":"true — `text` hədd səbəbindən kəsilib; tam uzunluq `text_length`-dədir, tam mətn `law.source_url`-da.","default":false},"text_length":{"type":"integer","title":"Text Length","description":"Tam mətnin uzunluğu (simvol), kəsilməmişdən əvvəl.","default":0},"status":{"type":"string","title":"Status","description":"Maddənin statusu: aktiv | ləğv_edilib | yox_olub."},"in_force":{"type":"boolean","title":"In Force","description":"Həm qanun qüvvədədir, həm maddə aktivdir."},"stored_versions":{"type":"integer","title":"Stored Versions","description":"Bazada saxlanan mətn versiyalarının sayı (müşahidə etdiyimiz mətn dəyişiklikləri). Hüquqi dəyişikliklərin sayı deyil — o, `amendments_total`-dadır."},"first_seen_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Seen At","description":"Cari mətnin bazada İLK göründüyü vaxt (dəyişiklik aktının tarixi deyil; bax /docs/tezelik)."},"amendments_total":{"type":"integer","title":"Amendments Total","description":"Bu maddəni dəyişdirən aktların sayı (e-qanun dəyişiklik qeydlərinə görə).","default":0},"last_amendment":{"anyOf":[{"$ref":"#/components/schemas/AmendmentRef"},{"type":"null"}],"description":"Ən son dəyişiklik aktı (varsa)."},"recent_amendments":{"items":{"$ref":"#/components/schemas/AmendmentRef"},"type":"array","title":"Recent Amendments","description":"Son ən çox 3 dəyişiklik aktı, ən yenisi əvvəl."},"data_updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Updated At","description":"Bazaya son məlumat paketinin (e-qanun.az-dan gündəlik yeniləmə) tətbiq olunduğu vaxt. Bilinmirsə null. Bax /docs/tezelik."},"notice":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notice","description":"Müvəqqəti xəbərdarlıq (varsa)."}},"type":"object","required":["article_id","law","text","status","in_force","stored_versions"],"title":"Article"},"ArticleHistory":{"properties":{"article_id":{"type":"string","title":"Article Id"},"law_id":{"type":"integer","title":"Law Id"},"law_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Law Title"},"article_no":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Article No"},"stored_versions":{"type":"integer","title":"Stored Versions","description":"Bax Article.stored_versions (hüquqi dəyişiklik sayı `total`-dadır)."},"total":{"type":"integer","title":"Total","description":"Bu maddəni dəyişdirən aktların ümumi sayı."},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"amendments":{"items":{"$ref":"#/components/schemas/Amendment"},"type":"array","title":"Amendments","description":"Ən yenisi əvvəl."},"note":{"type":"string","title":"Note","default":"Tarixçə e-qanun-dakı dəyişiklik qeydlərindən (DEY) qurulub; köhnə redaksiya mətnləri verilmir."},"data_updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Updated At","description":"Bax Article.data_updated_at."}},"type":"object","required":["article_id","law_id","stored_versions","total","limit","offset","amendments"],"title":"ArticleHistory"},"ErrorResponse":{"properties":{"error":{"type":"string","title":"Error"},"message":{"type":"string","title":"Message"}},"type":"object","required":["error","message"],"title":"ErrorResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LawInfo":{"properties":{"id":{"type":"integer","title":"Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"status":{"type":"string","title":"Status","description":"Qanunun statusu: «Qüvvədədir» / «Ləğv olunmuşdur» / naməlum."},"in_force":{"type":"boolean","title":"In Force"},"accept_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accept Date","description":"Qəbul tarixi (YYYY-MM-DD)."},"number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Number","description":"Qəbul nömrəsi (məs. «787-IQ»); bilinmirsə null."},"citation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Citation","description":"İnsan üçün istinad (qanunun adı); maddə üçün «<citation>, maddə <article_no>» yazın."},"source_url":{"type":"string","title":"Source Url"}},"type":"object","required":["id","status","in_force","source_url"],"title":"LawInfo"},"SearchHit":{"properties":{"article_id":{"type":"string","title":"Article Id","description":"Maddənin sabit id-si (GET /v1/articles/{id} üçün)."},"law_id":{"type":"integer","title":"Law Id","description":"Qanunun e-qanun framework id-si."},"law_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Law Title"},"article_no":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Article No","description":"Maddə nömrəsi (məs. «177»); maddəsiz sənəddə null."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Maddənin başlığı (yoxdursa null)."},"citation":{"type":"string","title":"Citation","description":"İnsan üçün istinad: «Cinayət Məcəlləsi, maddə 177»."},"snippet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Snippet","description":"Maddədən sorğuya ən uyğun qısa parça (cümlə sərhədində kəsilir, «…» ilə). Tam mətn: GET /v1/articles/{article_id}."},"snippet_truncated":{"type":"boolean","title":"Snippet Truncated","description":"true — parça maddənin tam mətni deyil."},"text_length":{"type":"integer","title":"Text Length","description":"Maddənin tam mətninin uzunluğu (simvol)."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text","description":"Köhnəlmiş ad: `snippet` ilə eyni qısa parça. 2026-10-30-dan tam mətn DEYİL (tam mətn GET /v1/articles/{id}-dədir).","deprecated":true},"score":{"type":"number","title":"Score","description":"Oxşarlıq balı (1+cos)/2 şkalasında, ~0.80–0.90 tipik."},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url","description":"e-qanun.az-da mənbə."}},"type":"object","required":["article_id","law_id","citation","snippet","snippet_truncated","text_length","score"],"title":"SearchHit"},"SearchRequest":{"properties":{"query":{"type":"string","maxLength":500,"minLength":2,"title":"Query","description":"Sərbəst mətn (Azərbaycan dilində). Semantik axtarışdır — dəqiq maddə üçün GET /v1/articles/{id} işlədin."},"limit":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Limit","description":"Qaytarılacaq maksimum maddə sayı.","default":5},"law_ids":{"anyOf":[{"items":{"type":"integer"},"type":"array","maxItems":20},{"type":"null"}],"title":"Law Ids","description":"İstəyə görə: yalnız bu qanunlar (e-qanun framework id-ləri, məs. 46947 = Cinayət Məcəlləsi)."},"include_repealed":{"type":"boolean","title":"Include Repealed","description":"Qüvvədən düşmüş aktların maddələri də daxil olsun.","default":false}},"additionalProperties":false,"type":"object","required":["query"],"title":"SearchRequest"},"SearchResponse":{"properties":{"query":{"type":"string","title":"Query"},"results":{"items":{"$ref":"#/components/schemas/SearchHit"},"type":"array","title":"Results"},"count":{"type":"integer","title":"Count"},"note":{"type":"string","title":"Note","default":"Semantik axtarış: nəticələr oxşarlığa görə sıralanıb, dəqiq uyğunluq zəmanəti yoxdur."},"data_updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Updated At","description":"Bazaya son məlumat paketinin (e-qanun.az-dan gündəlik yeniləmə) tətbiq olunduğu vaxt. Bilinmirsə null. Bax /docs/tezelik."},"notice":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notice","description":"Müvəqqəti xəbərdarlıq (varsa)."}},"type":"object","required":["query","results","count"],"title":"SearchResponse"},"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"}}}}