IsoFind API

IsoFind exposes a local REST API served by FastAPI on http://127.0.0.1:8001. It is used by the Tauri frontend and can be queried directly by scripts or third-party tools to automate operations on analytical data. This page documents the 489 routes exposed by the backend.

General Information

All routes return JSON unless otherwise specified (CSV exports, PNG images, PDF files). Error responses follow the standard FastAPI format: {"detail": "error message"} with the corresponding HTTP status code. In multi-user mode, routes that modify data require a valid session cookie.

Interactive Swagger documentation is available at http://127.0.0.1:8001/docs while IsoFind is running. It lists every route with its complete data schema and allows direct testing.

Data Compartmentalization

Since version 1.1, most routes apply a visibility filter. A non-administrator user only sees the samples they own, those that have been shared with them, and those marked public. Child tables (geochemistry, molecules, physicochemistry, isotopes) inherit this filter implicitly, through the already restricted list of identifiers. Identifiers that are not visible but supplied by a client are silently dropped rather than raising an error, so that nothing is revealed about their existence.

Bulk destructive operations and global maintenance operations (global normalizations, purging of training data, resetting all normalizations) are restricted to administrators.

The API listens on 127.0.0.1 (localhost) only. It is not reachable from the local network unless explicitly configured. For multi-workstation intranet use, refer to the network deployment documentation.
Some routes under the /api/licence prefix also have an English-spelled alias under /api/license. Both forms are strictly equivalent.

Contents

Sections

System, Security and Startup

GET /api/ready Indicates whether backend startup has fully completed. The frontend shows a loader while ready=false.
GET /health Backend health check.
GET /api/version/info Version, installation mode, build date and enabled features.
GET /api/system/mode System operating mode: single_user or multi_user.
GET /api/system/config System configuration. Admin only.
GET /api/system/stats System statistics: active users, sessions, database state. Admin only.
GET /api/system/protection Protection status of the frontend assets (encrypted templates and scripts).
GET /api/installation/mode Installation mode detected at startup.
GET /api/network-mode Current network mode: standard or airgap. The frontend uses it to disable network-dependent features.
GET /api/trial-status Compatibility endpoint for the legacy trial system. IsoFind no longer has a trial period.
GET /api/debug/modules Diagnostic of the load state of critical modules.
POST /api/shutdown Cleanly stops the FastAPI server. Called by Tauri when the application closes.
GET /api/updates/check Checks for update availability. Requires network access, blocked in air-gap mode.
GET /api/updates/current Returns the currently installed version.
GET /api/config/language Interface language configured in config.json.
POST /api/config/language Changes the interface language.

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

POST /api/sync Synchronization between configured data sources.

Local Token and Third-party API Access

GET /api/local/token Entry point for local Python clients. The flow depends on the configured api_access mode: open, manual confirmation, or refusal.
GET /api/local/pending-authorizations Lists pending authorization requests. Feeds the Tauri confirmation window.
POST /api/local/authorize-client Approves or refuses a pending authorization request.
GET /api/local/api-access-config Current configuration of the API access control.
POST /api/local/api-access-config Changes the api_access mode. Called from the IsoFind preferences.
DELETE /api/local/authorized-client/{client_id} Revokes the authorization of a registered client.
GET /api/security/token Indicates whether a security token is required, without ever revealing its value.
POST /api/security/bind-session-cookie Sets the isofind_token cookie, mirroring the security token. Required for navigations triggered by an <a href> tag.

Authentication and Sessions

The recovery routes are deliberately public. The recovery code is the sole authentication factor: it must be kept offline, exactly as an encryption key would be.
POST /api/auth/login User authentication (multi-user mode).

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

Returns: {"success": bool, "user": {...}} and a session cookie. In single-user mode, always accepted.

POST /api/auth/logout Logout and session invalidation.
GET /api/auth/check Canonical session check: reads the user set by the authentication middleware.
POST /api/auth/lock Locks the current session and invalidates the cookie server-side.
GET /api/auth/sessions Lists the active sessions of the current user (multi-user only).
DELETE /api/auth/sessions/{session_id} Terminates a specific session.
POST /api/auth/change-password Changes the password of the logged-in user.

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

GET /api/auth/first-launch Returns the temporary admin password if the account was just created. Single call: the value is wiped from memory afterwards.
GET /api/auth/recovery-code-status Indicates whether an active recovery code is configured. Public route, reveals nothing sensitive.
POST /api/auth/recovery/generate-initial Generates the initial recovery code on first startup. Public route, protected by the temporary admin password.
POST /api/auth/recovery/generate Generates a new recovery code (authenticated admin). The plaintext code is returned only once.
POST /api/auth/generate-recovery-code Variant called from the preferences panel. Only the PBKDF2 hash of the code is persisted.
POST /api/auth/recovery Resets the admin password via the recovery code. Public route: the code serves as authentication.

Body: {"recovery_code": str, "new_password": str}. Single use.

User Management

GET /api/users/list Lists all user accounts. Admin only.
POST /api/users/create Creates a user account. Admin only.

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

POST /api/users/{user_id}/toggle Activates or deactivates a user account.
POST /api/users/{user_id}/unlock Unlocks an account blocked after too many failed attempts. Resets failed_attempts and locked_until.
DELETE /api/users/{user_id} Deletes a user account. An administrator cannot delete their own account.
PUT /api/user/profile Updates the profile of the logged-in user (display name, email).
GET /api/logs/activity Activity log: logins, actions, exports. Admin only.
GET /api/logs/export Exports the activity log to CSV. Admin only.

Database Protection and Encryption

