API Korpus v1

Tarifs

Facturation à l'appel via Stripe metered. Pas de free tier — facturé dès le premier appel. Plafond mensuel configurable par clé.

Authentification

Toutes les requêtes nécessitent un header Authorization: Bearer kpus_live_…. Générez vos clés depuis votre dashboard /app/api-keys.

# Variable d'environnement recommandee
export KORPUS_API_KEY="kpus_live_a3f9b2c8..."

# Test de connexion
curl https://www.korpus.lu/api/v1/search \
  -H "Authorization: Bearer $KORPUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"force majeure","limit":5}'

POST /api/v1/search

Recherche hybride dans le corpus (full-text BM25 + vectorielle voyage-law-2 + RRF). Filtres par juridiction, concepts EuroVoc/LKIF, statut KeyCite, dates.

cURL

curl https://www.korpus.lu/api/v1/search \
  -H "Authorization: Bearer $KORPUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "RGPD biometrie consentement",
    "filters": {
      "jurisdictions": ["FR", "EU"],
      "statusFlags": ["green", "yellow"]
    },
    "limit": 20
  }'

JavaScript

const response = await fetch('https://www.korpus.lu/api/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.KORPUS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    text: 'RGPD biometrie consentement',
    filters: { jurisdictions: ['FR', 'EU'], statusFlags: ['green', 'yellow'] },
    limit: 20,
  }),
});
const result = await response.json();
console.log(`${result.total} resultats, cout: ${response.headers.get('X-Korpus-Cost-USD')}`);

Python

import os
import requests

response = requests.post(
    "https://www.korpus.lu/api/v1/search",
    headers={"Authorization": f"Bearer {os.environ['KORPUS_API_KEY']}"},
    json={
        "text": "RGPD biometrie consentement",
        "filters": {"jurisdictions": ["FR", "EU"], "statusFlags": ["green", "yellow"]},
        "limit": 20,
    },
)
result = response.json()
print(f"{result['total']} resultats, cout: {response.headers['X-Korpus-Cost-USD']}")

Réponse

{
  "hits": [
    {
      "type": "headnote",
      "headnoteId": "uuid",
      "articleSlug": "consolidation-erreur-droit-2026",
      "articleTitle": "Consolidation du regime de l'erreur de droit...",
      "sequence": 1,
      "summary": "La premiere chambre civile precise...",
      "snippet": "...<mark>RGPD</mark>...",
      "legalRuleType": "Obligation",
      "statusFlag": "green",
      "score": 0.84
    }
  ],
  "total": 47,
  "offset": 0,
  "limit": 20,
  "embeddingCostUsd": 0.000012,
  "latencyMs": 287
}

GET /api/v1/articles/[slug]

Récupère un article complet (contenu, headnotes, concepts, integrity flags, groundedness score, judicialDecision).

curl "https://www.korpus.lu/api/v1/articles/consolidation-erreur-droit-2026" \
  -H "Authorization: Bearer $KORPUS_API_KEY"

MCP server (Model Context Protocol)

Korpus expose un serveur MCP HTTP compatible avec Claude Desktop, Cursor et tout client MCP. Quatre outils sont disponibles : korpus_search, korpus_get_article, korpus_rag_query, korpus_verify_claim. Chaque appel tools/call est facturé selon l'opération sous-jacente (search, article, rag, verify) — le handshake et tools/list sont facturés au tarif MCP ($0.05). Scope requis : mcp.

Configuration Claude Desktop

Ajoutez ce bloc à votre claude_desktop_config.json :

{
  "mcpServers": {
    "korpus": {
      "url": "https://www.korpus.lu/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer kpus_live_..."
      }
    }
  }
}

Test direct (JSON-RPC 2.0)

# Lister les outils disponibles
curl https://www.korpus.lu/api/v1/mcp \
  -H "Authorization: Bearer $KORPUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Appeler un outil
curl https://www.korpus.lu/api/v1/mcp \
  -H "Authorization: Bearer $KORPUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"korpus_search",
      "arguments":{"text":"force majeure","limit":5}
    }
  }'

Headers de réponse

Codes erreur