API IsoFind

IsoFind expose une API REST locale servie par FastAPI sur http://127.0.0.1:8001. Elle est utilisée par l'interface frontend Tauri et peut être interrogée directement par des scripts ou des outils tiers pour automatiser des opérations sur les données analytiques.

Informations générales

Toutes les routes retournent du JSON sauf indication contraire (exports CSV, images PNG). Les réponses d'erreur suivent le format FastAPI standard : {"detail": "message d'erreur"} avec le code HTTP correspondant. En mode multi-utilisateurs, les routes qui modifient des données requièrent un cookie de session isotrace_session valide.

La documentation interactive Swagger est accessible à http://127.0.0.1:8001/docs pendant qu'IsoFind est ouvert. Elle liste toutes les routes avec leurs schémas de données complets et permet de les tester directement.

L'API écoute uniquement sur 127.0.0.1 (localhost). Elle n'est pas accessible depuis le réseau local sauf configuration explicite. Pour un usage intranet multi-postes, consulter la documentation de déploiement réseau.

Système et authentification

GET /api/ready Vérifie que le backend est démarré et prêt.

Retourne {"status": "ready"}. Appelé par Tauri après le démarrage du processus FastAPI.

GET /health Vérification de santé du backend.

Retourne {"status": "healthy"}.

GET /api/version/info Informations de version et mode d'installation.

Retourne la version, le mode (single_user ou multi_user), la date de build et les fonctionnalités activées.

GET /api/system/mode Mode de fonctionnement du système.

GET /api/system/stats Statistiques globales du système (utilisateurs actifs, sessions, état de la base).

POST /api/auth/login Authentification utilisateur (mode multi-utilisateurs uniquement).

Corps : {"username": str, "password": str}

Retour : {"success": bool, "user": {...}} + cookie isotrace_session. En mode mono-utilisateur, toujours accepté.

POST /api/auth/logout Déconnexion et invalidation de la session.

GET /api/auth/check Vérifie si la session courante est valide.

Retourne l'utilisateur connecté ou {"authenticated": false}.

POST /api/auth/change-password Changement de mot de passe.

Corps : {"old_password": str, "new_password": str, "confirm_password": str}

POST /api/auth/lock Verrouille la session active sans la détruire.

GET /api/auth/sessions Liste les sessions actives de l'utilisateur courant.

DELETE /api/auth/sessions/{session_id} Invalide une session spécifique.

POST /api/auth/recovery Réinitialise le mot de passe admin via le code de récupération.

Corps : {"recovery_code": str, "new_password": str}. Usage unique : un nouveau code est généré après consommation.

Échantillons

GET /api/samples Liste tous les échantillons avec leurs données isotopiques.

Params : limit (int, optionnel), nombre max de résultats . sort (asc ou desc) : tri par date de création. Par défaut : tri par ID décroissant.

GET /api/samples/{sample_id} Récupère un échantillon précis avec ses données isotopiques.

Retourne 404 si l'identifiant n'existe pas.

GET /api/v2/samples/{sample_id}/full Récupère un échantillon avec toutes ses données associées : isotopes, méthodes, publications, pipeline.

GET /api/samples/isotopic-data Toutes les données isotopiques de la base avec indicateur de normalisation.

GET /api/samples/metadata Métadonnées des échantillons (GPS, projet, dates, description). Dictionnaire indexé par sample_id.

GET /api/samples/stats Statistiques pour le dashboard : total échantillons, avec GPS, éléments uniques, répartition par type de matériau.

POST /api/samples Crée un nouvel échantillon.

Corps : name (str, requis), material_type, sector, collection_date, collection_location, description, classification (source ou fille), latitude, longitude, project.

Le type de matériau et la classification sont normalisés automatiquement. L'identifiant de l'utilisateur courant est associé à l'échantillon en mode multi-utilisateurs.

PUT /api/samples/{sample_id} Remplace complètement un échantillon.

PATCH /api/samples/{sample_id} Mise à jour partielle d'un échantillon (seuls les champs fournis sont modifiés).

DELETE /api/samples/{sample_id} Supprime un échantillon et toutes ses données isotopiques associées.

DELETE /api/samples/{sample_id}/isotope/{isotope_id} Supprime une donnée isotopique individuelle d'un échantillon.

GET /api/samples/{sample_id}/purification-yields Récupère les rendements de purification enregistrés pour un échantillon.

POST /api/samples/{sample_id}/purification-yields Enregistre ou met à jour le rendement de purification d'un élément pour un échantillon.

Corps : {"element": str, "yield_percent": float, "operator": str|null, "method_key": str|null}

Fonctionne par INSERT OR REPLACE : un seul rendement par couple (sample_id, element).

