IsoFind API

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

General Information

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

Interactive Swagger documentation is accessible at http://127.0.0.1:8001/docs while IsoFind is running. It lists all routes with their full data schemas and allows for direct testing.

The API listens exclusively on 127.0.0.1 (localhost). It is not accessible from the local network unless explicitly configured. For multi-station intranet use, please consult the network deployment documentation.

System & Authentication

GET /api/ready Check if the backend is started and ready.

Returns {"status": "ready"}. Called by Tauri after the FastAPI process initialization.

GET /health Backend health check.

Returns {"status": "healthy"}.

GET /api/version/info Version info and installation mode.

Returns the version, mode (single_user or multi_user), build date, and enabled features.

GET /api/system/mode System operating mode.

GET /api/system/stats Global system statistics (active users, sessions, database state).

POST /api/auth/login User authentication (multi-user mode only).

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

Returns: {"success": bool, "user": {...}} + isotrace_session cookie. In single-user mode, always accepted.

POST /api/auth/logout Logout and session invalidation.

GET /api/auth/check Verifies if the current session is valid.

Returns the logged-in user or {"authenticated": false}.

POST /api/auth/change-password Password change.

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

POST /api/auth/lock Locks the active session without destroying it.

GET /api/auth/sessions Lists active sessions for the current user.

DELETE /api/auth/sessions/{session_id} Invalidates a specific session.

POST /api/auth/recovery Resets admin password via recovery code.

Body: {"recovery_code": str, "new_password": str}. Single-use: a new code is generated after consumption.

Samples

GET /api/samples List all samples with their isotopic data.

Params: limit (int, optional), max number of results. sort (asc or desc): sort by creation date. Default: sort by descending ID.

GET /api/samples/{sample_id} Retrieve a specific sample with its isotopic data.

Returns 404 if the identifier does not exist.

GET /api/v2/samples/{sample_id}/full Retrieve a sample with all associated data: isotopes, methods, publications, pipeline.

GET /api/samples/isotopic-data All isotopic data in the database with normalization indicators.

GET /api/samples/metadata Sample metadata (GPS, project, dates, description). Dictionary indexed by sample_id.

GET /api/samples/stats Dashboard statistics: total samples, samples with GPS, unique elements, breakdown by material type.

POST /api/samples Create a new sample.

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

Material type and classification are normalized automatically. Current user ID is associated with the sample in multi-user mode.

PUT /api/samples/{sample_id} Completely replace a sample.

PATCH /api/samples/{sample_id} Partial update of a sample (only provided fields are modified).

DELETE /api/samples/{sample_id} Delete a sample and all associated isotopic data.

DELETE /api/samples/{sample_id}/isotope/{isotope_id} Delete an individual isotopic data point from a sample.

GET /api/samples/{sample_id}/purification-yields Retrieve recorded purification yields for a sample.

POST /api/samples/{sample_id}/purification-yields Record or update the purification yield of an element for a sample.

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

Uses INSERT OR REPLACE logic: only one yield per (sample_id, element) pair.

DELETE /api/samples/{sample_id}/purification-yields/{element} Delete the purification yield of a specific element.

GET /api/samples/export Export all samples to CSV (columns: name, material type, sector, date, location, description, classification, GPS coordinates, project).

POST /api/v2/samples/export-batch Export multiple samples with all data (isotopes, methods, publications).

Body: [sample_id, ...], list of IDs.

POST /api/import-csv Import a sample CSV file with intelligent column resolution.

Body: multipart/form-data: file (UploadFile), archive_mode (bool, default False).

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

Match Analysis

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

Body:

Field	Type	Default	Description
sample_id	int	required	Identifier of the sample in the database.
isotope_data	list	[]	Isotopic data to use (if empty, uses data from the database).
threshold	float	0.85	Match score threshold (0 to 1). Mahalanobis distance.
algorithm	str	hybrid	Algorithm: hybrid, mahalanobis, bayesian.
classification_filter	str	sources	Filter by sources, daughters, or all.
database_sources	list	["local"]	Databases to query: local, archive, community.
same_material	bool	true	Restrict to identical material types.

POST /analyze/manual Manual analysis with directly entered isotopic data, without a database sample.

Body: sample_name, material_type, isotope_data (list, required), threshold (float, default 0.75), algorithm. Creates a temporary non-persisted sample.

POST /api/matching/find/{sample_id} Search for matches for a sample, simplified version.

Params: threshold (float, optional): matching threshold.

POST /api/matching/batch Analyze multiple samples in a single request.

Body: [sample_id, ...] + threshold (float, optional). Returns a dictionary sample_id → result with isolated errors per sample.

POST /api/matching/manual Manual analysis via the matching interface (with element and ratio selection).

POST /api/matching/advanced/{sample_id} Advanced analysis with extended parameters (additional filters, multi-database selection).