GET /api/database-protection/status Protection state of the database. Flat response consumed by the frontend to render the padlock.
GET /api/database-protection/lock-status Lightweight endpoint for the unlock splash: four fields are enough to decide whether to show the modal.
GET /api/database-protection/icon Condensed state for status-bar widgets: green padlock (protected) or grey.
POST /api/database-protection/enable Enables protection at the requested level. For the encrypted level: creates the keystore with a random MEK and generates a BIP39 recovery key.
POST /api/database-protection/unlock Unlocks the session: password verification, key derivation, replay of the ISOF integrity verifier.
POST /api/database-protection/lock Locks the current session. Idempotent.
POST /api/database-protection/verify Verifies a protection password without changing the lock state.
POST /api/database-protection/unlock-with-recovery Unlocks via the BIP39 recovery key when the password is lost. Forces a new master password to be set.
POST /api/database-protection/regenerate-recovery Regenerates a BIP39 recovery key. The previous one is invalidated. The master password is required.
POST /api/database-protection/change-master-password Changes the master password of the encrypted database. Distinct from /api/auth/change-password, which concerns the user password.
GET /api/integrity-seal/status Status of the integrity seal over the ISOF provenance columns. Valid means no external modification has been detected since the last import.
POST /api/integrity-seal/reseal Reseals the fingerprint of the ISOF provenance columns. Called automatically after a successful import.
GET /api/refs/integrity-status Integrity state of the reference databases: fractionation_database, isotopes_reference, molecules_reference.
POST /api/refs/import Receives a reference .db file, verifies its ECDSA signature from the IsoFind Issuing CA, then installs it.

Backup and Restore

GET /api/database/backup Downloads a binary copy of the active database. For a SQLCipher database, the downloaded file remains encrypted.
GET /api/database/backup/info Metadata of available backups and protection state.
POST /api/database/restore Restores a backed-up database. Direct binary write for a plaintext database.
POST /api/database/backup/encrypted Creates an AES-256-GCM encrypted backup in backups/.

Body: {"password": "master_password"}

POST /api/database/restore/encrypted Restores a .protected.bak backup. Decryption happens in memory server-side: the plaintext never transits.

Samples

All read routes on samples apply compartmentalization: a non-administrator user only sees their own samples, those shared with them, and those marked public.
GET /api/samples Full list of samples with their isotopic data.

Params: limit (int), sort (asc or desc, by creation date). Default: descending identifier.

GET /api/samples/{sample_id} Retrieves a specific sample with its isotopic data. Returns 404 if the identifier does not exist.
POST /api/samples Creates a new sample with its isotopic data.

Body: name (required), material_type, sector, collection_date, collection_location, description, classification (source or daughter), latitude, longitude, project.

Material type and classification are normalized automatically. In multi-user mode, owner_id is the current user and visibility defaults to private.

PUT /api/samples/{sample_id} Fully replaces a sample. Owner or administrator only.
PATCH /api/samples/{sample_id} Partial update: only the provided fields are modified.
DELETE /api/samples/{sample_id} Deletes a sample and all its associated isotopic data.
DELETE /api/samples/{sample_id}/isotope/{isotope_id} Deletes an individual isotopic data point.
GET /api/samples/{sample_id}/isotopes Isotopic data of a sample.
GET /api/samples/{sample_id}/isotope-values Isotopic values of a sample, in the format expected by the calculation modules.
GET /api/samples/{sample_id}/isotope-debug Raw isotope_data rows with the detail of ratio_value against normalized_value. Diagnostic use.
GET /api/samples/{sample_id}/depth-profile Depth points associated with a sample (vertical profile).
GET /api/samples/{sample_id}/audit Traceability history of a sample.

Params: limit (int).

POST /api/samples/{sample_id}/audit Records an audit entry on a sample.
GET /api/samples/isotopic-data All isotopic data in the database, with a normalization indicator.
GET /api/samples/metadata Sample metadata indexed by sample_id, mergeable client-side.
GET /api/samples/stats Scientific dashboard statistics: total, georeferenced samples, unique elements, breakdown by material.
GET /api/samples/family-distribution Aggregated distribution of measurements by data family.
GET /api/samples/integrity ISOF provenance and integrity information per sample.
POST /api/samples/check-existing Pre-check of sample name uniqueness, before submitting an import.
POST /api/samples/count Counts samples before loading, so the frontend can size its pagination.
GET /api/spreadsheet/samples Endpoint dedicated to the spreadsheet: returns every isotopic data field, including collection_date, sample_type and standard_used.

Purification Yields

GET /api/samples/{sample_id}/purification-yields Purification yields recorded for a sample.
POST /api/samples/{sample_id}/purification-yields Records or replaces the yield of an element for a sample.

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

Uses INSERT OR REPLACE: a single yield per (sample_id, element) pair.

DELETE /api/samples/{sample_id}/purification-yields/{element} Deletes the yield of an element for a sample.
GET /api/v2/methods/yield-ranges Expected yield ranges for an element, read from the protocol_json of purification or separation methods.

Params: element (str).

Sample Import and Export

POST /api/import-csv CSV import with semantic column resolution.

Body: multipart/form-data: file, archive_mode (bool), standard_aliases, skip_existing.

Accepts headers in French or English, with or without accents, in upper or lower case. Resolution is exact first, then approximate (maximum edit distance of 2). Encoding is detected automatically (UTF-8, UTF-8 BOM, Latin-1).

POST /api/csv/preview-excel Server-side pre-parsing of an Excel file, for frontend modules that do not embed SheetJS.
GET /api/samples/export Exports the visible samples to CSV.
GET /api/v2/samples/{sample_id}/full Complete sample: isotopes, methods, publications, pipeline.
POST /api/v2/samples/export-batch Exports several samples with all their associated data.

Body: [sample_id, ...]

Match Analysis

POST /analyze Runs the geographic matching search for a sample in the database.

Body:

FieldTypeDefaultDescription
sample_idintrequiredIdentifier of the sample in the database.
isotope_datalist[]Isotopic data to use. If empty, the database values are taken.
thresholdfloat0.85Match score threshold, between 0 and 1. Mahalanobis distance.
algorithmstrhybridhybrid, mahalanobis or bayesian.
classification_filterstrsourcessources, daughters or all.
database_sourceslist["local"]local, archive, community.
same_materialbooltrueRestrict to identical material types.
POST /analyze/manual Analysis from isotopic data entered directly, without a database sample. Creates a temporary, non-persisted sample.

Body: sample_name, material_type, isotope_data (required), threshold (default 0.75), algorithm.