DELETE /api/samples/{sample_id}/purification-yields/{element} Supprime le rendement de purification d'un élément spécifique.

GET /api/samples/export Exporte tous les échantillons en CSV (colonnes : nom, type de matériau, secteur, date, localisation, description, classification, coordonnées GPS, projet).

POST /api/v2/samples/export-batch Exporte plusieurs échantillons avec toutes leurs données (isotopes, méthodes, publications).

Corps : [sample_id, ...], liste d'identifiants.

POST /api/import-csv Import d'un fichier CSV d'échantillons avec résolution intelligente des colonnes.

Corps : multipart/form-data : file (UploadFile), archive_mode (bool, défaut False).

Accepte les en-têtes en français ou en anglais, avec ou sans accents, en majuscules ou minuscules. La résolution est d'abord exacte puis approximative (distance d'édition maximum 2). L'encodage est détecté automatiquement (UTF-8, UTF-8 BOM, Latin-1).

Recherche de correspondances

POST /analyze Lance la recherche de correspondance géographique pour un échantillon de la base.

Corps :

Champ	Type	Défaut	Description
sample_id	int	requis	Identifiant de l'échantillon dans la base.
isotope_data	list	[]	Données isotopiques à utiliser (si vide, utilise celles de la base).
threshold	float	0.85	Seuil de score de correspondance (0 à 1). Distance de Mahalanobis.
algorithm	str	hybrid	Algorithme : hybrid, mahalanobis, bayesian.
classification_filter	str	sources	Filtrer sur sources, filles, ou all.
database_sources	list	["local"]	Bases à interroger : local, archive, community.
same_material	bool	true	Restreindre aux mêmes types de matériaux.

POST /analyze/manual Analyse manuelle avec données isotopiques saisies directement, sans échantillon en base.

Corps : sample_name, material_type, isotope_data (list, requis), threshold (float, défaut 0.75), algorithm. Crée un échantillon temporaire non persisté en base.

POST /api/matching/find/{sample_id} Recherche de correspondances pour un échantillon, version simplifiée.

Params : threshold (float, optionnel) : seuil de correspondance.

POST /api/matching/batch Analyse plusieurs échantillons en une seule requête.

Corps : [sample_id, ...] + threshold (float, optionnel). Retourne un dictionnaire sample_id → résultat avec les erreurs par échantillon isolées.

POST /api/matching/manual Analyse manuelle via l'interface de correspondance (avec sélection d'éléments et de ratios).

POST /api/matching/advanced/{sample_id} Analyse avancée avec paramètres étendus (filtres supplémentaires, sélection multi-base).

GET /api/matching/config Configuration actuelle du moteur de matching (seuils, algorithme par défaut).

Méthodes, pipelines et publications (v2)

GET /api/v2/methods Liste les méthodes de la bibliothèque.

Params : type (str, optionnel), element (str, optionnel) : filtres.

GET /api/v2/methods/{method_id} Récupère une méthode spécifique.

POST /api/v2/methods Crée une nouvelle méthode dans la bibliothèque.

PUT /api/v2/methods/{method_id} Met à jour une méthode.

DELETE /api/v2/methods/{method_id} Supprime une méthode.

GET /api/v2/methods/yield-ranges Plages de rendements acceptables par méthode (utilisées pour la validation des rendements de purification).

GET /api/v2/samples/{sample_id}/methods Méthodes associées à un échantillon.

POST /api/v2/samples/{sample_id}/methods Associe une méthode à un échantillon.

POST /api/v2/samples/methods-batch Associe une méthode à plusieurs échantillons en une seule opération.

DELETE /api/v2/sample-methods/{sm_id} Dissocie une méthode d'un échantillon.

GET /api/v2/publications Liste les publications de la bibliothèque.

GET /api/v2/publications/doi/{doi} Recherche une publication par son DOI.

POST /api/v2/publications Crée une référence bibliographique.

GET /api/v2/pipelines Liste les pipelines d'analyse.

Params : element (str, optionnel) : filtre par élément cible.

GET /api/v2/samples/{sample_id}/pipeline Pipeline associé à un échantillon et sa progression.

PUT /api/v2/sample-pipelines/{sp_id}/progress Met à jour la progression d'une étape de pipeline.

Standards et normalisation isotopique

GET /api/standards Liste tous les standards isotopiques.

POST /api/standards/custom Crée un standard personnalisé.

PUT /api/standards/{standard_id} Met à jour un standard existant.

DELETE /api/standards/{standard_id} Supprime un standard isotopique.

POST /api/samples/{sample_id}/normalize Normalise les données isotopiques d'un échantillon par rapport à un standard de référence.

POST /api/samples/auto-normalize Normalise automatiquement tous les échantillons pour lesquels un shift inter-standard est disponible (standard mesuré + référence configurée + shift calculé).

