Documentation de l’API

L’API Regunow utilise HTTPS, l’authentification Bearer et le préfixe versionné /api/v1. Cette documentation est accessible sans compte. Les requêtes API nécessitent un accès Pro actif et l’acceptation des politiques en vigueur.

1. Connectez-vous à Regunow et créez une clé dans Paramètres → Clés API.
2. Conservez le secret en lieu sûr. Il n’est affiché qu’une fois, lors de la création de la clé.
3. Définissez votre hôte et votre clé, puis envoyez votre première question depuis un serveur ou une automatisation de confiance.

# Use your Regunow host and a key from Settings → API Keys.
export REGUNOW_BASE_URL="https://YOUR_REGUNOW_HOST"
export REGUNOW_API_KEY="YOUR_API_KEY"

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/chat/completions" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-question-001" \
  -d '{
    "messages": [{
      "role": "user",
      "content": "Which EU product-safety obligations apply to a connected consumer device?"
    }],
    "mode": "jurisdiction",
    "jurisdiction": "eu"
  }'

La réponse se trouve dans output.content. Les références aux sources et les crédits facturés sont inclus. Cette requête consomme des crédits. Utilisez une nouvelle clé d’idempotence pour chaque nouvelle question.

// Node.js: set REGUNOW_BASE_URL and REGUNOW_API_KEY in your environment.
// Generate one key per operation; keep it unchanged when retrying that operation.
import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID();
const response = await fetch(
  process.env.REGUNOW_BASE_URL + "/api/v1/chat/completions",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer " + process.env.REGUNOW_API_KEY,
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify({
      messages: [{ role: "user", content: "Summarize EU product-safety obligations." }],
      mode: "jurisdiction",
      jurisdiction: "eu",
    }),
  },
);

const result = await response.json();
if (!response.ok) {
  throw new Error(result.error.code + ": " + result.error.message);
}
console.log(result.output.content);

Envoyez votre clé API dans l’en-tête HTTP Authorization à chaque requête. Les clés dans les URL, cookies ou corps de requête ne sont pas acceptées.

Authorization: Bearer rgn_live_...

Stockez les clés dans une variable d’environnement ou un gestionnaire de secrets. Ne les incluez pas dans le code du navigateur, les applications mobiles, les dépôts publics ou les journaux. L’accès depuis un navigateur d’une autre origine n’est pas activé ; passez par votre serveur.

Les clés désactivées, supprimées ou expirées cessent immédiatement d’authentifier les requêtes. Regunow ne conserve qu’une empreinte du secret et ne peut donc pas l’afficher à nouveau. Créez une clé de remplacement si nécessaire.

L’accès Pro et l’acceptation des politiques sont vérifiés à chaque requête. Si vous recevez legal_acceptance_required, le titulaire de la clé doit se connecter et ouvrir Acceptation des conditions légales. Une clé API ne peut pas accepter les politiques.

GET/api/v1/models

Découvrez les modèles, niveaux d’effort, juridictions, langues de réponse et fonctionnalités disponibles. Ce point de terminaison authentifié ne facture pas de crédits séparément et permet de vérifier une clé avant une requête de chat.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/models" \
  -H "Authorization: Bearer $REGUNOW_API_KEY"

Utilisez les valeurs renvoyées par le catalogue de votre déploiement. En mode Juridiction, omettez model et effort pour utiliser les valeurs par défaut acceptées. Si vous les fournissez, elles doivent correspondre à Sonnet 4.6 / Élevé. Sans pièce jointe, le service de récupération gère le modèle de réponse ; le champ du modèle décrit la sélection validée.

POST/api/v1/chat/completions

Envoyez un corps JSON contenant un tableau messages. Par défaut, l’API renvoie la réponse complète en JSON. Définissez stream sur true pour recevoir le texte progressivement.

{
  "messages": [{
    "role": "user",
    "content": "What retention period does this policy specify? Cite the document."
  }],
  "mode": "freestyle",
  "web_search": "off",
  "response_language": "en",
  "file_ids": ["YOUR_FILE_ID"]
}