POST /analyze/map Analysis and generation of the match map in a single request.
POST /analyze/archives Variant of /analyze that searches archives only. Same parameters.
POST /analyze/manual/archives Variant of /analyze/manual restricted to visible archives.
POST /api/matching/find/{sample_id} Match search for a sample, simplified version.

Params: threshold (float).

POST /api/matching/batch Analyzes several samples in one request. Returns a dictionary from sample_id to result, with errors isolated per sample.
POST /api/matching/manual Manual analysis from the matching interface, with element and ratio selection.
POST /api/matching/advanced/{sample_id} Advanced analysis with an explicit algorithm choice.

Params: algorithm, threshold, sigma_multiplier.

GET /api/matching/compare/{sample_id} Compares the results of every algorithm for the same sample.
GET /api/matching/config Current configuration of the matching engine: thresholds, default algorithm.

Methods, Pipelines and Publications (v2)

GET /api/v2/methods Lists the methods in the library.

Params: type, element.

GET /api/v2/methods/{method_id} Retrieves a method by its identifier.
POST /api/v2/methods Creates a method.
PUT /api/v2/methods/{method_id} Updates a method.
DELETE /api/v2/methods/{method_id} Deletes a method.
GET /api/v2/methods/{method_id}/samples Identifiers of the samples this method is assigned to.
GET /api/v2/samples/{sample_id}/methods Methods applied to a sample.
POST /api/v2/samples/{sample_id}/methods Associates a method with a sample.
POST /api/v2/samples/methods-batch Methods assigned across a list of samples.

Body: {"sample_ids": [...]}

POST /api/v2/samples/assign-method-batch Assigns a method to several samples at once.

Body: sample_ids, method_id, method_type, method_name, element, parameters_json.

DELETE /api/v2/sample-methods/{sm_id} Dissociates a method from a sample.
GET /api/v2/publications Lists publications.

Params: year, category.

GET /api/v2/publications/{pub_id} Retrieves a publication by its identifier.
GET /api/v2/publications/doi/{doi} Retrieves a publication by its DOI. The DOI is accepted as-is, slashes included.
POST /api/v2/publications Creates a bibliographic reference.
PUT /api/v2/publications/{pub_id} Updates a publication.
DELETE /api/v2/publications/{pub_id} Deletes a publication.
GET /api/v2/samples/{sample_id}/publications Publications linked to a sample.
POST /api/v2/samples/{sample_id}/publications Links a publication to a sample.
DELETE /api/v2/sample-publications/{sp_id} Removes a sample-to-publication link.
GET /api/v2/pipelines Lists analysis pipelines.

Params: element.

GET /api/v2/pipelines/{pipeline_id} Detailed pipeline with its methods.
POST /api/v2/pipelines Creates a pipeline.
DELETE /api/v2/pipelines/{pipeline_id} Deletes a pipeline.
GET /api/v2/samples/{sample_id}/pipeline Active pipeline of a sample and its progression.
POST /api/v2/samples/{sample_id}/pipeline Assigns a pipeline to a sample.
PUT /api/v2/sample-pipelines/{sp_id}/progress Updates the progression of a pipeline stage.

Params: current_stage, status.

Standards and Isotopic Normalization

GET /api/standards Lists isotopic standards.

Params: element.

POST /api/standards/custom Creates a custom standard.
PUT /api/standards/{standard_id} Updates a standard.
DELETE /api/standards/{standard_id} Deletes a standard.
POST /api/samples/{sample_id}/normalize Persists the normalized values of a sample into the database.
POST /api/samples/{sample_id}/reset-normalization Cancels the normalization of a sample.
POST /api/samples/auto-normalize Automatically normalizes every sample for which an inter-standard shift is available. Global operation, admin only.
POST /api/samples/check-normalization Determines which samples can be normalized, without applying anything.
POST /api/samples/reset-all-normalizations Resets all normalizations. Admin only.
POST /api/samples/normalize-materials Normalizes existing material types. Maintenance operation, admin only.
POST /api/samples/normalize-classifications Normalizes existing classifications. Admin only.
POST /api/samples/normalize-all-data Normalizes materials, classifications, isotopic ratios and element symbols in a single pass. Admin only.

Elements

GET /api/elements Lists all isotopic elements, predefined and custom.
GET /api/elements/custom Lists custom elements only.
POST /api/elements/custom Creates a custom isotopic element.
PUT /api/elements/custom/{element_id} Modifies a custom element.
DELETE /api/elements/custom/{element_id} Deletes a custom element.
GET /api/zones Reference geographic zones used by the matching search.
GET /api/stats Global dashboard statistics: samples, elements, zones, computed matches.

Certified Reference Materials

GET /api/crm/list Lists all certified reference materials.
GET /api/crm/{crm_id} Retrieves a CRM with its concentrations and isotopic data.
GET /api/crm/statistics Global statistics of the CRM database.
POST /api/crm/add Adds a CRM.
PUT /api/crm/{crm_id}/update Updates a CRM.
PUT /api/crm/{crm_id}/edit Edits a CRM: adds or modifies concentrations and isotopes in one request.
DELETE /api/crm/{crm_id}/delete Deletes a CRM.
DELETE /api/crm/{crm_id} Deletes a CRM. Short-URL variant, identical behaviour.
POST /api/crm/{crm_id}/concentration Adds or updates the concentration of an element in a CRM.
POST /api/crm/{crm_id}/isotope Adds or updates an isotopic ratio in a CRM.
DELETE /api/crm/{crm_id}/concentration/{element} Deletes the concentration of an element.
DELETE /api/crm/{crm_id}/isotope/{ratio} Deletes an isotopic ratio.
GET /api/crm/export/database Downloads the complete CRM database.
GET /api/crm/export/json Exports the CRMs to JSON.
POST /api/crm/import/database Imports a CRM database with merging.

Params: strategy: merge strategy on duplicates.

POST /api/crm/import/preview Previews the contents of a CRM import without applying it.

Analyzed CRMs and Inter-standard Shifts

