— Référence API

API GUARDIAN.

Le composant qui encadre les appels aux modèles de langage : supervision, plafonnement des coûts, filtrage des données sensibles et exercice des droits.

Avant de commencer

GUARDIAN est une API interne. Elle n'est pas ouverte à l'inscription : l'URL de production et le jeton d'accès sont remis nominativement. Cette page documente son fonctionnement, elle ne donne pas accès au service.

Sauf mention contraire, chaque endpoint attend un en-tête Authorization de type Bearer. Deux endpoints seulement sont publics : la sonde de santé légère et la page de désinscription.

Les échanges se font en JSON, en UTF-8. Le corps d'une requête est limité à 1 Mo, sauf pour le rendu PDF qui accepte 5 Mo. Une requête mal formée reçoit un code 400 accompagné du champ error et du détail des champs fautifs — la validation est stricte et refuse tout champ hors schéma plutôt que de l'ignorer silencieusement.

Les montants sont exprimés en centimes d'euro, les durées en millisecondes, les dates au format ISO 8601, et les mois au format AAAA-MM.

Santé du service

Deux sondes : une publique et légère, destinée à un moniteur externe, et une détaillée réservée aux tableaux de bord internes.

GET/healthpublic

Sonde de santé légère.

Teste la connectivité à la base par une requête triviale. Conçue pour un moniteur externe qui interroge fréquemment.

Réponses

200: Toujours. Le corps porte status (« ok » ou « degraded »), service, version, db (booléen) et timestamp. Un service dégradé répond 200 avec status « degraded », pas une erreur HTTP.

Limité à 60 appels par minute.

GET/v1/healthjeton requis

Santé détaillée, pour tableau de bord.

Ajoute la latence de la base, le nombre de heartbeats reçus dans la dernière heure, le nombre d'incidents ouverts et le résultat du dernier passage de purge.

Réponses

200: Corps : status, service, version, db, db_latency_ms, recent_heartbeats_1h, open_incidents, last_purge et timestamp.
401: Jeton absent ou invalide.

Supervision des workflows

Le cœur de la détection de panne silencieuse. Chaque workflow signale sa fin d'exécution ; l'absence de signal au-delà du délai attendu déclenche une alerte.

POST/v1/heartbeatjeton requis

Signale la fin d'exécution d'un workflow.

À appeler en dernier nœud de chaque workflow, en succès comme en échec. C'est l'absence d'appel, et non un appel en échec, qui révèle une panne silencieuse.

Corps de la requête

Champ	Type	Requis	Contraintes
`client_slug`	chaîne	oui	2 à 64 caractères, minuscules, chiffres et tirets
`workflow_external_id`	chaîne	oui	1 à 64 caractères
`workflow_name`	chaîne	oui	1 à 120 caractères
`status`	énumération	oui	success ou failure
`duration_ms`	entier	non	positif ou nul, maximum 86 400 000
`error_message`	chaîne ou null	non	2 000 caractères maximum
`expected_interval_minutes`	entier	non	strictement positif, maximum 10 080 (sept jours)
`grace_period_minutes`	entier	non	positif ou nul, maximum 120
`criticality`	énumération	non	critical, standard ou low
`payload`	objet libre	non	—

Réponses

202: Heartbeat accepté. Corps : accepted, workflow_id, status_before, status_after et transitioned — ce dernier indiquant si l'état du workflow a changé.
400: invalid_body — le corps ne respecte pas le schéma ; le détail des champs fautifs est renvoyé.
401: Jeton absent ou invalide.
500: internal_error.

POST/v1/workflowsjeton requis

Déclare ou met à jour le contrat de surveillance d'un workflow.

Définit à quelle fréquence un workflow est censé s'exécuter. C'est ce contrat qui permet de qualifier un silence d'anormal.

Corps de la requête

Champ	Type	Requis	Contraintes
`client_slug`	chaîne	oui	minuscules, chiffres et tirets
`external_id`	chaîne	oui	non vide
`name`	chaîne	oui	non vide
`expected_interval_minutes`	entier ou null	non	strictement positif
`grace_period_minutes`	entier	non — défaut 15	positif ou nul
`criticality`	énumération	non — défaut standard	critical, standard ou low

Réponses

200: Contrat enregistré.
400: invalid_body.
401: Jeton absent ou invalide.
500: internal_error.

GET/v1/clients/:slug/workflowsjeton requis

Liste les workflows surveillés d'un client.

Paramètres de chemin

Champ	Type	Requis	Contraintes
`slug`	chaîne	oui	identifiant du client

Réponses

200: Corps : workflows.
401: Jeton absent ou invalide.
500: internal_error.

POST/v1/health-checks/runjeton requis

Déclenche manuellement la détection de pannes silencieuses.