Remplacez YOUR_FILE_ID par l’UUID renvoyé après un téléversement réussi. Pour chaque question suivante, envoyez l’historique pertinent de l’utilisateur et de l’assistant ainsi que les file_ids souhaités. L’API ne mémorise pas automatiquement l’historique ni les pièces jointes.

Les messages système et les champs inconnus sont rejetés. Cette API ne propose pas la génération d’images ou de rapports, l’entrée audio ni l’accès aux mémoires enregistrées. Les images téléversées peuvent servir d’entrée aux questions.

Une requête réussie renvoie object: "regunow.chat.completion", la réponse, les métadonnées des sources, l’utilisation et les temps mesurés. Les valeurs suivantes sont illustratives.

{
  "id": "request-uuid",
  "request_id": "request-uuid",
  "object": "regunow.chat.completion",
  "created": 1790812800,
  "model": "jp.anthropic.claude-sonnet-4-6",
  "latency": {
    "time_to_first_token_ms": 2345,
    "time_to_answer_completion_ms": 9876
  },
  "output": {
    "input_files": [],
    "role": "assistant",
    "content": "The complete answer...",
    "finish_reason": "end_turn",
    "citations": [],
    "sources": [],
    "web_search": false
  },
  "usage": {
    "input_tokens": 1234,
    "output_tokens": 456,
    "charged_microcredits": 789000,
    "charged_credits": 0.789
  }
}

• output.content contient le texte définitif de la réponse. Les positions des citations se rapportent à cette chaîne finale ; sourceIndexes désigne les entrées de output.sources.
• Les sources comprennent titre, nom de fichier, type MIME, URI et extrait récupéré. Affichez les extraits et citations avec la réponse.
• Une URI de source indique un emplacement qui peut être privé. Seules les URL publiques des éditeurs doivent être présentées comme liens accessibles. L’API ne permet ni le téléchargement ni la traduction des fichiers sources réglementaires.
• Avec des pièces jointes, output.input_files identifie les fichiers fournis. Les sources jointes ont un file_id ; les sources réglementaires et web ont file_id: null. Les URI des pièces jointes sont null.
• La présence d’un fichier d’entrée ne prouve pas qu’il étaye toutes les affirmations. Les modèles peuvent omettre les citations intégrées ; les images et numérisations peuvent avoir des extraits vides.

Les nombres de tokens peuvent être null si le service de récupération ne les fournit pas ; cela signifie inconnu, pas zéro. charged_credits indique les frais enregistrés pour le client. created est un horodatage Unix en secondes ; les latences sont en millisecondes.

Chaque réponse d’un point de terminaison contient un en-tête X-Request-Id. Conservez cet identifiant pour le diagnostic. Les réponses de chat et d’erreur en JSON contiennent aussi request_id.

Définissez "stream": true. La réponse utilise text/event-stream. Avec cURL, ajoutez -N pour désactiver la mise en tampon de la sortie.

curl --fail-with-body -N \
  "$REGUNOW_BASE_URL/api/v1/chat/completions" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: streaming-question-001" \
  -d '{
    "messages": [{"role":"user","content":"Summarize EU product-safety obligations."}],
    "mode": "jurisdiction",
    "jurisdiction": "eu",
    "stream": true
  }'

Lisez des événements SSE complets séparés par des lignes vides ; un bloc réseau peut contenir une partie d’événement ou plusieurs événements. Ajoutez choices[0].delta.content à mesure qu’il arrive. Ignorez les commentaires de maintien de connexion commençant par :.