GET /api/crm-analyzed/list Lists analyzed CRMs with their statistics.
GET /api/crm-analyzed/{crm_analysis_id} Retrieves an analyzed CRM with all its measured values.
POST /api/crm-analyzed/create Creates an analyzed CRM with its values.
PUT /api/crm-analyzed/{crm_analysis_id} Updates the information of an analyzed CRM.
DELETE /api/crm-analyzed/{crm_analysis_id} Deletes an analyzed CRM. Cascades over values, associations and shifts.
POST /api/crm-analyzed/{crm_analysis_id}/add-value Adds a measured value to an analyzed CRM.
DELETE /api/crm-analyzed/value/{value_id} Deletes a measured value.
GET /api/crm-analyzed/robustness-score Global robustness score of the calibration campaign.
GET /api/crm-analyzed/robustness-by-element Robustness score broken down by element.
POST /api/crm-analyzed/recalculate-scores Recomputes the scores of all existing analyzed CRMs.
POST /api/crm-analyzed/associate-samples Associates samples with an analyzed CRM.
POST /api/crm-analyzed/auto-associate Automatically associates samples by analysis date range.
DELETE /api/crm-analyzed/disassociate/{sample_id}/{crm_id} Removes a sample-to-CRM association.
GET /api/crm-analyzed/sample/{sample_id}/crms CRMs associated with a sample.
POST /api/crm-analyzed/{crm_analysis_id}/calculate-shifts Computes isotopic shifts between standards for a single CRM, comparing analyses performed against different standards.
POST /api/crm-analyzed/calculate-all-shifts Computes all inter-standard shifts, grouping by CRM name and processing each pair of standards.
GET /api/crm-analyzed/shifts/active Lists the active shifts derived from analyzed CRMs.
POST /api/crm-analyzed/shift/{shift_id}/toggle-active Activates or deactivates a shift.
POST /api/crm-analyzed/import-csv Imports analyzed CRMs from a CSV file.

Format: crm_id, crm_name, session_name, analysis_date, instrument, standard_used, element, isotope_ratio, measured_value, uncertainty

GET /api/crm-analyzed/export-csv Exports all analyzed CRMs to CSV.
POST /api/shifts/calculate/{crm_id} Computes inter-standard shifts by analyzing every measurement of a CRM.

Params: element (required), isotope_ratio (required).

POST /api/shifts/calculate-all Computes shifts for every CRM measured against several standards.
GET /api/shifts/get Retrieves a shift between two standards.

Params: element, isotope_ratio, standard_from, standard_to.

GET /api/shifts/list Lists all computed shifts, with optional filters.
POST /api/shifts/convert Converts an isotopic value from one standard to another by applying the appropriate shift.

Params: value, element, isotope_ratio, standard_from, standard_to.

GET /api/shifts/statistics Statistics on the computed shifts.
GET /api/shifts/history History of shift computations.

Params: limit (int).

GeoReM Integration

The GeoReM routes issue outbound requests to an online service. They are unavailable in air-gap mode.
GET /api/crm/georem/search Searches for a reference material in GeoReM.

Params: q: material name.

GET /api/crm/georem/preview/{georem_id} Previews the data that would be imported from GeoReM.
POST /api/crm/georem/import/{georem_id} Imports a CRM from GeoReM.
POST /api/crm/georem/import/{georem_id}/full Imports a CRM from GeoReM with the full set of extracted data.

Params: user_notes.

GET /api/georem/search GeoReM search, short-URL variant.
GET /api/georem/preview Previews the GeoReM data available for a material, without importing.

Params: material_name.

GET /api/georem/search-isotopes Searches the isotopic data of a material on GeoReM.

Example: /api/georem/search-isotopes?material_name=GXR-4

POST /api/georem/import-complete Full import from GeoReM: concentrations and isotopes.
POST /api/georem/import/{sample_name} Full import by material name. Automatically converts epsilon to delta and identifies the isotopic ratios.
GET /api/georem/test/{sample_name} Diagnostic route: returns the raw HTML returned by GeoReM.

Inorganic Geochemistry

GET /api/samples/{sample_id}/geochem All concentrations of a sample, sorted by element.
GET /api/samples/{sample_id}/geochem/{geochem_id} A specific geochemical entry.
POST /api/samples/{sample_id}/geochem Adds a concentration.
POST /api/samples/{sample_id}/geochem/batch Inserts a batch of concentrations in a single transaction.

remplacer=true first deletes the elements concerned, which allows a CSV import to be replayed cleanly.

PATCH /api/samples/{sample_id}/geochem/{geochem_id} Partial update of an entry.
DELETE /api/samples/{sample_id}/geochem/{geochem_id} Deletes a geochemical entry. Owner or administrator only.
DELETE /api/samples/{sample_id}/geochem Deletes all concentrations of a sample. Bulk destructive action, recorded in the audit trail.

Physicochemistry

GET /api/samples/{sample_id}/physicochemistry All physicochemical measurements of a sample.
GET /api/samples/{sample_id}/physicochemistry/nexus-conditions Physicochemical conditions formatted for the Nexus Conditions card (GeochemicalConditions object).
POST /api/samples/{sample_id}/physicochemistry Adds or replaces a measurement. The UNIQUE(sample_id, parameter) constraint guarantees a single value per parameter.
POST /api/samples/{sample_id}/physicochemistry/batch Upsert of a batch of measurements in a single transaction.
PATCH /api/samples/{sample_id}/physicochemistry/{parameter} Partial update by parameter name.
DELETE /api/samples/{sample_id}/physicochemistry/{parameter} Deletes a physicochemical parameter.
DELETE /api/samples/{sample_id}/physicochemistry Deletes all physicochemical measurements of a sample.

Molecules: User Catalogue

GET /api/molecules/catalogue Paginated list of molecules in the user catalogue.

Params: famille (exact filter, for example PFAS), actif, page, page_size, include_geochemical, q (free-text search).

GET /api/molecules/catalogue/familles Families present in the user catalogue.
GET /api/molecules/catalogue/{molecule_id} Details of a catalogue molecule.
POST /api/molecules/catalogue Creates a molecule in the user catalogue.
PATCH /api/molecules/catalogue/{molecule_id} Partial update of a molecule.
DELETE /api/molecules/catalogue/{molecule_id} Deletes a molecule.

Params: archiver (bool): archives instead of deleting.

