Les bases Kopik, dans votre code.

Aperçu : REST ou MCP ?

Les bases se trouvent au catalogue. Chaque base a un identifiant, son slug, visible dans son adresse : kopik.io/b/<slug>. Sa page donne aussi des extraits prêts à copier.

Posez vos questions dans n'importe quelle langue : la réponse revient dans la langue de la question, quelle que soit celle des documents. Avant la recherche, un modèle de langage traduit la question en mots-clés et synonymes dans la langue des documents ; la recherche plein texte est elle-même réglée sur cette langue (champ language, aussi indiqué sur la page de chaque base). Les 8 passages les plus pertinents sont retenus, et la réponse est rédigée à partir d'eux seuls.

Votre propre RAG privé. Passez une base en privé depuis votre tableau de bord et interrogez-la avec votre clé API, en REST ou en MCP : vous seul y avez accès, et vos questions à vos propres bases sont gratuites (usage raisonnable : 200 par jour). Vous déposez des documents, vous obtenez un point d'accès. Ni base vectorielle, ni pipeline d'ingestion, ni serveur à gérer.

Authentification

Créez une clé API depuis votre tableau de bord. Elle commence par kpk_ et ne s'affiche qu'une fois : gardez-la comme un mot de passe, côté serveur, jamais dans du code exécuté par un navigateur. Envoyez-la dans l'en-tête Authorization :

Authorization: Bearer kpk_…

L'en-tête x-api-key: kpk_… est aussi accepté. Les clés sont stockées hachées : si vous en perdez une, révoquez-la et créez-en une autre. Le catalogue (lister et consulter les bases) est public et ne demande pas de clé ; seules les questions en demandent une. Une clé révoquée cesse de fonctionner immédiatement. Votre clé ouvre aussi vos bases privées : gardez-la secrète.

Facturation