data: {"choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{"content":"The answer begins..."},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"choices":[],"usage":{"prompt_tokens":1234,"completion_tokens":456,"total_tokens":1690},"regunow":{"output":{},"latency":{},"usage":{"charged_credits":0.789,"charged_microcredits":789000}}}

data: [DONE]

L’événement final de métadonnées a un tableau choices vide. Lisez la réponse définitive, les citations et les sources dans regunow.output, les temps dans regunow.latency et les crédits dans regunow.usage. Les nombres de tokens utilisent usage.prompt_tokens et usage.completion_tokens.

La récupération et le traitement des citations peuvent entraîner des pauses. Le texte reste provisoire jusqu’aux métadonnées finales. Une erreur après le début de la diffusion arrive sous forme d’objet error, puis [DONE] ; HTTP 200 seul ne garantit pas la réussite. Les échecs antérieurs d’authentification ou de validation renvoient des erreurs JSON ordinaires.

La répétition d’une opération terminée reste en SSE et renvoie la réponse enregistrée en un seul bloc de texte avec X-Idempotent-Replayed: true.

Téléversez des documents ou images, puis joignez leurs identifiants à une requête de chat. Ils partagent la Bibliothèque et le quota du titulaire de la clé. Les documents sont limités à 10 MiB et les images à 5 MiB.

Téléversement direct (recommandé)

Ce processus en trois étapes envoie les octets d’origine directement au stockage, évitant les limites de corps de requête de l’application. Utilisez-le pour les intégrations hébergées, surtout avec de gros fichiers.

POST/api/v1/files/upload-intents

Envoyez uniquement name, mime_type et bytes (la taille exacte). Une requête réussie renvoie HTTP 201 avec l’identifiant d’un fichier en attente et une URL signée valable 300 secondes.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files/upload-intents" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: policy-intent-001" \
  -d '{"name":"policy.txt","mime_type":"text/plain","bytes":16384}'

{
  "id": "YOUR_FILE_ID",
  "status": "pending",
  "upload_method": "PUT",
  "upload_url": "SIGNED_UPLOAD_URL",
  "upload_headers": {"Content-Type": "text/plain"},
  "expires_in": 300
}

Définissez FILE_ID avec l’id renvoyé. Utilisez les upload_method, upload_url et upload_headers fournis pour envoyer les octets d’origine exacts. Indiquez la Content-Length exacte. N’envoyez pas la clé API Regunow à l’URL de téléversement et ne journalisez pas les URL signées.

# Set UPLOAD_URL from the intent response. Use its returned upload_headers.
# This example assumes policy.txt is exactly 16,384 bytes.
curl --fail-with-body -X PUT "$UPLOAD_URL" \
  -H "Content-Type: text/plain" \
  -H "Content-Length: 16384" \
  --data-binary @./policy.txt

POST/api/v1/files/{fileId}/complete

Envoyez {} avec une autre clé d’idempotence. La finalisation valide les octets et renvoie HTTP 200 avec un fichier disponible. Son identifiant n’est utilisable dans file_ids qu’après réussite.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files/$FILE_ID/complete" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: policy-complete-001" \
  -d '{}'

Si l’URL expire, supprimez le fichier en attente inutilisé et préparez un nouveau téléversement avec une nouvelle clé. Répéter la préparation ne prolonge pas l’URL. Si le résultat de la finalisation est incertain, consultez d’abord l’état du fichier. S’il reste en attente, réessayez avec une nouvelle clé d’idempotence ; l’ancienne restitue son résultat enregistré. Finaliser un fichier déjà disponible renvoie ses métadonnées.

Téléversement multipart

POST/api/v1/files

Pour les petits fichiers, envoyez un champ multipart/form-data nommé file. Envoyez les octets d’origine, pas du base64 ni une URL distante. Votre passerelle d’hébergement peut imposer une limite de corps inférieure à celle des fichiers de l’API.

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files" \
  -H "Authorization: Bearer $REGUNOW_API_KEY" \
  -H "Idempotency-Key: policy-upload-001" \
  -F "file=@./policy.pdf;type=application/pdf"

Un téléversement réussi renvoie HTTP 201 avec un fichier disponible ; aucun appel de finalisation séparé n’est nécessaire.

{
  "id": "YOUR_FILE_ID",
  "object": "regunow.file",
  "name": "policy.pdf",
  "mime_type": "application/pdf",
  "category": "file",
  "bytes": 16384,
  "status": "available",
  "created_at": "2026-10-01T00:00:00Z",
  "request_id": "request-uuid",
  "usage": {"charged_microcredits":500,"charged_credits":0.0005}
}

Lister, consulter et supprimer des fichiers

curl --fail-with-body \
  "$REGUNOW_BASE_URL/api/v1/files?limit=20" \
  -H "Authorization: Bearer $REGUNOW_API_KEY"

Les clés d’un même compte accèdent aux fichiers disponibles de sa Bibliothèque. Les fichiers absents et ceux d’un autre compte renvoient tous deux 404. Si plusieurs utilisateurs passent par un seul compte, appliquez vos propres autorisations avant de joindre ou supprimer des fichiers.

Les téléversements en attente ou en échec occupent le quota jusqu’au nettoyage réussi. Les téléversements incomplets de plus de 24 heures peuvent être nettoyés. Un fichier disponible a passé la validation du téléversement ; l’extraction intervient à la question, donc des documents corrompus, chiffrés ou illisibles peuvent encore échouer à l’analyse.

Les requêtes de chat, téléversements et suppressions enregistrent une utilisation mesurée. Le catalogue des modèles et la lecture des métadonnées ne facturent pas de crédits séparément. L’extraction documentaire et l’analyse d’images sont facturées via la requête de chat.

Consultez les frais d’une opération dans usage.charged_credits. Un crédit équivaut à 1 000 000 de microcrédits. Les limites des clés sont distinctes des crédits du compte ; les deux peuvent bloquer une requête. Vérifiez l’utilisation et définissez les limites dans Paramètres → Clés API.

Les limites de contexte et de vision du modèle restent applicables même si chaque message et pièce jointe respecte les limites de l’API. Les budgets des clés sont réinitialisés sur des périodes glissantes quotidiennes, hebdomadaires ou mensuelles, à partir de la création de la clé ou du renouvellement de la période précédente.

Une requête lancée avec un budget disponible peut dépasser légèrement un faible solde restant, car son coût final n’est connu qu’après génération. Les nouvelles requêtes de chat et modifications de fichiers s’arrêtent dès que la limite est atteinte. Les réservations empêchent les requêtes simultanées de dépenser le même budget disponible.

Envoyez un Idempotency-Key pour chaque requête de chat, téléversement, finalisation et suppression. Il est facultatif, mais vivement recommandé pour éviter de répéter travail et frais après une déconnexion.

Idempotency-Key: a-unique-key-for-this-operation

• Générez une clé unique pour chaque nouvelle opération et conservez-la avec la requête d’origine.
• Réessayez avec la même clé API, la même clé d’idempotence et des entrées inchangées. Après règlement, l’état et la réponse enregistrés peuvent être restitués pendant 24 heures sans nouvel appel au fournisseur ni frais supplémentaires.
• Une répétition inclut X-Idempotent-Replayed: true. Réutiliser la clé avec d’autres entrées, ou pendant la première requête, renvoie 409.
• Les résultats mis en cache peuvent inclure des erreurs. Répéter la même clé peut restituer le même échec au lieu de relancer l’opération. Vérifiez le résultat avant une nouvelle opération.
• Après expiration de la fenêtre de répétition, réutiliser une clé lance une nouvelle requête pouvant être facturée.

Utilisez des délais exponentiels pour les problèmes temporaires de réseau, de limitation de débit ou de service. Gardez la même clé d’idempotence tant que le résultat est incertain. Corrigez d’abord les entrées invalides, identifiants expirés ou crédits épuisés.

Supprimer un fichier n’efface pas une réponse de chat ou de téléversement mise en cache pendant sa fenêtre de répétition. Une répétition après suppression renvoie la réponse d’origine sans recréer le fichier.

Les erreurs utilisent une structure JSON stable. Consultez error.code pour les traiter et conservez request_id ou l’en-tête X-Request-Id pour contacter l’assistance.

{
  "error": {
    "type": "request_error",
    "code": "invalid_request",
    "message": "messages must contain 1 to 20 alternating user/assistant messages, end with a user message, and stay within 64,000 characters."
  },
  "request_id": "request-uuid"
}