POST /api/molecules/catalogue/seed/{famille} Inserts the predefined molecules of a family. CAS duplicates are skipped.
GET /api/molecules/catalogue/seed/familles Families available in the seed, with the required licence tier.

Molecules: Measurements and Compliance

GET /api/molecules/mesures-all All measurements across all samples in a single request.

Params: page, page_size, include_geochemical, famille, sample_ids.

GET /api/molecules/{sample_id}/mesures Molecular measurements of a sample.
GET /api/molecules/{sample_id}/mesures/{mesure_id} A specific measurement.
POST /api/molecules/{sample_id}/mesures Adds a measurement.
POST /api/molecules/{sample_id}/mesures/batch Adds a batch of measurements in a single transaction.
PATCH /api/molecules/{sample_id}/mesures/{mesure_id} Partial update of a measurement.
DELETE /api/molecules/{sample_id}/mesures/{mesure_id} Deletes a measurement.
DELETE /api/molecules/{sample_id}/mesures Deletes all measurements of a sample.
POST /api/molecules/recalculer-conformite Recomputes conforme, seuil_ref and seuil_ref_unit for every measurement whose catalogued molecule had its threshold changed.
POST /api/molecules/recalculer-conformite/{molecule_id} Recomputes compliance for a single molecule. To be called after a PATCH on the catalogue.
GET /api/molecules/{sample_id}/conformite Compliance summary of a sample, by family and by molecule: exceedances, compliant, untested.
GET /api/molecules/stats/global Global molecular statistics.
GET /api/molecules/stats/par-sample/{sample_id} Molecular statistics of a sample.

Molecules: Reference Database

GET /api/molecules/reference/catalogue Molecules from the reference database.

Params: famille (PFAS, Pesticides, PAH...), niveau_acces (gratuit, pro, defense), q, limit.

GET /api/molecules/reference/familles Families in the reference database, with counts and access tiers.
GET /api/molecules/reference/{ref_id} A molecule from the reference database.
GET /api/molecules/reference/{ref_id}/isotopes Isotopic links of a reference molecule.
POST /api/molecules/reference/{ref_id}/importer Copies a reference molecule into the user catalogue. CAS duplicates are skipped.
POST /api/molecules/reference/importer-batch Imports several reference molecules. Returns the outcome of each import: new, already present, or error.
GET /api/molecules/{sample_id}/isotopic-links Cross-references the detected molecule families with the isotopic elements relevant to origin attribution. Requires data in isotope_data.
GET /api/molecules/ref-isotopes Molecule-to-isotope links from the reference table.

Params: famille, element.

POST /api/molecules/ref-isotopes/seed Inserts the reference molecule-to-isotope links. Duplicates on CAS plus ratio are skipped.
GET /api/molecules/ref-isotopes/v2 Enriched isotopic links: value ranges, discrimination score, feasibility.

Params: famille, element, faisabilite, min_discrimination. Falls back to static data if the table is empty.

POST /api/molecules/ref-isotopes/seed-v2 Inserts the enriched entries of ref_molecules_isotopes_v2.
GET /api/molecules/ref-isotopes/sample/{sample_id} Cross-references the families detected in a sample with the reference table to identify exploitable links.
GET /api/molecules/ref-isotopes/suggest/{sample_id} Prioritized recommendations for complementary analyses, derived from the molecules and isotopic signatures present.

CSIA: Compound-Specific Isotope Analysis

GET /api/molecules/csia/list Molecules with CSIA data usable by the Nexus.
GET /api/molecules/csia/{molecule_name}/pathways Documented degradation pathways for a molecule.
POST /api/molecules/csia/resolve Full resolution of a molecule and pathway: epsilon, mode, metabolites, references, and every multi-element fractionation for the same pathway.
POST /api/molecules/csia/dual Dual-isotope resolution for a pair of elements (C/Cl, C/N...). Returns both epsilons and the Lambda slope, diagnostic of the mechanism.

Isotopic Fractionations

GET /api/fractionation/summary Summary aggregated by process type. Used by the Process Library.
GET /api/fractionation/list Paginated list with filters.

Params: page, per_page, element, process_type, material, search, sort_by, sort_order.

GET /api/fractionation/elements Elements available in the fractionation database.
GET /api/fractionation/process-types Available process types.
GET /api/fractionation/materials Available materials, optionally filtered by process type.
GET /api/fractionation/stats/overview General statistics of the fractionation database.
GET /api/fractionation/{entry_id} A fractionation entry.
POST /api/fractionation/ Creates a fractionation entry.
POST /api/fractionation/experimental Creates entries from experimental data: several measurement points, with fractionation values computed automatically.
PUT /api/fractionation/{entry_id} Updates an entry.
DELETE /api/fractionation/{entry_id} Deletes an entry.
GET /api/fractionation/export/json Exports the data to JSON.

Params: element, process_type.

GET /api/fractionation/export/csv Exports the data to CSV.
POST /api/fractionation/import/json Imports data from a JSON file.

Kinetic Fractionation

GET /api/kinetic-fractionation/health Module health check.
POST /api/kinetic-fractionation/compute Computes kinetic fractionation. Kinetic entries (equilibrium_reached = 0) are searched first, with a fallback on unspecified data.
GET /api/kinetic-fractionation/search Searches for a kinetic epsilon in the database.

Params: element, process_type, mineral.

GET /api/kinetic-fractionation/database/kinetic Lists all kinetic entries.
GET /api/kinetic-fractionation/database/all Lists all entries with their type: equilibrium, kinetic, or unspecified.

Nexus: Health, Sessions and Workflows