GET /api/matching/config Current configuration of the matching engine (thresholds, default algorithm).

Methods, pipelines, and publications (v2)

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

Params: type (str, optional), element (str, optional): filters.

GET /api/v2/methods/{method_id} Retrieves a specific method.

POST /api/v2/methods Creates a new method in the library.

PUT /api/v2/methods/{method_id} Updates a method.

DELETE /api/v2/methods/{method_id} Deletes a method.

GET /api/v2/methods/yield-ranges Acceptable yield ranges per method (used for purification yield validation).

GET /api/v2/samples/{sample_id}/methods Methods associated with a sample.

POST /api/v2/samples/{sample_id}/methods Associates a method with a sample.

POST /api/v2/samples/methods-batch Associates a method with multiple samples in a single operation.

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

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

GET /api/v2/publications/doi/{doi} Searches for a publication by its DOI.

POST /api/v2/publications Creates a bibliographic reference.

GET /api/v2/pipelines Lists analysis pipelines.

Params: element (str, optional): filter by target element.

GET /api/v2/samples/{sample_id}/pipeline Pipeline associated with a sample and its progression.

PUT /api/v2/sample-pipelines/{sp_id}/progress Updates the progression of a pipeline step.

Standards and Isotopic Normalization

GET /api/standards Lists all isotopic standards.

POST /api/standards/custom Creates a custom standard.

PUT /api/standards/{standard_id} Updates an existing standard.

DELETE /api/standards/{standard_id} Deletes an isotopic standard.

POST /api/samples/{sample_id}/normalize Normalizes isotopic data of a sample relative to a reference standard.

POST /api/samples/auto-normalize Automatically normalizes all samples for which an inter-standard shift is available (measured standard + configured reference + calculated shift).

POST /api/samples/reset-all-normalizations Resets all applied normalizations.

POST /api/samples/normalize-materials Normalizes material types for all samples.

POST /api/samples/normalize-all-data Normalizes materials, classifications, isotopic ratios, and element symbols in a single pass.

CRM and Inter-standard Shifts

GET /api/crm/list Lists all Certified Reference Materials (CRM).

GET /api/crm/{crm_id} Retrieves a specific CRM with its concentrations and isotopic data.

POST /api/crm/add Adds a new CRM.

PUT /api/crm/{crm_id}/edit Updates metadata for a CRM.

POST /api/crm/{crm_id}/concentration Adds an elemental concentration to a CRM.

POST /api/crm/{crm_id}/isotope Adds isotopic data to a CRM.

DELETE /api/crm/{crm_id}/concentration/{element} Deletes the concentration of a specific element from a CRM.

DELETE /api/crm/{crm_id}/isotope/{ratio} Deletes specific isotopic data from a CRM.

GET /api/crm/statistics Global statistics on registered CRMs.

GET /api/crm/georem/search Search in the online GeoReM database.

POST /api/crm/georem/import/{georem_id}/full Fully imports a CRM from GeoReM (concentrations + isotopes).

POST /api/shifts/calculate/{crm_id} Calculates the inter-standard shift for a given CRM, element, and isotopic ratio.

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

POST /api/shifts/calculate-all Calculates all available shifts for all CRMs.

POST /api/shifts/convert Converts an isotopic value from one standard to another by applying the calculated shift.

GET /api/shifts/history History of calculated shifts.

Elements

GET /api/elements Lists all isotopic elements in the database (predefined + 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.

Community Database

GET /api/community/search Search in the online community database.

Params: query (str), location (str). Requires active 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.

Mapping

GET /api/tiles/{z}/{x}/{y}.png Map tiles proxy. Serves tiles from the configured source (online or local packs in air-gap mode).

GET /api/mapping/export/{sample_id} Mapping export for a sample.

GET /api/mapping/batch-export Batch mapping export for multiple samples.

Database and Backup

GET /api/database/backup Generates and downloads a backup of the main database.

POST /api/database/restore Restores the database from a backup.

POST /api/sync Manual synchronization between configured data sources.

User Management

GET /api/users/list Lists all user accounts (admin only).

POST /api/users/create Creates a new 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.

DELETE /api/users/{user_id} Deletes a user account (admin only, not allowed on own account).

PUT /api/user/profile Updates the profile of the logged-in user (display name, email).

Logs and Journals

GET /api/logs/activity User activity log (logins, actions, exports).

GET /api/logs/export Exports activity logs to CSV.

Geographic Zones and Statistics

GET /api/zones Lists reference geographic zones used in matching search.

GET /api/stats Global database statistics (samples, elements, zones, calculated matches).

Configuration

GET /api/config/language Current interface language.

POST /api/config/language Changes the interface language.

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

GET /api/updates/check Checks for update availability. Requires network access (blocked in air-gap mode).