API Reference

FileMind exposes a local FastAPI REST API for power users, scripting, and integrations. The desktop app starts it on a random port under http://127.0.0.1:{port}/api/v1; running filemind serve --port 8765 from the command line gives you a fixed one.

Authentication

The API binds to 127.0.0.1 only and is not reachable from other machines. When the desktop app starts the service it generates a per-launch bearer token, and every route except /health requires it in an Authorization: Bearer … header (or an X-FileMind-Token header). The token is passed to the service as the FILEMIND_TOKEN environment variable; a service started by hand without that variable runs with authentication off.

Health & Service

GET /api/v1/health

Returns service health with per-subsystem status for the language model, embeddings, OCR, and the database, plus a degraded list. No token required.

Library Management

POST /api/v1/library/open

Open or create a library at a specified database path.

{"db_path": "C:\\Papers\\FileMind\\library.db"}

GET /api/v1/library/stats

Returns library statistics: file counts, index-status breakdown, chunk and proposal counts.

GET /api/v1/library/files/check

Checks whether a path is already in the library.

GET /api/v1/library/facets/authors · GET /api/v1/library/facets/folders

Facet values for the author and folder filters.

POST /api/v1/library/clear

Clears derived data (chunks, embeddings, proposals, metadata) but keeps the file registry. The same action as Clear & Re-index in Settings.

POST /api/v1/library/reset

Full database reset. Destructive — cannot be undone.

Scanning & Jobs

POST /api/v1/scan

Submit a background scan job for a folder. Returns a job ID for progress tracking.

{"root_path": "C:\\Papers\\Geothermal"}

GET /api/v1/jobs

List recent background jobs (scan, propose, apply, rollback, model downloads) with status and progress.

GET /api/v1/jobs/{job_id}

Get detailed status for a specific job.

POST /api/v1/jobs/{job_id}/cancel

Cancel a running job (rollback jobs cannot be cancelled).

POST /api/v1/jobs/prune

Drop finished jobs older than a given age from the list.

Rename Proposals

POST /api/v1/renames/propose

Generate rename proposals as a background job.

{"max_files": 100}

GET /api/v1/renames/proposals

List proposals, filterable by status (PROPOSED, APPROVED, APPLIED, REJECTED).

POST /api/v1/renames/proposals/{id}/approve · …/reject

Approve or reject a single proposal.

POST /api/v1/renames/apply

Apply all approved proposals as one journaled batch. Returns 409 if an apply or rollback is already running.

POST /api/v1/renames/rollback

Roll back an applied batch by ID.

GET /api/v1/actions/batches

List all rename batches with their status.

Search

GET /api/v1/search

Search your library with query parameters:

GET /api/v1/search?q=magnetotelluric+imaging&mode=hybrid&limit=20&offset=0

mode is hybrid, fts, or semantic. The search filters map to parameters such as year_min, year_max, authors, scope_root, has_doi, index_status, exclude_duplicates, sort, and group_by_file. The API also accepts filters the app does not expose yet — venue, min_confidence, added_from, added_to, and size_bucket — and rerank=false to skip the reranker. The response carries total, limit, and offset for paging.

GET /api/v1/search/facets

Returns available facet values (years, authors, venues) with counts for building filter UIs. Folder facets come from /library/facets/folders.

Ask My Library (RAG)

POST /api/v1/ask

Ask a question and get an answer with citations.

{
  "question": "How are magnetotelluric surveys used to characterise geothermal reservoirs?",
  "k": 12,
  "scope_root": "C:\\Papers\\Geothermal"
}

The response includes the answer text, a list of claims with the source tags each one cites and whether the citation was verified, the full source passages, and a not_found note for anything the library could not answer.

Papers & Duplicates

GET /api/v1/papers/{file_id}

Returns metadata, file path, index status, and rename history for a paper.

GET /api/v1/papers/{file_id}/related

Returns related papers ranked by embedding similarity.

GET /api/v1/papers/42/related?limit=10

POST /api/v1/extract-metadata

Run metadata extraction for a single file on demand.

GET /api/v1/duplicates

List duplicate groups (exact SHA-256 matches and near-duplicate title matches).

POST /api/v1/duplicates/{group_id}/resolve

Resolve a duplicate group by keeping one file and removing the others from the database.

Export

POST /api/v1/export/citations

Export citations in BibTeX, RIS, or CSV format to a path, applying the quality gates described in Export & Integration.

POST /api/v1/export/metadata

Export metadata as CSV or JSON.

POST /api/v1/export/zotero/validate · GET /api/v1/export/zotero/collections · POST /api/v1/export/zotero

Validate Zotero credentials, list collections, and push records to Zotero.

Configuration & Models

GET /api/v1/config

Returns the current configuration (API keys are redacted).

PATCH /api/v1/config

Update configuration at runtime without restarting. Providers are re-initialised for the sections that changed.

GET /api/v1/config/hardware

Detected RAM and GPU memory, with the local model recommendation.

GET /api/v1/config/llm/detect

Probe for local LLM servers (Ollama, LM Studio, and other OpenAI-compatible endpoints) already running on the machine.

GET /api/v1/config/llm/models · GET /api/v1/config/llm/catalog

Models available from the configured provider, and the curated Ollama catalog with hardware fit and install state.

POST /api/v1/config/llm/pull

Pull an Ollama model as a background job.

POST /api/v1/config/llm/test

Test a provider configuration without persisting it — the Test Connection button.

POST /api/v1/config/llm/download-builtin · GET …/builtin-status · POST …/builtin/start · GET …/builtin/status

Download the built-in model (resumable, SHA-256 verified), check whether it is on disk, start the bundled server, and check that it is running.

License & Usage

GET /api/v1/license/status · POST /api/v1/license/activate · POST /api/v1/license/deactivate

Current plan and allowance, and seat activation and release.

GET /api/v1/usage

This month's cloud AI usage: calls, exact token counts, and estimated cost.

CLI

The Python package also provides a command-line interface for scripting. It shares the same library and configuration as the app; --config and --db point it elsewhere.

filemind scan C:\Papers\Geothermal
filemind propose --limit 100 --out proposals.json
filemind apply --dry-run
filemind apply
filemind rollback <batch_id>
filemind search --mode hybrid "magnetotelluric imaging"
filemind ask "How are magnetotelluric surveys used to characterise geothermal reservoirs?"
filemind reindex
filemind serve --port 8765