Le même travail que la tâche planifiée, exécuté à la demande. Le corps de la requête est ignoré. Prévu pour le débogage.

Réponses

200: Résultat de la détection.
401: Jeton absent ou invalide.

Plafonnement des coûts

Un plafond mensuel par client, vérifié avant chaque appel au modèle et débité après. C'est ce qui rend possible un forfait à prix fixe quel que soit le volume traité.

POST/v1/budgetsjeton requis

Crée ou met à jour le plafond mensuel d'un client.

Corps de la requête

Champ	Type	Requis	Contraintes
`client_slug`	chaîne	oui	2 à 64 caractères, minuscules, chiffres et tirets
`month`	chaîne	non — défaut mois courant	format AAAA-MM
`cap_cents`	entier	oui	strictement positif, maximum 10 000 000 (100 000 €)
`on_cap_reached`	énumération	non — défaut block	block, downgrade ou queue

Réponses

200: Budget enregistré.
400: invalid_body.
401: Jeton absent ou invalide.
500: internal_error.

POST/v1/budgets/checkjeton requis

Vérifie le budget restant avant un appel au modèle.

Répond 200 même lorsque l'appel n'est pas autorisé : c'est à l'appelant de décider quoi faire du champ allowed. Un refus budgétaire n'est pas une erreur technique.

Corps de la requête

Champ	Type	Requis	Contraintes
`client_slug`	chaîne	oui	2 à 64 caractères, minuscules, chiffres et tirets
`estimated_cost_cents`	entier	oui	positif ou nul, maximum 1 000 000
`month`	chaîne	non	format AAAA-MM

Réponses

200: Corps : allowed, spent_cents, cap_cents, behavior et month.
400: invalid_body.
401: Jeton absent ou invalide.
500: internal_error.

POST/v1/budgets/recordjeton requis

Comptabilise le coût réel après un appel au modèle.

Corps de la requête

Champ	Type	Requis	Contraintes
`client_slug`	chaîne	oui	2 à 64 caractères, minuscules, chiffres et tirets
`cost_cents`	entier	oui	positif ou nul, maximum 1 000 000
`month`	chaîne	non	format AAAA-MM
`llm_call_id`	chaîne	non	1 à 64 caractères

Réponses

202: Coût enregistré. Corps : spent_cents, cap_cents, pct et breached_thresholds.
400: invalid_body.
401: Jeton absent ou invalide.
500: internal_error.

GET/v1/clients/:slug/budgetsjeton requis

Liste tous les mois budgétés d'un client.

Paramètres de chemin

Champ	Type	Requis	Contraintes
`slug`	chaîne	oui	—

Réponses

200: Corps : budgets.
401: Jeton absent ou invalide.
500: internal_error.

GET/v1/clients/:slug/budgets/:monthjeton requis

Lit le budget d'un mois donné.

Paramètres de chemin

Champ	Type	Requis	Contraintes
`slug`	chaîne	oui	—
`month`	chaîne	oui	format AAAA-MM

Réponses

200: Budget du mois.
404: no_budget — aucun budget défini pour ce mois.
401: Jeton absent ou invalide.
500: internal_error.

Passerelle vers les modèles de langage

Un seul point de passage pour tous les appels aux modèles, qui applique dans l'ordre : le plafond budgétaire, la règle de souveraineté, le repli en cas d'incident fournisseur, puis la validation de la réponse.

POST/v1/llm/chatjeton requis

Exécute une complétion encadrée.

La règle de souveraineté refuse un modèle non européen si le client ne l'a pas explicitement autorisé. La validation, optionnelle, réessaie automatiquement lorsque la réponse ne respecte pas le format attendu — c'est le garde-fou contre les réponses inventées.

Corps de la requête

Champ	Type	Requis	Contraintes
`client_slug`	chaîne	oui	2 à 64 caractères, minuscules, chiffres et tirets
`workflow_external_id`	chaîne	non	1 à 128 caractères
`model`	énumération	non — défaut mistral-small-latest	mistral-small-latest, mistral-large-latest, gpt-4o-mini ou gpt-4o
`messages`	tableau	oui	1 à 50 éléments
`messages[].role`	énumération	oui	system, user ou assistant
`messages[].content`	chaîne	oui	1 à 50 000 caractères
`max_tokens`	entier	non — défaut 1024	strictement positif, maximum 4 096
`temperature`	nombre	non — défaut 0.2	entre 0 et 2
`validation.mode`	énumération	non	json, json_schema ou regex
`validation.schema`	objet	non	obligatoire lorsque mode vaut json_schema
`validation.regex`	chaîne	non	obligatoire lorsque mode vaut regex, 2 000 caractères maximum
`validation.max_retries`	entier	non — défaut 2	entre 0 et 5

