API Reference

FileMind exposes a local FastAPI REST API for power users, scripting, and integrations. The API listens on http://localhost:{port} — the port is auto-selected by default and shown in the app's status bar.

Authentication

The API binds to 127.0.0.1 only and does not require authentication. It is not accessible from other machines on your network.

Health & Service

`GET /health`

Returns service health with per-subsystem status. Use this to check if Ollama, embeddings, and other components are working.

Library Management

`POST /library/open`

Open or create a library at a specified database path.

`GET /library/stats`

Returns library statistics: file counts, index status breakdown, metadata extraction progress.

`POST /library/clear`

Clears derived data (chunks, embeddings, proposals) but keeps the file registry.

`POST /library/reset`

Full database reset. Destructive — cannot be undone.

Scanning & Ingestion

`POST /scan`

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

{"folder": "/path/to/pdfs"}

`GET /jobs`

List recent background jobs with status and progress.

`GET /jobs/{job_id}`

Get detailed status for a specific job.

`POST /jobs/{job_id}/cancel`

Cancel a running job.

Rename Proposals

`POST /renames/propose`

Generate rename proposals as a background job.

{"max_files": 100}

`GET /renames/proposals`

List proposals with optional filtering by status (PROPOSED, APPROVED, APPLIED, REJECTED).

`POST /renames/proposals/{id}/approve`

Approve a single proposal.

`POST /renames/proposals/{id}/reject`

Reject a single proposal.

`POST /renames/apply`

Apply all approved proposals as an atomic batch.

`POST /renames/rollback`

Rollback the most recently applied batch.

`GET /actions/batches`

List all rename batches with their status.

Search

`GET /search`

Search your library with query parameters:

GET /search?q=attention+mechanisms&mode=hybrid&limit=20&offset=0

Supports all search filters as query parameters: year_min, year_max, author, venue, has_doi, min_confidence, sort, group_by_file, etc.

`GET /search/facets`

Returns available facet values (years, authors, venues, statuses) for building filter UIs.

Ask My Library (RAG)

`POST /ask`

Ask a question and get an answer with citations.

{
  "question": "What temperature was used in the sintering process?",
  "k": 12,
  "scope_root": "/optional/folder/filter"
}

Response includes the answer text, claims with source references, and full source details.

Paper Details

`GET /papers/{file_id}`

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

`GET /papers/{file_id}/related`

Returns related papers ranked by embedding similarity.

GET /papers/42/related?limit=10

Duplicates

`GET /duplicates`

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

`POST /duplicates/{group_id}/resolve`

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

Export

`POST /export/citations`

Export citations in BibTeX, RIS, or CSV format. See Export & Integration.

`POST /export/metadata`

Export metadata as CSV or JSON.

Configuration

`GET /api/v1/config`

Returns the current configuration (API keys are redacted).

`PATCH /api/v1/config`

Update configuration at runtime without restarting.

CLI

FileMind also provides a command-line interface for scripting:

filemind scan /path/to/pdfs
filemind propose --limit 100
filemind apply
filemind rollback <batch_id>
filemind search --mode hybrid "attention mechanisms"
filemind ask "What temperature was used?"
filemind serve --port 8765
filemind reindex