{"openapi":"3.1.0","info":{"title":"Endo Lab Corpus API","summary":"Federated endometriosis & adenomyosis research corpus.","description":"Endo Lab aggregates endometriosis and adenomyosis research metadata from 11 public sources (OpenAlex, PubMed, Crossref, Europe PMC, Unpaywall, PMC, SciLite, ClinicalTrials.gov, WHO ICTRP, NIH RePORTER, EU CORDIS) and exposes a hybrid (BM25 + vector) search API plus per-record license metadata.\n\n**For AI agents:** see `/llms.txt` for a one-page introduction, or `/agents` for install recipes (MCP, OpenAPI, cURL). Per-record licenses are surfaced in every payload and via the `X-License` response header; please honour the source license, especially WHO ICTRP (non-commercial only) and PMC-NC full text.\n\nProject lead: Denisha Labuschagne.","termsOfService":"/terms","contact":{"name":"Endo Lab","url":"https://github.com/louis-kotze/endo-lab"},"license":{"name":"Per-source (see /terms and X-License header)"},"version":"0.1.0"},"paths":{"/search":{"post":{"tags":["search"],"summary":"Hybrid search across the Endo Lab corpus","description":"Run a hybrid BM25 + vector search over papers, trials, and grants. Accepts free-text plus structured filters (year range, conditions, outcomes, license-permissive only). Results carry per-record license metadata; see `X-License` response header for the most-restrictive license in the payload.\n\nUse this for open-ended discovery. For known IDs, prefer `GET /papers/{id}` or (once available in phase C) bulk `POST /papers/lookup`.","operationId":"search_corpus","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}},"required":true},"responses":{"200":{"description":"Ranked results with facet counts and the BM25 / vector contribution per hit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/search/facets":{"get":{"tags":["search"],"summary":"Facet counts for a search query (GET)","description":"GET-shaped variant of `/search/facets` for agents that prefer URL query parameters over JSON request bodies.","operationId":"search_facets_get","requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/SearchFilters"},{"type":"null"}],"title":"Filters"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacetsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["search"],"summary":"Facet counts for a search query (POST)","description":"Returns aggregate counts (per-year, per-condition, per-source, per-license) for the same query a `POST /search` call would issue. Use to render filter UIs without paying for the full result set.","operationId":"search_facets_post","requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/SearchFilters"},{"type":"null"}],"title":"Filters"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacetsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/papers/{paper_id}":{"get":{"tags":["papers"],"summary":"Retrieve a paper by its Endo Lab UUID","description":"Hydrate a single paper. `paper_id` is the Endo Lab internal UUID (`canonical_uris` in the response carries DOI/PMID/PMCID/OpenAlex). A prefix-aware lookup (`doi:`, `pmid:`, ...) is planned for `/v1/resolve` in phase B of the agent-support spec. Response includes per-record license metadata; honour the source license when re-publishing.","operationId":"get_paper","parameters":[{"name":"paper_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Paper Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaperSummary"}}}},"404":{"description":"Paper not found for the supplied ID."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/papers/{paper_id}/full-text":{"get":{"tags":["papers"],"summary":"Full text for a paper (license-gated)","description":"`paper_id` is the Endo Lab UUID (same shape as `GET /papers/{id}`). Returns the parsed full body for papers whose license permits redistribution (CC-BY, CC0, US public domain). For CC-BY-NC, CC-BY-ND, or all-rights-reserved, returns a stub with `license_restricted: true` and a redirect URL to the publisher / PMC; the agent should follow that link rather than asking again.","operationId":"get_paper_full_text","parameters":[{"name":"paper_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Paper Id"}}],"responses":{"200":{"description":"Full text payload OR license-restricted stub.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Paper Full Text"}}}},"404":{"description":"Paper not found or no full text on file."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/papers/{paper_id}/references":{"get":{"tags":["papers"],"summary":"Outgoing citations for a paper","description":"`paper_id` is the Endo Lab UUID. Returns the list of papers cited by that paper, sourced from Crossref + OpenAlex. Each reference carries its own canonical IDs (DOI/PMID/OpenAlex) so agents can hydrate them in a follow-up bulk lookup (planned for phase C).","operationId":"get_paper_references","parameters":[{"name":"paper_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Paper Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaperReferencesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/papers/{paper_id}/annotations":{"get":{"tags":["papers"],"summary":"SciLite annotations for a paper","description":"`paper_id` is the Endo Lab UUID. Returns Europe PMC SciLite annotations (mentions of genes, diseases, chemicals, organisms) extracted from the paper's full text. Annotations are CC-BY — attribute Europe PMC when re-using.","operationId":"get_paper_annotations","parameters":[{"name":"paper_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Paper Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaperAnnotationsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/trials/{primary_id}":{"get":{"tags":["trials"],"summary":"Retrieve a clinical trial by registry ID","description":"Accepts `nct:NCT01234567` (ClinicalTrials.gov), `ictrp:<id>` (WHO ICTRP — non-commercial only; the response carries `commercial_use_ok=false`), or the Endo Lab UUID.","operationId":"get_trial","parameters":[{"name":"primary_id","in":"path","required":true,"schema":{"type":"string","title":"Primary Id"}},{"name":"primary_registry","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Registry"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrialResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/grants/{grant_id}":{"get":{"tags":["grants"],"summary":"Retrieve a funded grant by its Endo Lab UUID","description":"Hydrate a single grant. `grant_id` is the Endo Lab internal UUID; the response payload carries the upstream funder IDs (NIH RePORTER project number, EU CORDIS ID). A funder-ID-prefix lookup (`reporter:`, `cordis:`) is planned for `/v1/resolve` in phase B.","operationId":"get_grant","parameters":[{"name":"grant_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Grant Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/research/papers/{paper_id}/cite":{"get":{"tags":["portal"],"summary":"Formatted citation strings for a paper (BibTeX / RIS / plain)","description":"`paper_id` is the Endo Lab UUID. Returns three pre-formatted citation strings so the agent never has to assemble them from raw fields. Phase B's `GET /papers/{id}/citation` will replace this with a broader set (APA, Vancouver, CSL-JSON); the BibTeX and RIS payloads here are stable and forward-compatible.","operationId":"get_paper_citation","parameters":[{"name":"paper_id","in":"path","required":true,"schema":{"type":"string","title":"Paper Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/research/api/papers/{paper_id}/tldr":{"get":{"tags":["portal"],"summary":"Cached AI-generated TLDR for a paper","description":"`paper_id` is the Endo Lab UUID. Returns the cached one-sentence AI-generated summary if available, or a status indicating that generation is still in flight / hasn't been triggered. This endpoint is a cheap read-only check — it never triggers LLM generation. Use when an agent wants the corpus's existing summary rather than producing its own.","operationId":"get_paper_tldr","parameters":[{"name":"paper_id","in":"path","required":true,"schema":{"type":"string","title":"Paper Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/_TldrStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/research/api/papers/{paper_id}/deep-tldr":{"get":{"tags":["portal"],"summary":"Cached AI-generated deep summary; triggers fetch + generation if missing","description":"`paper_id` is the Endo Lab UUID. Returns the cached 3-5 sentence AI-generated summary (the one with the explicit endo-relevance closing sentence) if available. If missing, triggers whatever background work is needed — body fetch from PMC/EPMC/Unpaywall if no body on file, then deep_tldr generation — and returns a status the poller can use to display progress. See response model for the five possible statuses.","operationId":"get_paper_deep_tldr","parameters":[{"name":"paper_id","in":"path","required":true,"schema":{"type":"string","title":"Paper Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/_DeepTldrResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/research/api/compare":{"post":{"tags":["portal"],"summary":"AI-generated side-by-side comparison table for 2-10 papers","description":"Accepts 2-10 paper UUIDs in `paper_ids`. Returns a comparison table with LLM-generated cell values across columns the model picks (population, intervention, outcomes, etc.). Failures return `error` populated and `cells: []` rather than HTTP 500, so the caller can show a clear failure state without retrying. Calling agents should be aware they're consuming our LLM budget; prefer batching multiple paper-comparisons into one call.","operationId":"compare_papers","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/_CompareRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/_CompareResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/research/api/papers/{paper_id}/ask":{"post":{"tags":["portal"],"summary":"Verbatim-quote-only Q&A over one paper's full text","description":"`paper_id` is the Endo Lab UUID. Asks a question against the paper's stored full text and returns an answer grounded in verbatim quotes from the body. Returns 400 if the paper has no full text on file (agents should check `has_full_text` on the paper summary first, or fall back to abstract-only questions via the agent's own LLM). `unanswerable: true` means the model couldn't find supporting quotes — the agent should treat that as a hard negative, not retry with rephrased prompts.","operationId":"ask_paper","parameters":[{"name":"paper_id","in":"path","required":true,"schema":{"type":"string","title":"Paper Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/_AskRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/_AskResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/research/api/explore/prevalence":{"get":{"tags":["portal","explore"],"summary":"Prevalence study counts aggregated by year and population","description":"Yearly counts of prevalence studies in the corpus, faceted by population demographic (adolescent / reproductive-age / perimenopausal / postmenopausal). Aggregated from the Endo Lab tagger pipeline (`condition_tags`, `population_demographics`).","operationId":"explore_prevalence","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/research/api/explore/word-clouds":{"get":{"tags":["portal","explore"],"summary":"Term-frequency word clouds for the corpus","description":"Per-decade weighted term frequencies from paper titles and abstracts, filtered to clinically meaningful terms (drugs, interventions, outcomes). Suitable for direct render as a word-cloud chart; raw weights returned so the client picks the layout.","operationId":"explore_word_clouds","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/research/api/explore/diversity-trend":{"get":{"tags":["portal","explore"],"summary":"Demographic diversity trend in study populations","description":"Year-by-year breakdown of reported population demographics in endometriosis research — race/ethnicity reporting completeness, geographic spread of authors, and population-age coverage. Useful for diversity-gap analysis.","operationId":"explore_diversity_trend","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/research/api/explore/outcome-trend":{"get":{"tags":["portal","explore"],"summary":"Trend in measured outcomes over time","description":"Year-by-year frequency of named outcome instruments (e.g. EHP-30, NRS pain, laparoscopic findings). Shows which outcomes are gaining or losing methodological share. Sourced from the `outcome_instruments` tag table populated by the EPHect-aware tagger pipeline.","operationId":"explore_outcome_trend","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/research/api/explore/citation-graph":{"get":{"tags":["portal","explore"],"summary":"Citation graph slice around a seed paper or topic","description":"Returns nodes (papers) + edges (citations) for a sub-graph around a seed paper or topic query, suitable for direct render as a force-directed graph. Edges sourced from Crossref + OpenAlex. Hard cap on node count to keep response sizes bounded — see the `limit` parameter.","operationId":"explore_citation_graph","parameters":[{"name":"paper_id","in":"query","required":true,"schema":{"type":"string","title":"Paper Id"}},{"name":"depth","in":"query","required":false,"schema":{"type":"integer","default":1,"title":"Depth"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/research/api/explore/cooccurrence":{"get":{"tags":["portal","explore"],"summary":"Term co-occurrence matrix for the corpus","description":"Pairwise co-occurrence counts for the user-supplied terms across paper titles and abstracts. Returns a symmetric matrix suitable for heatmap rendering. Useful for hypothesising relationships (e.g. which interventions are studied alongside which outcomes).","operationId":"explore_cooccurrence","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/healthz":{"get":{"summary":"Healthz","operationId":"healthz_healthz_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response Healthz Healthz Get"}}}}}}},"/stats":{"get":{"summary":"Stats","operationId":"stats_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}}}}}},"components":{"schemas":{"AiVerdict":{"properties":{"verdict":{"type":"string","enum":["yes","no","possibly","insufficient_evidence"],"title":"Verdict"},"confidence":{"type":"number","title":"Confidence"},"summary":{"type":"string","title":"Summary"},"stances":{"items":{"$ref":"#/components/schemas/AiVerdictStance"},"type":"array","title":"Stances"},"n_papers_considered":{"type":"integer","title":"N Papers Considered"},"model":{"type":"string","title":"Model"},"generated_at":{"type":"string","format":"date-time","title":"Generated At"}},"type":"object","required":["verdict","confidence","summary","n_papers_considered","model","generated_at"],"title":"AiVerdict","description":"The aggregated AI verdict over the query's top hits."},"AiVerdictStance":{"properties":{"paper_id":{"type":"string","title":"Paper Id"},"stance":{"type":"string","enum":["supports","contradicts","mixed","off_topic"],"title":"Stance"},"note":{"type":"string","title":"Note"}},"type":"object","required":["paper_id","stance","note"],"title":"AiVerdictStance"},"AnnotationItem":{"properties":{"concept_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Concept Id"},"concept_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Concept Label"},"span_start":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Span Start"},"span_end":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Span End"},"span_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Span Source"},"source_provider":{"type":"string","title":"Source Provider"}},"type":"object","required":["source_provider"],"title":"AnnotationItem"},"FacetsResponse":{"properties":{"year_buckets":{"additionalProperties":{"type":"integer"},"type":"object","title":"Year Buckets"},"study_type":{"additionalProperties":{"type":"integer"},"type":"object","title":"Study Type"},"condition_tags":{"additionalProperties":{"type":"integer"},"type":"object","title":"Condition Tags"},"oa_status":{"additionalProperties":{"type":"integer"},"type":"object","title":"Oa Status"}},"type":"object","title":"FacetsResponse","description":"Counts grouped by common search facet dimensions over a base filter set."},"GrantResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"funder":{"type":"string","title":"Funder"},"award_id":{"type":"string","title":"Award Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"abstract":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Abstract"},"pi_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pi Name"},"organization":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Organization"},"start_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Start Date"},"end_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"End Date"},"total_funding":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Funding"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"},"condition_tags":{"items":{"type":"string"},"type":"array","title":"Condition Tags"},"source_license":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source License"},"commercial_use_ok":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Commercial Use Ok"},"attribution_required":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Attribution Required"},"attribution_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Attribution Text"}},"type":"object","required":["id","funder","award_id"],"title":"GrantResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"IngestionRunSummary":{"properties":{"source":{"type":"string","title":"Source"},"started_at":{"type":"string","title":"Started At"},"finished_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Finished At"},"status":{"type":"string","title":"Status"},"fetched":{"type":"integer","title":"Fetched"},"inserted":{"type":"integer","title":"Inserted"},"updated":{"type":"integer","title":"Updated"},"errored":{"type":"integer","title":"Errored"}},"type":"object","required":["source","started_at","finished_at","status","fetched","inserted","updated","errored"],"title":"IngestionRunSummary"},"PaperAnnotationsResponse":{"properties":{"paper_id":{"type":"string","format":"uuid","title":"Paper Id","description":"UUID of the paper these annotations belong to."},"annotations":{"additionalProperties":{"items":{"$ref":"#/components/schemas/AnnotationItem"},"type":"array"},"type":"object","title":"Annotations","description":"Map from concept type to the list of annotation items of that type."}},"type":"object","required":["paper_id","annotations"],"title":"PaperAnnotationsResponse","description":"SciLite annotations grouped by ``concept_type``."},"PaperLicense":{"properties":{"source_license":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source License"},"commercial_use_ok":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Commercial Use Ok"},"attribution_required":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Attribution Required"},"attribution_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Attribution Text"}},"type":"object","title":"PaperLicense"},"PaperReferenceItem":{"properties":{"cited_doi":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cited Doi"},"cited_paper_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cited Paper Id"},"source":{"type":"string","title":"Source"}},"type":"object","required":["source"],"title":"PaperReferenceItem","description":"One outbound citation from a paper.\n\n``cited_paper_id`` is populated when the cited DOI resolved to a row\nin our corpus; otherwise only ``cited_doi`` is set."},"PaperReferencesResponse":{"properties":{"paper_id":{"type":"string","format":"uuid","title":"Paper Id","description":"UUID of the paper whose outbound references are listed."},"references":{"items":{"$ref":"#/components/schemas/PaperReferenceItem"},"type":"array","title":"References","description":"List of outbound citations from this paper."}},"type":"object","required":["paper_id","references"],"title":"PaperReferencesResponse"},"PaperSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Endo Lab internal UUID; stable across re-ingests.","examples":["3fa85f64-5717-4562-b3fc-2c963f66afa6"]},"doi":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Doi","description":"DOI without the `https://doi.org/` prefix.","examples":["10.1016/j.fertnstert.2023.01.001"]},"pmid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pmid","description":"PubMed ID as a string.","examples":["36925012"]},"pmcid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pmcid","description":"PubMed Central ID as a string.","examples":["PMC10015432"]},"openalex_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Openalex Id","description":"OpenAlex work ID.","examples":["W2741809807"]},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Paper title; null only when no source supplied one (rare)."},"abstract":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Abstract","description":"Plain-text abstract, normalised across sources; null when no source supplied one."},"publication_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Publication Year","description":"Year of publication (4-digit). Source preference: Crossref > PubMed > OpenAlex."},"journal_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Journal Id","description":"Endo Lab UUID for the journal — internal; agents should use `journal_title` for display."},"journal_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Journal Title","description":"Human-readable name of the publishing journal."},"has_full_text":{"type":"boolean","title":"Has Full Text","description":"True if a downloadable full body is on file.","default":false},"is_preprint":{"type":"boolean","title":"Is Preprint","description":"True if the paper is a preprint not yet peer-reviewed.","default":false},"preprint_server":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preprint Server","description":"Preprint server name (e.g. 'biorxiv', 'medrxiv', 'arxiv'); set only when is_preprint is true."},"oa_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Oa Status","description":"Open-access status as reported by Unpaywall (e.g. 'gold', 'green', 'closed')."},"oa_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Oa Url","description":"Unpaywall best OA location URL; may point to a PDF or a landing page."},"cited_by_count":{"type":"integer","title":"Cited By Count","description":"In-corpus inbound citation count; denormalized and refreshed nightly.","default":0},"study_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Study Type","description":"Study design classification (e.g. 'RCT', 'cohort', 'case_report')."},"condition_tags":{"items":{"type":"string"},"type":"array","title":"Condition Tags","description":"Controlled vocabulary tags for conditions covered by this paper."},"outcome_instruments":{"items":{"type":"string"},"type":"array","title":"Outcome Instruments","description":"Standardised outcome instruments reported in this paper."},"license":{"$ref":"#/components/schemas/PaperLicense","description":"Licensing metadata for this paper's content."},"tldr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tldr","description":"AI-generated one-sentence summary of the paper."},"tldr_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tldr Model","description":"Identifier of the model used to generate the tldr."},"tldr_generated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Tldr Generated At","description":"Timestamp when the tldr was generated."}},"type":"object","required":["id"],"title":"PaperSummary","description":"Compact paper representation returned in search hits."},"SearchFilters":{"properties":{"year":{"anyOf":[{"$ref":"#/components/schemas/YearFilter"},{"type":"null"}]},"study_type":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Study Type"},"condition_tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Condition Tags"},"outcome_instruments":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Outcome Instruments"},"mesh_descriptors":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Mesh Descriptors"},"journal_issn":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Journal Issn"},"language":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Language"},"has_full_text":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Full Text"},"oa_status":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Oa Status"},"pmc_oa_partition":{"anyOf":[{"items":{"type":"string","enum":["commercial","non_commercial","other"]},"type":"array"},{"type":"null"}],"title":"Pmc Oa Partition"},"is_preprint":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Preprint"},"retracted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Retracted"},"openalex_topic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Openalex Topic"},"population_transgender_included":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Population Transgender Included"},"population_adolescents_included":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Population Adolescents Included"},"population_lmic_sites":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Population Lmic Sites"},"population_race_ethnicity_reported":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Population Race Ethnicity Reported"},"section_scope":{"anyOf":[{"items":{"type":"string","enum":["title","abstract","methods","results"]},"type":"array"},{"type":"null"}],"title":"Section Scope"},"exclude_tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Exclude Tags"}},"type":"object","title":"SearchFilters","description":"Filter set for the search API. All fields are optional and AND-combined.\n\n``exclude_tags`` defaults to dropping disambiguated endometritis hits\nso naive endometriosis searches don't return endometritis papers; pass\nan empty list to opt out."},"SearchHit":{"properties":{"paper":{"$ref":"#/components/schemas/PaperSummary"},"score":{"type":"number","title":"Score"},"breakdown":{"additionalProperties":true,"type":"object","title":"Breakdown"}},"type":"object","required":["paper","score"],"title":"SearchHit"},"SearchRequest":{"properties":{"q":{"type":"string","title":"Q","default":""},"filters":{"$ref":"#/components/schemas/SearchFilters"},"mode":{"type":"string","enum":["bm25","vector","hybrid"],"title":"Mode","default":"hybrid"},"limit":{"type":"integer","title":"Limit","default":25},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"rerank":{"type":"boolean","title":"Rerank","default":false},"rerank_pool":{"type":"integer","title":"Rerank Pool","default":50},"ai_verdict":{"type":"boolean","title":"Ai Verdict","default":false},"ai_verdict_pool":{"type":"integer","title":"Ai Verdict Pool","default":10}},"type":"object","title":"SearchRequest"},"SearchResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/SearchHit"},"type":"array","title":"Results","description":"Ranked list of search hits for the current page."},"total_estimated":{"type":"integer","title":"Total Estimated","description":"Estimated total papers matching the query; upper bound for pagination, not the page size."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque cursor token to fetch the next page; null when no further pages exist."},"highlights":{"additionalProperties":{"type":"string"},"type":"object","title":"Highlights","description":"Map from paper_id to a short abstract snippet around the first match position."},"facets_in_result":{"additionalProperties":{"additionalProperties":{"type":"integer"},"type":"object"},"type":"object","title":"Facets In Result","description":"Facet counts grouped by dimension over the result set (not the full corpus)."},"ai_verdict":{"anyOf":[{"$ref":"#/components/schemas/AiVerdict"},{"type":"null"}],"description":"AI verdict over the top hits; present only when the request set ai_verdict=true and the LLM call succeeded."}},"type":"object","required":["results","total_estimated"],"title":"SearchResponse"},"StatsResponse":{"properties":{"papers_total":{"type":"integer","title":"Papers Total"},"papers_with_full_text":{"type":"integer","title":"Papers With Full Text"},"papers_with_embeddings":{"type":"integer","title":"Papers With Embeddings"},"papers_with_oa_url":{"type":"integer","title":"Papers With Oa Url","default":0},"trials_total":{"type":"integer","title":"Trials Total"},"grants_total":{"type":"integer","title":"Grants Total"},"last_ingest_runs":{"items":{"$ref":"#/components/schemas/IngestionRunSummary"},"type":"array","title":"Last Ingest Runs"}},"type":"object","required":["papers_total","papers_with_full_text","papers_with_embeddings","trials_total","grants_total","last_ingest_runs"],"title":"StatsResponse"},"TrialResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"primary_id":{"type":"string","title":"Primary Id"},"primary_registry":{"type":"string","title":"Primary Registry"},"secondary_ids":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Secondary Ids"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"phase":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phase"},"conditions":{"items":{"type":"string"},"type":"array","title":"Conditions"},"condition_tags":{"items":{"type":"string"},"type":"array","title":"Condition Tags"},"interventions":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Interventions"},"eligibility_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Eligibility Text"},"enrollment":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Enrollment"},"start_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Start Date"},"completion_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Completion Date"},"last_update_posted":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Last Update Posted"},"has_results":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Results"},"countries":{"items":{"type":"string"},"type":"array","title":"Countries"},"source_license":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source License"},"commercial_use_ok":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Commercial Use Ok"},"attribution_required":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Attribution Required"},"attribution_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Attribution Text"}},"type":"object","required":["id","primary_id","primary_registry"],"title":"TrialResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"YearFilter":{"properties":{"gte":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Gte"},"lte":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Lte"}},"type":"object","title":"YearFilter","description":"Inclusive lower/upper bound on ``papers.publication_year``."},"_AskRequest":{"properties":{"question":{"type":"string","maxLength":500,"minLength":3,"title":"Question"}},"type":"object","required":["question"],"title":"_AskRequest"},"_AskResponse":{"properties":{"question":{"type":"string","title":"Question"},"answer":{"type":"string","title":"Answer"},"quotes":{"items":{"$ref":"#/components/schemas/_QuoteResponse"},"type":"array","title":"Quotes"},"unanswerable":{"type":"boolean","title":"Unanswerable"},"model":{"type":"string","title":"Model"},"generated_at":{"type":"string","format":"date-time","title":"Generated At"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["question","answer","quotes","unanswerable","model","generated_at"],"title":"_AskResponse"},"_CompareCellResponse":{"properties":{"paper_id":{"type":"string","title":"Paper Id"},"column":{"type":"string","title":"Column"},"value":{"type":"string","title":"Value"}},"type":"object","required":["paper_id","column","value"],"title":"_CompareCellResponse"},"_CompareRequest":{"properties":{"paper_ids":{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":10,"title":"Paper Ids"}},"type":"object","title":"_CompareRequest"},"_CompareResponse":{"properties":{"columns":{"items":{"type":"string"},"type":"array","title":"Columns"},"cells":{"items":{"$ref":"#/components/schemas/_CompareCellResponse"},"type":"array","title":"Cells"},"n_papers":{"type":"integer","title":"N Papers"},"model":{"type":"string","title":"Model"},"generated_at":{"type":"string","format":"date-time","title":"Generated At"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["columns","cells","n_papers","model","generated_at"],"title":"_CompareResponse"},"_DeepTldrResponse":{"properties":{"paper_id":{"type":"string","title":"Paper Id"},"status":{"type":"string","title":"Status"},"deep_tldr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deep Tldr"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"},"generated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Generated At"},"fetch_failure_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fetch Failure Reason"}},"type":"object","required":["paper_id","status"],"title":"_DeepTldrResponse","description":"Polling response for the on-demand deep-summary generator.\n\nUsed by the \"✨ AI summary\" button on search result cards. Five\nterminal states:\n  - ``status=\"ready\"``: ``deep_tldr`` is populated, render it.\n  - ``status=\"generating\"``: a background worker is producing the\n    deep_tldr from a body we already have. Poller should retry in\n    ~4s; typical wall time 5-15s.\n  - ``status=\"fetching_body\"``: paper had no body so we kicked off\n    the on-demand fulltext fetch. Body lands → deep_tldr generation\n    chains automatically. Poller should retry in ~8s; total wall\n    time 15-60s depending on the upstream source.\n  - ``status=\"unavailable\"``: paper has no fetchable identifier\n    (no PMCID/PMID/DOI/OA URL), so there's nothing to try.\n  - ``status=\"fetch_failed\"``: a prior on-demand fetch failed and\n    we're inside the backoff window — exposed so the UI can show\n    the failure reason rather than spinning."},"_QuoteResponse":{"properties":{"text":{"type":"string","title":"Text"},"section":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Section"}},"type":"object","required":["text"],"title":"_QuoteResponse"},"_TldrStatusResponse":{"properties":{"paper_id":{"type":"string","title":"Paper Id"},"tldr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tldr"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"},"generated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Generated At"},"generating":{"type":"boolean","title":"Generating","default":false}},"type":"object","required":["paper_id"],"title":"_TldrStatusResponse","description":"Polling response for the on-demand TLDR generator.\n\n``tldr`` is null while the background task is still running. The\nportal poller swaps in the AI summary section once ``tldr`` is set."}}},"tags":[{"name":"search","description":"Hybrid BM25 + vector search across the corpus."},{"name":"papers","description":"Retrieve, hydrate, and inspect individual papers (full text, references, annotations)."},{"name":"trials","description":"Clinical trial records from ClinicalTrials.gov and WHO ICTRP (note: ICTRP is non-commercial)."},{"name":"grants","description":"Funded research grants from NIH RePORTER and EU CORDIS."},{"name":"portal","description":"Researcher-facing HTML pages and the JSON endpoints powering them."},{"name":"explore","description":"Aggregate JSON endpoints powering the Explore charts (prevalence, outcomes, co-occurrence, citation graph)."},{"name":"admin","description":"Operator-only HTML admin UI. Not for public consumption."},{"name":"legal","description":"Terms of Service, Privacy Policy, robots.txt, /llms.txt."}]}