Réponses

200: Corps : id, provider, model, fallback_from, message, usage, cost_cents, latency_ms, budget et validation.
400: invalid_body, ou validation_config_error si la configuration de validation est incohérente.
402: budget_exceeded — le plafond mensuel du client est atteint.
403: sovereignty_violation — modèle non autorisé pour ce client.
404: unknown_client ou inactive_client.
422: validation_failed — la réponse n'a pas satisfait la validation après les tentatives autorisées.
502: provider_error — le fournisseur de modèle a échoué.
500: no_api_key ou internal_error.
401: Jeton absent ou invalide.

GET/v1/llm/callsjeton requis

Liste les appels récents d'un client.

Paramètres de requête

Champ	Type	Requis	Contraintes
`client`	chaîne	oui	identifiant du client
`limit`	entier	non — défaut 50	ramené dans l'intervalle 1 à 200

Réponses

200: Corps : calls, du plus récent au plus ancien.
400: missing_client — le paramètre client est obligatoire.
404: unknown_client.
401: Jeton absent ou invalide.

Contrôle avant exécution

Une porte unique interrogée avant chaque exécution de workflow. Elle évite qu'un automate tourne pour un client suspendu ou au-delà de son plafond.

GET/v1/clients/:slug/preflightjeton requis

Autorise ou refuse une exécution, et renvoie la configuration du client.

Paramètres de chemin

Champ	Type	Requis	Contraintes
`slug`	chaîne	oui	—

Paramètres de requête

Champ	Type	Requis	Contraintes
`workflow_external_id`	chaîne	non	1 à 128 caractères
`estimated_cost_cents`	entier	non — défaut 0	positif ou nul, maximum 1 000 000

Réponses

200: Corps : proceed, reason et client_config.
400: invalid_query.
402: budget_capped — plafond mensuel atteint.
409: inactive_client — le client est suspendu.
401: Jeton absent ou invalide.
500: internal_error.

Filtrage des données sensibles

Remplace dans un texte libre les segments relevant de l'article 9 du RGPD et les identifiants réglementés, avant que ce texte ne soit transmis ailleurs. Le texte soumis n'est jamais journalisé.

POST/v1/redact-piijeton requis

Masque les catégories sensibles d'un texte.

Les segments détectés sont remplacés par un marqueur explicite indiquant la catégorie. Catégories reconnues : identifiants gouvernementaux, identifiants financiers, coordonnées, santé, opinions politiques, convictions religieuses, orientation sexuelle et appartenance syndicale.

Corps de la requête

Champ	Type	Requis	Contraintes
`client_slug`	chaîne	oui	1 à 64 caractères, minuscules, chiffres et tirets
`text`	chaîne	oui	1 à 5 000 caractères
`context`	énumération	non — défaut generic	qualification_brief, quote_brief ou generic

Réponses

200: Corps : redacted_text, sensitive_categories_detected, contained_sensitive_data, length_input et length_output.
400: invalid_body.
404: unknown_client ou inactive_client.
401: Jeton absent ou invalide.
500: internal_error.

Désinscription

Génère des liens de désinscription signés et sert la page publique de confirmation. Le lien porte sa propre validité : il ne peut être ni forgé ni prolongé.

POST/v1/optout/tokensjeton requis

Émet un lien de désinscription signé.

Corps de la requête

Champ	Type	Requis	Contraintes
`client_slug`	chaîne	oui	1 à 64 caractères, minuscules, chiffres et tirets
`subject_id_hash`	chaîne	oui	empreinte SHA-256 en hexadécimal, 64 caractères
`channel`	énumération	non — défaut email	email
`expires_in_days`	entier	non — défaut 365	entre 1 et 365

Réponses

200: Corps : token, opt_out_url et expires_at.
400: invalid_body.
401: Jeton absent ou invalide.
500: internal_error.

L'identifiant de la personne n'est jamais transmis en clair : seule son empreinte l'est.

GET/v1/optoutpublic

Page publique de confirmation de désinscription.

Seul endpoint destiné à être ouvert directement par une personne. Il répond en HTML, jamais en JSON, et interdit l'indexation par les moteurs de recherche.

Paramètres de requête

Champ	Type	Requis	Contraintes
`token`	chaîne	oui	—

Réponses

200: Désinscription enregistrée, page de confirmation.
400: Lien invalide ou altéré.
404: Client inconnu.
410: Lien expiré.

Limité à 30 appels par minute et par adresse.

Droits des personnes

Export et effacement à la demande, avec traçabilité. Ces endpoints servent à répondre à une personne qui exerce ses droits au titre du RGPD.

POST/v1/dsar/exportjeton requis

Génère une archive des données d'un client.

