For AI agents

Endo Lab is built to be queried by autonomous agents as well as humans. This page collects the canonical install recipes and behavioural notes in one place. See also /llms.txt for a short machine-readable introduction and /llms-full.txt for the long-form version with the full source-license matrix.

OpenAPI & cURL

The full API contract lives at /openapi.json (OpenAPI 3.1). Interactive Swagger UI at /docs. Every operation carries an operationId, a one-line summary, and a longer description naming the source(s) and license envelope on the result.

curl -s http://www.endolab.net/openapi.json | jq '.paths | keys'

curl -s -X POST http://www.endolab.net/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "dienogest endometriosis pain", "limit": 10}'

MCP (Model Context Protocol)

A first-party MCP server is planned for phase D of the agent-support spec but has not yet shipped. The intended starting surface is the 7-tool set documented below — already stable in src/endo_lab/agent/tools.py. Until the MCP server lands, point any MCP-aware client at the OpenAPI spec above — most Claude Desktop / Cursor / OpenAI Agents SDK setups can self-discover from the spec.

Tool surface (preview of the MCP server)

The corpus-tool surface that the MCP server (phase D) will expose is already defined as stable JSON schemas in the codebase (src/endo_lab/agent/tools.py). External agents using OpenAPI today can structure their queries against the same shapes:

search_corpus(query, limit?, year_min?, year_max?, study_type?) — hybrid BM25 + dense-vector search over the full corpus. Returns paper summaries.
find_recent(topic, since_year?, limit?) — focused variant of search_corpus with a year filter; defaults to the past two calendar years.
get_paper(paper_id) — single paper detail (title, abstract, journal, year, license, full-text-on-file flag).
ask_paper(paper_id, question) — verbatim-quote-only Q&A against one paper's body text. Only works when has_full_text=true.
compare_papers(paper_ids[2-6], dimension) — side-by-side comparison matrix on a focused dimension; runs per-paper Q&A in parallel.
get_trial(primary_id, primary_registry?) — clinical-trial lookup by registry ID (NCT…, ISRCTN…, ChiCTR…).
get_grant(funder, award_id) — funded-grant lookup by natural key (NIH RePORTER + EU CORDIS today).

These same tools power the first-party /research/chat surface — a working reference implementation of a corpus-tool agent. Drive it directly to see the shape of responses the MCP server will return.

Rate limits

Anonymous use: 60 requests/minute per IP. Authenticated API keys (phase E) get higher quotas. Phase C will surface X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers on every response — back off before exhausting the bucket. A 429 returns a structured JSON body with retry_after_seconds.

Citing Endo Lab

Cite the underlying source (DOI / PMID / NCT / RePORTER project number), not Endo Lab as an authority. We are a federator; the upstream record is the truth.

BibTeX and RIS export are available today via the chat surface (POST /research/chat/citations, form fields paper_ids (comma-separated UUIDs) and format=bibtex|ris). A per-paper formatted-citation endpoint (GET /papers/{id}/citation, adding APA / Vancouver / CSL-JSON) is still planned in phase B.

Acceptable use

Research only. No medical advice. Honour per-record licenses — see /terms. WHO ICTRP records are non-commercial only; the per-record commercial_use_ok flag and the X-License response header make this machine-checkable.

Example agent prompts

"Find RCTs published since 2022 on letrozole for adenomyosis pain. Return the top 10 with DOIs and abstracts."
"Hydrate these 30 PMIDs and report which have CC-BY full text available." (bulk lookup lands in phase C)
"Plot the trend in adolescent endometriosis prevalence studies over the last decade." (uses GET /research/api/explore/prevalence)