GET /api/nexus/health State of the Nexus engine.
GET /api/nexus/statistics Statistics of the Nexus database.
POST /api/nexus/sessions/save Saves a complete Nexus session: workflow, computation results and matches, for later inclusion in a report.
GET /api/nexus/sessions/list Lists the fifty most recent sessions, enriched with the molecule and total delta.
GET /api/nexus/sessions/{session_id} Loads a complete Nexus session.
DELETE /api/nexus/sessions/{session_id} Deletes a Nexus session.
GET /api/nexus/workflows/list Lists saved workflows.
GET /api/nexus/workflows/{workflow_id} Loads a workflow.
POST /api/nexus/workflows/save Saves a workflow.
DELETE /api/nexus/workflows/{workflow_id} Deletes a workflow.
GET /api/nexus/workflows/autosave Retrieves the latest autosave, stored in the reserved __autosave__ slot.
POST /api/nexus/workflows/autosave Upsert of the autosave slot.
POST /api/nexus/execute Main frontend route: transforms the nodes and connections representation into a workflow analysis.
POST /api/nexus/validate Validates a workflow before execution.
POST /api/nexus/analyze_workflow Full workflow analysis: ML layers 1 and 2, database lookup, composite scoring.
GET /api/nexus/templates/list Predefined workflow templates.
GET /api/nexus/templates/{template_id} Loads a predefined template.

Nexus: Isotopic Computation and Hybrid Pipeline

POST /api/nexus/calculate_isotopic_chain Full isotopic computation with contextualisation. Supports forward and inverse modes.
POST /api/fourier/calculate Fractionation computation via ML and Fourier transform. Legacy endpoint, kept for compatibility.
POST /api/ml/analyze Chemical analysis by ML. Legacy endpoint: prefer /api/nexus/predict_speciation.
GET /api/nexus/hybrid/status Availability of the hybrid pipeline.
POST /api/nexus/hybrid/forward Hybrid forward pipeline, by operator splitting: source signature, linear FFT component, then Rayleigh.
POST /api/nexus/hybrid/inverse Hybrid inverse pipeline. Requires delta_source to estimate the residual fraction.
POST /api/nexus/hybrid/analyze Full hybrid analysis: processes and parameters are extracted automatically from the workflow.
GET /api/nexus/process-diagnostics/{workflow_id} Detailed process diagnostics for a workflow, notably for each Rayleigh stage.
POST /api/nexus/identify-processes Identifies the geochemical processes between two connected signatures.
POST /api/nexus/identify-processes-multi Multi-process identification by iterative chaining, via automatic contextualisation.
POST /api/nexus/auto-contextualise Iterative automatic contextualisation from an initial signature and a geochemical context.

Nexus: Speciation and Machine Learning

GET /api/nexus/ml_status State of the embedded ML models.
POST /api/nexus/predict_speciation Predicts speciation (ML layer 1). All supported elements.
POST /api/nexus/predict_adsorption Predicts adsorption favourability (ML layer 2).
POST /api/nexus/predict_workflow ML prediction applied to a complete workflow.
POST /api/nexus/analyze-speciation Detailed speciation of a sample: species, concentrations and percentages.
POST /api/nexus/compare-speciation Compares source and product speciation: oxidation state changes, concentrations, species.
POST /api/nexus/analyze-csv-speciation Analyzes speciation from an uploaded CSV file.

Params: file, element.

POST /api/nexus/query_database Queries the fractionation database.

Nexus: Quick Detection and Provenance

GET /api/nexus/samples/search Sample search for the Database Sample card.

Params: q, element, material_type, limit.

POST /api/nexus/db-match Matches within the database, for the Database Match card.
POST /api/nexus/scoring-composite Composite scoring: match of the signature against the database and mixture detection.
POST /api/nexus/search-origin Searches the geographic origin of a sample from its isotopic signature.
GET /api/nexus/quick-match/templates Available transformation templates. Filtered by licence tier.
GET /api/nexus/quick-match/csia-templates/{molecule_name} Exposes the documented CSIA pathways of a molecule as dynamic Quick Match templates, each pathway producing a pre-filled step.

Params: element.

POST /api/nexus/quick-match Quick match with fractionation applied, in two stages.
POST /api/nexus/quick-match-archives Same, but against the archive tables.
POST /api/nexus/traceability Provenance search by inversion of the industrial process, using the fractionation database.
POST /api/nexus/traceability-archives Same inversion logic, applied to the archives.
POST /api/nexus/unmix Multi-source isotopic unmixing, by solving a constrained problem.
POST /api/nexus/authenticity-check Composite authenticity score, between 0 and 1, by comparison with the reference library.
POST /api/nexus/authenticity-check-archives Variant querying archive_samples and archive_isotope_data.
GET /api/nexus/sample-series Dated isotopic measurements of a sample, for temporal monitoring.

Params: sample_id, element, isotope_ratio.

POST /api/nexus/monitor-series Analysis of an isotopic time series: trend, breakpoints, drift.

Molecular Nexus

POST /api/nexus/molecular/degradation-chain Propagates an isotopic signature along a multi-step degradation chain (kinetic Rayleigh, CSIA). Each step carries its own isotope, epsilon and residual fraction.
POST /api/nexus/molecular/molecular-traceability Inverse reconstruction of the source signature of an organic contaminant, by inverse Rayleigh: delta_0 = delta_residue - epsilon * ln(f). Uncertainty is propagated at each step upstream.
POST /api/nexus/molecular/degradation-extent Estimates the degradation extent by CSIA inversion: f = exp((delta_sample - delta_source) / epsilon), degradation being (1 - f) * 100.
GET /api/nexus/molecular/epsilon-database Available CSIA epsilons. Without a parameter, the whole database.

Params: process_type.

GET /api/nexus/molecular/sample-geochem/{sample_id} Concentrations from sample_geochem for a sample.

Prediction and Simulation

POST /api/predict/prior Coupled geochemical prior: two end-member mixing, Rayleigh distillation with epsilon taken from the fractionation database or from the literature.
POST /api/predict/train Trains the residual multilayer perceptron (residual = observed - prior) for an element.
POST /api/predict/infer Prior corrected by the residual model.
GET /api/predict/model-status State of the trained residual models.
POST /api/predict/temporal Isotopic temporal extrapolation.
POST /api/predict/temporal/train-lstm Trains the temporal LSTM on the available campaigns.
GET /api/predict/lithology-templates Catalogue of lithological templates, each providing the [min, max, typical] ranges of the hydrogeochemical parameters and the bibliographic references.
GET /api/predict/nexus-processes Nexus processes available for an element, with the number of entries in the database.

Params: element.