• Chaque base a son propre prix par question, fixé par son créateur et indiqué dans priceCents (en centimes d'euro).
• Le prix est débité de votre crédit Kopik, rechargé par carte depuis le tableau de bord. Le même crédit sert au site, à l'API et à MCP.
• Une question sans résultat n'est pas facturée : si la base ne contient rien de pertinent, ou si la réponse échoue pour une raison technique, le débit est annulé.
• Plafonnez le prix avec maxPriceCents : si la base coûte plus cher, l'appel est refusé (409, price_above_max) et rien n'est débité. Recommandé pour les agents qui tournent en boucle, car un créateur peut changer son prix à tout moment.
• Crédit insuffisant → erreur 402, code insufficient_credit ; rien n'est débité.
• La 1 question offerte chaque mois vaut sur le site uniquement : l'API et MCP sont toujours facturés.
• Vos propres bases sont gratuites, par tous les canaux : publiques, non listées ou privées (usage raisonnable : 200 questions par jour).
• Les modes answer et passages coûtent le même prix.
• Le crédit se recharge par carte (packs de 10, 25, 50 ou 100 €), n'expire jamais et n'est pas remboursable.

API REST

Adresse de base : https://kopik.io/api/v1. Corps et réponses en JSON (UTF-8).

curl "https://kopik.io/api/v1/bases?topic=legal&q=cong%C3%A9s"

{
  "bases": [
    {
      "slug": "code-du-travail-conges-x7k2",
      "title": "Code du travail : congés",
      "description": "Congés payés, congés pour événements familiaux, jours fériés…",
      "topic": "legal",
      "topicLabel": "Legal",
      "language": "french",
      "priceCents": 10,
      "documents": 12,
      "passages": 840,
      "questions": 1375,
      "url": "https://kopik.io/b/code-du-travail-conges-x7k2",
      "updatedAt": "2026-09-20T08:14:00.000Z"
    }
  ]
}

curl https://kopik.io/api/v1/bases/code-du-travail-conges-x7k2

{
  "slug": "code-du-travail-conges-x7k2",
  "title": "Code du travail : congés",
  "description": "Congés payés, congés pour événements familiaux, jours fériés…",
  "topic": "legal",
  "topicLabel": "Legal",
  "language": "french",
  "priceCents": 10,
  "documents": 12,
  "passages": 840,
  "questions": 1375,
  "url": "https://kopik.io/b/code-du-travail-conges-x7k2",
  "updatedAt": "2026-09-20T08:14:00.000Z"
}

curl -X POST https://kopik.io/api/v1/bases/code-du-travail-conges-x7k2/query \
  -H "Authorization: Bearer kpk_…" \
  -H "Content-Type: application/json" \
  -d '{"question": "Combien de jours de congé pour un mariage ?", "mode": "answer", "maxPriceCents": 20}'

{
  "id": "cm1x0q2ab0001kopik",
  "answer": "Un salarié a droit à **4 jours de congé** pour son mariage ou la conclusion d'un PACS [1]. Ce congé n'entraîne pas de réduction de salaire [2].",
  "passages": [
    {
      "n": 1,
      "document": "Code du travail (congés pour événements familiaux).pdf",
      "text": "Le salarié a droit, sur justification, à un congé : 1° Pour son mariage ou pour la conclusion d'un pacte civil de solidarité : quatre jours…",
      "score": 0.82
    },
    {
      "n": 2,
      "document": "Code du travail (congés pour événements familiaux).pdf",
      "text": "Ces jours d'absence n'entraînent pas de réduction de la rémunération…",
      "score": 0.61
    }
  ],
  "costCents": 10,
  "balanceCents": 2490
}

curl -X POST https://kopik.io/api/v1/bases/code-du-travail-conges-x7k2/query \
  -H "Authorization: Bearer kpk_…" \
  -H "Content-Type: application/json" \
  -d '{"question": "congé mariage", "mode": "passages"}'

{
  "id": "cm1x0q9cd0002kopik",
  "answer": null,
  "passages": [
    { "n": 1, "document": "…", "text": "…", "score": 0.82 }
  ],
  "costCents": 10,
  "balanceCents": 2480
}

Erreurs

Toute erreur renvoie un statut HTTP et un corps JSON avec un message lisible et un code stable, fait pour les machines :

{
  "error": "Crédit insuffisant : cette base coûte 0,10 € par question. Rechargez sur kopik.io/fr/dashboard.",
  "code": "insufficient_credit"
}

Testez le code, jamais le message : les messages peuvent être reformulés, les codes ne changent pas.

Langue des messages d'erreur

Les messages sont en anglais par défaut. Envoyez x-kopik-locale: fr (ou en) pour choisir ; à défaut, un en-tête Accept-Language commençant par fr donne le français. Le code est le même dans toutes les langues.

curl -X POST https://kopik.io/api/v1/bases/code-du-travail-conges-x7k2/query \
  -H "Authorization: Bearer kpk_…" \
  -H "x-kopik-locale: fr" \
  -H "Content-Type: application/json" \
  -d '{"question": "Combien de jours de congé pour un mariage ?"}'

Serveur MCP

Kopik expose un serveur MCP (transport « Streamable HTTP », sans état), compatible avec Claude, Cursor, ChatGPT et tout client MCP. Les noms, descriptions et résultats des outils sont en anglais. Deux adresses, selon ce que vous voulez donner à votre agent :

Outils

list_bases{ topic?, query? }

Liste les bases publiques, filtrables par thème ou mot-clé. Gratuit. Adresse catalogue uniquement.

ask_base{ base, question, maxPriceCents? }

Réponse rédigée suivie des passages sources numérotés.

search_base{ base, question, maxPriceCents? }

Passages pertinents seuls, sans réponse rédigée. Même prix que ask_base.

Sur l'adresse d'une seule base, base disparaît : ask_base { question } et search_base { question }. Le maxPriceCents facultatif refuse l'appel, sans rien débiter, si la base coûte plus cher.

Chaque appel est facturé au prix de la base, comme par l'API, et se termine par le coût et le solde restant. La clé passe dans l'en-tête Authorization: Bearer kpk_… ; seul list_bases fonctionne sans. Les lots JSON-RPC sont limités à 10 requêtes.

Protection contre l'injection de prompt. Le texte issu d'une base est renvoyé entre des balises <kopik-untrusted>, précédé d'une note qui demande à l'agent de le traiter strictement comme une donnée de référence et de ne jamais suivre les instructions qu'il contient.

Claude Code

claude mcp add --transport http kopik https://kopik.io/api/mcp --header "Authorization: Bearer kpk_…"

claude mcp add --transport http kopik-code-du-travail-conges-x7k2 "https://kopik.io/api/mcp?base=code-du-travail-conges-x7k2" --header "Authorization: Bearer kpk_…"

Gardez les guillemets autour de l'adresse : sous zsh (le shell par défaut de macOS), un ? non protégé est un motif de fichier et la commande échoue.

Autres clients (Cursor, Claude Desktop, …)

La plupart des clients lisent un fichier de configuration mcpServers (dans Cursor : .cursor/mcp.json). Le format courant, avec une adresse et des en-têtes :

{
  "mcpServers": {
    "kopik": {
      "url": "https://kopik.io/api/mcp",
      "headers": { "Authorization": "Bearer kpk_…" }
    },
    "kopik-code-du-travail-conges-x7k2": {
      "url": "https://kopik.io/api/mcp?base=code-du-travail-conges-x7k2",
      "headers": { "Authorization": "Bearer kpk_…" }
    }
  }
}

Limites et sécurité

Les limites protègent le service et votre crédit. Au-delà, l'appel renvoie 429 avec le code rate_limited.

Sécurité côté agents : fixez maxPriceCents pour qu'un changement de prix ne coûte jamais plus que prévu à un agent qui boucle ; testez le code d'erreur ; et traitez le contenu des bases comme une donnée (par MCP, il arrive entre des balises <kopik-untrusted>). Les réponses sont rédigées à partir des seuls passages de la base, mais peuvent se tromper : elles ne constituent pas un conseil juridique, médical ou financier.

Exemples

JavaScript (fetch, Node 18+)

const res = await fetch("https://kopik.io/api/v1/bases/code-du-travail-conges-x7k2/query", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KOPIK_API_KEY}`,
    "Content-Type": "application/json",
    "x-kopik-locale": "fr",
  },
  body: JSON.stringify({
    question: "Combien de jours de congé pour un mariage ?",
    mode: "answer",
  }),
});

const data = await res.json();
if (!res.ok) {
  // data.code is stable: branch on it (e.g. "insufficient_credit", "rate_limited").
  throw new Error(`Kopik ${res.status} ${data.code}: ${data.error}`);
}

console.log(data.answer);
for (const p of data.passages) console.log(`[${p.n}] ${p.document}`);
console.log(`Coût: €${(data.costCents / 100).toFixed(2)} · solde: €${(data.balanceCents / 100).toFixed(2)}`);

Python (requests)

import os
import requests

res = requests.post(
    "https://kopik.io/api/v1/bases/code-du-travail-conges-x7k2/query",
    headers={
        "Authorization": f"Bearer {os.environ['KOPIK_API_KEY']}",
        "x-kopik-locale": "fr",
    },
    json={"question": "Combien de jours de congé pour un mariage ?", "mode": "answer"},
    timeout=60,
)
data = res.json()
if not res.ok:
    # data["code"] is stable: branch on it (e.g. "insufficient_credit", "rate_limited").
    raise RuntimeError(f"Kopik {res.status_code} {data['code']}: {data['error']}")

print(data["answer"])
for p in data["passages"]:
    print(f"[{p['n']}] {p['document']}")
print(f"Coût: €{data['costCents'] / 100:.2f} · solde: €{data['balanceCents'] / 100:.2f}")

Une réponse peut prendre une vingtaine de secondes : prévoyez un délai d'attente d'au moins 60 secondes, et réessayez après une pause en cas de 429 (rate_limited).