POST /api/samples/reset-all-normalizations Réinitialise toutes les normalisations appliquées.

POST /api/samples/normalize-materials Normalise les types de matériaux de tous les échantillons.

POST /api/samples/normalize-all-data Normalise en une passe les matériaux, classifications, ratios isotopiques et symboles d'éléments.

CRM et shifts inter-standards

GET /api/crm/list Liste tous les matériaux de référence certifiés (CRM).

GET /api/crm/{crm_id} Récupère un CRM spécifique avec ses concentrations et données isotopiques.

POST /api/crm/add Ajoute un nouveau CRM.

PUT /api/crm/{crm_id}/edit Met à jour les métadonnées d'un CRM.

POST /api/crm/{crm_id}/concentration Ajoute une concentration élémentaire à un CRM.

POST /api/crm/{crm_id}/isotope Ajoute une donnée isotopique à un CRM.

DELETE /api/crm/{crm_id}/concentration/{element} Supprime la concentration d'un élément spécifique d'un CRM.

DELETE /api/crm/{crm_id}/isotope/{ratio} Supprime une donnée isotopique spécifique d'un CRM.

GET /api/crm/statistics Statistiques globales sur les CRM enregistrés.

GET /api/crm/georem/search Recherche dans la base GeoReM en ligne.

POST /api/crm/georem/import/{georem_id}/full Importe complètement un CRM depuis GeoReM (concentrations + isotopes).

POST /api/shifts/calculate/{crm_id} Calcule le shift inter-standard pour un CRM, un élément et un ratio isotopique donnés.

Params : element (str, requis), isotope_ratio (str, requis).

POST /api/shifts/calculate-all Calcule tous les shifts disponibles pour tous les CRM.

POST /api/shifts/convert Convertit une valeur isotopique d'un standard à un autre en appliquant le shift calculé.

GET /api/shifts/history Historique des shifts calculés.

Éléments

GET /api/elements Liste tous les éléments isotopiques de la base (prédéfinis + personnalisés).

GET /api/elements/custom Liste les éléments personnalisés uniquement.

POST /api/elements/custom Crée un élément isotopique personnalisé.

PUT /api/elements/custom/{element_id} Modifie un élément personnalisé.

DELETE /api/elements/custom/{element_id} Supprime un élément personnalisé.

Base de données communautaire

GET /api/community/search Recherche dans la base communautaire en ligne.

Params : query (str), location (str). Requiert un accès réseau actif (bloqué en mode air-gap).

POST /api/community/contribute Contribue un échantillon à la base communautaire. Disponible dès le plan Research.

GET /api/community/stats Statistiques de la base communautaire.

Cartographie

GET /api/tiles/{z}/{x}/{y}.png Proxy de tuiles cartographiques. Sert les tuiles depuis la source configurée (en ligne ou packs locaux en mode air-gap).

GET /api/mapping/export/{sample_id} Export cartographique d'un échantillon.

GET /api/mapping/batch-export Export cartographique groupé de plusieurs échantillons.

Base de données et sauvegarde

GET /api/database/backup Génère et télécharge une sauvegarde de la base de données principale.

POST /api/database/restore Restaure la base de données depuis une sauvegarde.

POST /api/sync Synchronisation manuelle entre les sources de données configurées.

Gestion des utilisateurs

GET /api/users/list Liste tous les comptes utilisateurs (admin uniquement).

POST /api/users/create Crée un nouveau compte utilisateur (admin uniquement).

Corps : username, email, password, role (user, analyst, manager, admin), display_name.

POST /api/users/{user_id}/toggle Active ou désactive un compte utilisateur.

POST /api/users/{user_id}/unlock Déverrouille un compte bloqué après trop de tentatives échouées.

DELETE /api/users/{user_id} Supprime un compte utilisateur (admin uniquement, pas sur son propre compte).

PUT /api/user/profile Met à jour le profil de l'utilisateur connecté (nom d'affichage, email).

Journaux et logs

GET /api/logs/activity Journal d'activité des utilisateurs (connexions, actions, exports).

GET /api/logs/export Exporte les logs d'activité en CSV.

Zones géographiques et statistiques

GET /api/zones Liste les zones géographiques de référence utilisées dans la recherche de correspondances.

GET /api/stats Statistiques globales de la base (échantillons, éléments, zones, correspondances calculées).

Configuration

GET /api/config/language Langue d'interface actuelle.

POST /api/config/language Change la langue d'interface.

Corps : {"language": "fr"|"en"}

GET /api/updates/check Vérifie la disponibilité d'une mise à jour. Requiert un accès réseau (bloqué en mode air-gap).

POST /api/shutdown Arrête proprement le backend FastAPI. Appelé par Tauri à la fermeture du logiciel.