{"openapi":"3.1.0","info":{"title":"Korpus API","version":"1.0.0","summary":"API publique de la plateforme juridique Korpus.","description":"Korpus est une plateforme de doctrine juridique et de jurisprudence\ncommentée structurée pour la consommation par les LLM et les agents\nIA. Cette API expose la recherche unifiée, les articles complets,\net le serveur MCP (Model Context Protocol).\n\n**Tarification** (USD par appel, dégrésive selon volume mensuel) :\n- `search` : $0.015\n- `articles` : $0.06\n- `mcp` : $0.05\n\nRéductions automatiques : -10% au-delà de $500/mois cumulés, -20%\nau-delà de $2000/mois.\n\n**Authentification** : Bearer token via header `Authorization`.\nCréer une clé : compte Praticien (29€ HT/mois) ou Cabinet.\n\n**LLM-readiness** : toutes les réponses incluent le hash SHA-256\net la version semver de chaque publication (composants L1+L2 de la\nspec template publication v2).","termsOfService":"https://www.korpus.lu/cgu","contact":{"name":"Korpus API Support","url":"https://www.korpus.lu/api/docs","email":"api@korpus.lu"},"license":{"name":"CC BY 4.0 (contenu) — API tarifée à l'usage","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://www.korpus.lu/api/v1","description":"Production"}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key (kpus_live_...)","description":"Token Bearer Korpus, prefixé `kpus_live_`. Créer une clé via l'espace Compte > API. Format : `Authorization: Bearer kpus_live_...`."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Code d'erreur machine-readable."},"message":{"type":"string","description":"Message humain."},"detail":{"type":"string","description":"Détails supplémentaires si disponibles."}}},"SearchHit":{"type":"object","required":["type","score"],"properties":{"type":{"type":"string","enum":["article","headnote"]},"score":{"type":"number","description":"Score RRF fusion lexicale+sémantique."},"slug":{"type":"string"},"title":{"type":"string"},"abstract":{"type":"string","nullable":true},"jurisdiction":{"type":"array","items":{"type":"string"}},"contentType":{"type":"string"},"publishedAt":{"type":"string","format":"date-time","nullable":true}}},"Article":{"type":"object","required":["slug","title","contentType","sha256Hash","version"],"properties":{"slug":{"type":"string"},"title":{"type":"string"},"abstract":{"type":"string","nullable":true},"contentClean":{"type":"string"},"language":{"type":"string"},"jurisdiction":{"type":"array","items":{"type":"string"}},"legalDomain":{"type":"array","items":{"type":"string"}},"contentType":{"type":"string","enum":["jurisprudence","legislation","doctrine","regulation","convention_collective","soft_law","custom"]},"doctrineSubtype":{"type":"string","nullable":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time"},"sha256Hash":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Hash SHA-256 deterministe RFC 8785 (P5/L1)."},"version":{"type":"string","pattern":"^\\d+\\.\\d+\\.\\d+$","description":"Version semver MAJOR.MINOR.PATCH (P6/L2)."},"groundednessScore":{"type":"integer","minimum":0,"maximum":100,"nullable":true,"description":"Score groundedness 0-100 (% claims vérifiées)."},"hasIntegrityWarning":{"type":"boolean"},"headnotes":{"type":"array","items":{"$ref":"#/components/schemas/Headnote"}}}},"Headnote":{"type":"object","required":["sequence","summary"],"properties":{"sequence":{"type":"integer","minimum":1},"summary":{"type":"string"},"sourceText":{"type":"string","nullable":true},"legalRuleType":{"type":"string","enum":["ratio","obiter","distinction"],"nullable":true}}},"SearchFilters":{"type":"object","properties":{"jurisdictions":{"type":"array","items":{"type":"string","enum":["FR","EU","LU","MC","AD"]},"maxItems":10},"conceptIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":20},"courtLevels":{"type":"array","items":{"type":"string"},"maxItems":10},"statusFlags":{"type":"array","items":{"type":"string","enum":["red","orange","yellow","green","gray"]},"maxItems":5},"legalRuleTypes":{"type":"array","items":{"type":"string"},"maxItems":20},"doctrineSubtypes":{"type":"array","items":{"type":"string"},"maxItems":10},"legalDomains":{"type":"array","items":{"type":"string"},"maxItems":20},"treatmentTypes":{"type":"array","items":{"type":"string"},"maxItems":20},"dateFrom":{"type":"string","format":"date"},"dateTo":{"type":"string","format":"date"}}}}},"security":[{"bearerApiKey":[]}],"paths":{"/search":{"post":{"operationId":"searchUnified","summary":"Recherche unifiée (lexicale + sémantique)","description":"Recherche RRF (Reciprocal Rank Fusion) combinant tsvector (BM25) et embeddings vectoriels (Voyage law-2 1024d). Renvoie articles ET headnotes classés par score.","tags":["search"],"security":[{"bearerApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","maxLength":500,"default":"","description":"Requête plein texte. Optionnel : vide = parcours filtré (filters seuls)."},"filters":{"$ref":"#/components/schemas/SearchFilters"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20},"offset":{"type":"integer","minimum":0,"maximum":1000,"default":0},"includeHeadnotes":{"type":"boolean","default":true,"description":"Inclure les headnotes dans les hits."},"enableVector":{"type":"boolean","default":true,"description":"Activer la branche sémantique (embeddings) en plus du lexical."}}},"example":{"text":"rupture brutale relation commerciale","filters":{"jurisdictions":["FR"]},"limit":10}}}},"responses":{"200":{"description":"Résultats de recherche classés RRF.","content":{"application/json":{"schema":{"type":"object","properties":{"hits":{"type":"array","items":{"$ref":"#/components/schemas/SearchHit"}},"total":{"type":"integer"}}}}}},"401":{"description":"API key invalide ou manquante.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit atteint OU spending cap depassée."}}}},"/articles/{slug}":{"get":{"operationId":"getArticle","summary":"Article complet par slug","description":"Renvoie un article publié avec metadata + contenu nettoyé + headnotes + concepts + integrity flags + groundedness + hash SHA-256 + version semver.","tags":["articles"],"security":[{"bearerApiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","maxLength":600},"description":"Slug unique de l'article."}],"responses":{"200":{"description":"Article complet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Article"}}}},"404":{"description":"Article introuvable, dépublié ou supprimé.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mcp":{"post":{"operationId":"mcpServer","summary":"Model Context Protocol — JSON-RPC 2.0","description":"Endpoint MCP exposant 10 outils Korpus aux clients compatibles (Claude Desktop, Cursor, agents IA). Conforme spec MCP. Liste des outils : korpus_search, korpus_get_article, korpus_rag_query, korpus_verify_claim, korpus_get_decision, korpus_get_concept, korpus_get_relations, korpus_explain_legal_term, korpus_list_authorities, korpus_get_chronology.","tags":["mcp"],"security":[{"bearerApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"method":{"type":"string","enum":["tools/list","tools/call","initialize","ping"]},"params":{"type":"object"},"id":{"oneOf":[{"type":"string"},{"type":"integer"}]}}}}}},"responses":{"200":{"description":"Réponse JSON-RPC 2.0."}}}}},"tags":[{"name":"search","description":"Recherche unifiée RRF."},{"name":"articles","description":"Lecture détaillée d'articles."},{"name":"mcp","description":"Model Context Protocol (agents LLM)."}],"externalDocs":{"description":"Documentation Korpus complète","url":"https://www.korpus.lu/api/docs"},"x-korpus-version":"1.0.0","x-korpus-llms-txt":"https://www.korpus.lu/llms.txt","x-korpus-dataset":"https://www.korpus.lu/api/v1/dataset.json","x-korpus-spec-template":"https://www.korpus.lu/docs/template-publication-spec-v2"}