L'archive couvre l'ensemble du périmètre du client : sa fiche, ses workflows, ses heartbeats, ses incidents, ses budgets, ses appels aux modèles et l'historique de ses demandes.

Corps de la requête

Champ	Type	Requis	Contraintes
`client_slug`	chaîne	oui	minuscules, chiffres et tirets
`requested_by`	chaîne	oui	adresse email valide
`subject_email`	chaîne	non	adresse email valide

Réponses

200: Corps : request_id, records_exported et export_path.
400: invalid_body.
404: unknown_client.
500: export_failed ou internal_error.
401: Jeton absent ou invalide.

POST/v1/dsar/deletejeton requis

Efface les appels aux modèles d'un client.

Effacement logique : les enregistrements sont retirés des exports et des lectures, puis purgés définitivement vingt-quatre mois après leur création. Le champ confirm doit valoir exactement vrai — un garde-fou volontaire contre l'appel accidentel.

Corps de la requête

Champ	Type	Requis	Contraintes
`client_slug`	chaîne	oui	minuscules, chiffres et tirets
`requested_by`	chaîne	oui	adresse email valide
`subject_email`	chaîne	non	adresse email valide
`confirm`	booléen	oui	doit valoir vrai

Réponses

200: Corps : request_id et records_deleted.
400: invalid_body.
404: unknown_client.
401: Jeton absent ou invalide.
500: internal_error.

GET/v1/clients/:slug/dsar-requestsjeton requis

Historique des demandes d'un client.

Paramètres de chemin

Champ	Type	Requis	Contraintes
`slug`	chaîne	oui	—

Paramètres de requête

Champ	Type	Requis	Contraintes
`limit`	entier	non — défaut 50	entre 1 et 100

Réponses

200: Corps : requests, de la plus récente à la plus ancienne.
400: invalid_query.
404: unknown_client.
401: Jeton absent ou invalide.
500: internal_error.

Documents et audits

Rendu de documents en PDF et production de rapports d'audit asynchrones.

POST/v1/render-pdfjeton requis

Convertit un document HTML en PDF.

Accepte jusqu'à 5 Mo de contenu, contre 1 Mo pour les autres endpoints.

Corps de la requête

Champ	Type	Requis	Contraintes
`html`	chaîne	oui	5 Mo maximum
`options.paperFormat`	énumération	non — défaut A4	A4, Letter ou A3
`options.marginTop`	chaîne	non — défaut 0.4	nombre en pouces
`options.marginBottom`	chaîne	non — défaut 0.4	nombre en pouces
`options.marginLeft`	chaîne	non — défaut 0.4	nombre en pouces
`options.marginRight`	chaîne	non — défaut 0.4	nombre en pouces
`options.landscape`	booléen	non — défaut faux	—
`options.printBackground`	booléen	non — défaut vrai	—

Réponses

200: Le PDF, en binaire.
400: invalid_body.
401: Jeton absent ou invalide.
500: internal_error.

POST/v1/audit/startjeton requis

Lance un rapport d'audit.

Traitement asynchrone : l'appel rend immédiatement un identifiant de tâche, à interroger ensuite.

Corps de la requête

Champ	Type	Requis	Contraintes
`entreprise_nom`	chaîne	oui	2 à 200 caractères
`siren`	chaîne	non	exactement 9 chiffres
`site_url`	chaîne	non	URL valide
`profondeur`	énumération	non — défaut mini	mini ou complet
`overrides`	objet	non	valeurs mesurées connues, qui remplacent les hypothèses
`hypotheses`	objet	non	paramètres du calcul lorsque la mesure manque

Réponses

202: Corps : jobId et status.
400: invalid_body.
401: Jeton absent ou invalide.

GET/v1/audit/:idjeton requis

État et contenu d'un rapport d'audit.

Paramètres de chemin

Champ	Type	Requis	Contraintes
`id`	chaîne	oui	64 caractères maximum, alphanumériques, tirets et tirets bas

Réponses

200: Corps : id, status, report, error, createdAt et finishedAt.
404: not_found — identifiant mal formé ou tâche inconnue.
401: Jeton absent ou invalide.

GET/v1/audit/:id/pdfjeton requis

Rapport d'audit au format PDF.

Paramètres de chemin

Champ	Type	Requis	Contraintes
`id`	chaîne	oui	64 caractères maximum, alphanumériques, tirets et tirets bas

Réponses

200: Le PDF, en binaire.
404: not_found.
409: not_ready — la tâche n'est pas terminée.
502: pdf_render_failed.
401: Jeton absent ou invalide.

Une question sur l'intégration ?

Cette référence décrit l'état du service au moment de sa rédaction. Si un comportement observé s'en écarte, c'est la page qui a tort : signalez-le, elle sera corrigée.

Nous écrire