HTTP API

← Home

lit-monitor serve exposes the same query and ingestion layer as the MCP server over HTTP, so scripts and other services can drive lit-monitor without an MCP client. Interactive request/response docs are auto-generated by FastAPI at http://127.0.0.1:8765/docs — that page is always the authoritative, version-matched reference; the table below is the orientation.

Local-only, no auth

The server binds to 127.0.0.1 by default and has no authentication of its own. Treat it as a localhost service; don't expose the port. See the Web UI guide for host/binding notes.

Stable query & ingest endpoints

These are the programmatic surfaces meant to be called from outside the browser. (The web UI also serves many HTMX-fragment routes — those render partial HTML for the dashboards and aren't part of this stable API.)

Method · Path	Purpose
POST /api/ingest	Ingest a paper end-to-end (extract → embed → graph → note), honouring the R28 atomic dual-write invariant.
GET /api/ingest/queue	The current ingestion queue.
GET /api/ingest/{doi}/status	Ingestion status for one DOI.
GET /api/papers/{doi}	Full snapshot of one paper — extraction, score, metadata.
GET /api/papers/{doi}/related?mode={vector,graph,hybrid}	Related papers under the chosen retrieval mode.
GET /api/papers/{doi}/score-breakdown	The per-signal ranking decomposition for one paper.
POST /api/papers/{doi}/relink	Re-render the paper's Related-Work block from current graph/vector state.
POST /api/papers/{doi}/re-extract	Re-run extraction for one paper (phase-selectable).
POST /api/ask	Natural-language question → generated Cypher → LLM-summarised answer.
POST /api/cypher	Run a read-only, safety-guarded Cypher query (same guard as the MCP run_cypher tool).
POST /api/search	Free-text search across the corpus — vector, graph, or hybrid mode.
GET /api/entities	List entities, filterable ?type=.
GET /api/entities/{canonical_id}	Detail for one canonical entity.
GET /api/discovery/runs	Discovery run history (newest first).
GET /api/discovery/runs/{run_id}	One discovery run's summary.
GET /api/discovery/runs/{run_id}/papers	Ranked papers for one discovery run.
GET /api/health	Liveness/health probe.

{doi} and {canonical_id} are path-style parameters — slashes in a DOI are matched as-is (e.g. GET /api/papers/10.1016/j.example.2024.001).

Parity with MCP

POST /api/ask, POST /api/cypher, and POST /api/search are the HTTP twins of the MCP find_papers_by_query_hybrid, run_cypher, and semantic_search tools — both surfaces call the same shared query layer, so results match. Pick HTTP for scripts and services, MCP for AI agents.