POST /api/predict/simulate Simulates the evolution of a geochemical plume from a source point.
GET /api/predict/simulate/molecules Molecules with transport properties available.
GET /api/predict/csia/molecules Molecules with CSIA data usable for isotopic simulation.
GET /api/predict/csia/pathways Documented degradation pathways for a molecule.

Params: molecule.

GET /api/predict/csia/dual Dual CSIA resolution: isotope pair (C/Cl, C/N, C/H) and Lambda slope, diagnostic of the mechanism.

Params: molecule, pathway, primary, secondary.

GET /api/predict/info Available models and their parameters.

Signature Reconstruction (IsoSupply)

POST /api/reconstruction/forward Propagates an initial signature through the industrial chain. Simulation mode: starting from X, the outgoing metal is Y.
POST /api/reconstruction/inverse Reconstructs the origin signature from the final signature.

Params: method: analytical (default, instantaneous and scientifically defensible) or stochastic methods.

POST /api/reconstruction/match Compares an observed signature with the deposits in the database. Adaptive behaviour depending on compatibility at the 95 % confidence interval.
POST /api/reconstruction/full Complete pipeline, inversion then matching. The main IsoSupply endpoint.
GET /api/reconstruction/methods Supported inversion methods.
GET /api/reconstruction/catalog/{element} Documented industrial processes for an element.
GET /api/reconstruction/deposits/search Deposit search by partial name.

Params: element (required), q (name fragment, case-insensitive).

GET /api/reconstruction/deposit/{deposit_id} Full details of a deposit: metadata, publications, sample count.
GET /api/reconstruction/deposit/{deposit_id}/measurements Individual measurements of a deposit for an element, to overlay historical points on the confidence ellipses.
GET /api/reconstruction/samples Samples in isofind.db holding measurements for the requested element.

Params: element, limit.

GET /api/reconstruction/sample/{sample_id} Details of a sample with its measured ratios: notation, value, uncertainty, standard, depth.
POST /api/reconstruction/samples/aggregate Aggregates several samples into a weighted mean signature, weighted by inverse variances.
POST /api/reconstruction/check-chain-consistency Checks the consistency between a measured matrix and a declared chain. Warnings are informative: the computation remains allowed.
GET /api/reconstruction/nexus-chains Nexus chains saved for an element.

Params: element, limit.

GET /api/reconstruction/nexus-chain/{chain_id}/preview Details of a Nexus chain, with the catalogue process_id values resolved.
POST /api/reconstruction/dag/preview Lightweight graph validation without inversion: cycles, isolated nodes, anchoring of targets, reconstructibility of each unknown link.
POST /api/reconstruction/dag Full reconstruction of a supply graph. Convergence nodes are handled according to the state of the downstream link.
POST /api/reconstruction/audit-score Auditability score of the reconstruction.
POST /api/reconstruction/session/save Saves a reconstruction session into workflows.db.
POST /api/reconstruction/session/{session_id}/rename Renames a session and updates updated_at.
GET /api/reconstruction/sessions Saved sessions, sorted by descending date.

Params: element, limit.

GET /api/reconstruction/session/{session_id} Reloads a complete session: input, result, audit.
DELETE /api/reconstruction/session/{session_id} Deletes a session. Idempotent, with no recycle bin.

Reports

GET /api/reports/templates Lists report templates.
POST /api/reports/templates Creates a template.
GET /api/reports/templates/{template_id} Retrieves a template.
PUT /api/reports/templates/{template_id} Updates a template.
DELETE /api/reports/templates/{template_id} Deletes a template.
POST /api/reports/generate Generates a PDF report and persists it. The sample_ids list is filtered down to the visible samples.
POST /api/reports/preview Generates a preview PDF, without persistence.
GET /api/reports/licence-status Authorization state per licence tag for each report block. The frontend greys out the blocks that are not permitted.
GET /api/reports/list Lists the generated reports.

Params: label_id, project.

GET /api/reports/{report_id} Metadata of a report.
DELETE /api/reports/{report_id} Deletes a report and its PDF file.
GET /api/reports/download/{report_id} Serves the generated PDF as a direct download.
POST /api/reports/bulk-delete Bulk deletion of reports.
POST /api/reports/export-zip Creates and returns a ZIP archive of the selected reports.
GET /api/reports/nexus-sessions Nexus sessions available for the report form.
GET /api/reports/signature-reconstruction-sessions Signature reconstruction sessions available for the report form.
GET /api/reports/labels Lists labels.
POST /api/reports/labels Creates a label.
PATCH /api/reports/labels/{label_id} Updates a label.
DELETE /api/reports/labels/{label_id} Deletes a label.
POST /api/reports/labels/assign Assigns labels to reports.
POST /api/reports/labels/unassign Removes labels.
GET /api/reports/branding Configured branding.
PUT /api/reports/branding Updates the branding: name and logo path. Pro licence required.
DELETE /api/reports/branding Removes the custom branding and restores the IsoFind identity.
GET /api/reports/custom-blocks Lists the active custom blocks.
GET /api/reports/custom-blocks/{block_id} Details of a custom block.
POST /api/reports/custom-blocks Creates a custom block.
PUT /api/reports/custom-blocks/{block_id} Updates a custom block.
DELETE /api/reports/custom-blocks/{block_id} Deletes a custom block.
GET /api/reports/matrix-groups Groups of comparable matrices.
PUT /api/reports/matrix-groups Saves the matrix groups.
GET /api/reports/matrix-groups/check Checks whether comparing two matrices is relevant.

Params: matrix_a, matrix_b.

ISOF Format

POST /api/isof/export-payload Builds the ISOF document and returns it as raw JSON, without triggering a download.
POST /api/isof/export Generates and returns an .isof file. Only the visible samples are exported.
POST /api/isof/import Imports methods, pipelines, yields and assignments from an .isof file. Samples in the file are treated read-only: nothing is inserted into samples.
POST /api/isof/verify Verifies the signature of an ISOF file without importing it.
POST /api/isof/sign Signs an .isof file at level 2 (ECDSA and the IsoFind PKI).

Body: multipart: file, lab_key_pem, lab_cert_pem, use_stored_cert, scope, signed_by.

POST /api/isof/inspect-cert Reads a PEM or DER certificate and returns its X.509 attributes, along with its position in the IsoFind PKI chain.
GET /api/isof/load-cert Indicates whether a lab certificate is stored locally and returns its attributes. Returns found=false without error if none is stored.
POST /api/isof/store-cert Encrypts and stores the private key and lab certificate locally.

If use_stored_key=true, the key is read from the existing store: the post-CSR case, where the key was already generated.

POST /api/isof/generate-csr Generates an ECDSA P-256 key pair locally, builds a signed CSR, saves the private key in the Fernet-encrypted store, and returns the CSR in PEM.
DELETE /api/isof/store-cert Deletes the key, the certificate and the Fernet key from the local store.

Community Database

GET /api/community/search Searches the online community database.

Params: query, location. Requires network access, blocked in air-gap mode.

POST /api/community/contribute Contributes a sample to the community database. Available from the Research plan onwards.
GET /api/community/stats Community database statistics.
POST /api/community/submit Receives a signed ISOF, validates it, then places it in the moderation queue.
GET /api/community/imports Lists the imported community packs.
POST /api/community/imports/{prov_id}/{action} Archives, unarchives or deletes an imported pack.

Path: action is archive, unarchive or delete.

Archives

GET /api/archives/samples Paginated list of archived samples.

Params: page (default 1), page_size (default 50), search, element, classification, sector, project.

GET /api/archives/samples/{sample_id} Full details of an archived sample.
GET /api/archives/filters Unique values available for the archive list filters.
GET /api/archives/stats Statistics of the visible archives.
GET /api/archive/stats Archive statistics for the dashboard. Legacy alias.
POST /api/archives/restore/{sample_id} Restores an archived sample into the active database.
DELETE /api/archives/delete/{sample_id} Permanently deletes an archived sample.
GET /api/archives/export Exports the visible archives to CSV.
POST /api/samples/{sample_id}/archive Archives a sample.
POST /api/projects/{project_name}/archive Archives every sample of a project in a single operation.

Projects

POST /api/project/new Creates a project.
GET /api/project/current Returns the active project.
PUT /api/project/update Updates the active project.
DELETE /api/project/close Closes the active project.
GET /api/project/list Lists every project in the registry, sorted by descending modification date.
POST /api/project/activate/{id_projet} Switches to a project from the registry. The project is rebuilt from its metadata, without requiring an .isf file.
DELETE /api/project/registry/{id_projet} Removes a project from the registry.

Params: supprimer_donnees (bool): also deletes the associated samples. Irreversible.

GET /api/project/samples Identifiers and lightweight metadata of the samples associated with the active project.
POST /api/project/samples/add Manually associates samples with the project by their identifiers.
POST /api/project/samples/sync Synchronizes the project samples by name matching.
DELETE /api/project/samples/{sample_id} Removes a sample from the project, without deleting it from the database.
POST /api/project/samples/clear Resets the list of associated samples.
GET /api/project/score Score of the active project.

Params: project_only (bool): restricts the computation to the samples associated with the project.

GET /api/project/score/snapshot Creates a score snapshot for the history.
GET /api/project/score/history Score history.
GET /api/project/intention Detects the implicit objective of the project from observed usage.
GET /api/project/objectives Available objectives with their descriptions.
GET /api/project/constraints Available constraints.
POST /api/project/export Exports the active project to the .isf format.
GET /api/project/export/download/{filename} Downloads an exported .isf file.
POST /api/project/import Imports a project from an .isf file.
GET /api/project/training-data/check Detects the presence of training data in the database. Admin only.
DELETE /api/project/training-data/purge Deletes every sample and analysis carrying the training marker. Global destructive action, admin only.

Mapping

GET /api/tiles/{z}/{x}/{y}.png Serves a PNG tile from the local MBTiles. TMS scheme: y_tms = (2^z - 1) - y_xyz.
GET /api/tiles/metadata Metadata of the active MBTiles. Lets the frontend adjust the Leaflet maxZoom to the installed pack.
GET /api/map/samples-extended Geochemical, molecular and physicochemical data for every georeferenced sample. No pagination: designed for a single call when the mapping page loads.
GET /api/map/section-data Measurements with depth, for the vertical cross-section.

Params: sample_ids (comma-separated list), mode (isotope, geochem, physico, molecule), element, ratio, parameter (default pH).

GET /api/mapping/view/{sample_id} Generates and displays an interactive map of the matches.
GET /api/mapping/export/{sample_id} Exports the match map as a standalone HTML file.

Params: threshold, filename.

GET /api/mapping/batch-export Generates the maps of several samples.

Generic Workflows

POST /api/workflows/save Saves a generic workflow.
GET /api/workflows/list Lists generic workflows.

Licence

GET /api/licence/status State of the current licence. A /api/license/status variant exists for English-speaking clients.
GET /api/licence/features Features permitted by the licence.
GET /api/licence/scopes Permitted usage scopes.
GET /api/licence/dev-mode/status Indicates whether development mode is active.

Interface Pages

GET / Dashboard.
GET /echantillons Sample management.
GET /analyse Match search.
GET /database Database management.
GET /standardization Standardisation and normalization.
GET /visualisation Mapping and 2D visualisation.
GET /visualisation_3d 3D visualisation and simulation.
GET /tableur Built-in spreadsheet.
GET /advanced Advanced features.
GET /advanced_analysis Advanced isotopic analysis interface with Fourier. Served encrypted in memory through ProtectedTemplates.
GET /algocalculs Algorithms and computations.
GET /correspondances_nexus Nexus matches.
GET /process_library Process library.
GET /process_database Process database.
GET /lab_data_advanced Advanced laboratory data.
GET /rapports Reports module.
GET /signature_reconstruction Signature reconstruction.
GET /chain_map Supply chain graph.
GET /supplier_audit Supplier audit.
GET /prospection Energy and Mining prospecting module. Pro licence required.
GET /prospection_site Prospecting site.
GET /forages Borehole management.
GET /credits-isof ISOF credits and acknowledgements.
GET /login Login page.
GET /lock Locked session page, shown after a manual lock.
  • Foix, FRANCE
Linkedin

All Rights Reserved by IsoFind