openapi: 3.1.0
info:
  title: Evipedia API
  version: "1.0.0"
  summary: Read-only access to evipedia.ai evidence reviews.
  description: >
    Public, key-less, read-only endpoints for evipedia.ai - a continuously
    updated encyclopedia of evidence reviews on health & longevity
    interventions. Every endpoint is a plain HTTP GET with no authentication.
    Content is licensed CC BY 4.0 (c) Forever Healthy Foundation; credit
    "evipedia.ai" and, where practical, link the review's permalink.
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  contact:
    name: Evipedia - Made for Integration
    url: https://evipedia.ai/integration
servers:
  - url: https://evipedia.ai
    description: Production
tags:
  - name: catalog
    description: Whole-catalog indexes and feeds.
  - name: review
    description: Per-review resources, addressed by the review's slug.
paths:
  /reviews.json:
    get:
      operationId: listReviews
      tags: [catalog]
      summary: Full review catalog
      description: >
        Every live review with its canonical name, alternate names, category,
        permalinks (HTML / Markdown / metadata), dates, and plain-text conclusion.
      responses:
        "200":
          description: Array of review index entries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ReviewIndexEntry"
  /search.json:
    get:
      operationId: searchIndex
      tags: [catalog]
      summary: Search index
      description: >
        One lightweight entry per review (name, synonyms, keywords, category,
        url). Synonym- and drug-class-aware; the same index that powers the
        search box on the site.
      responses:
        "200":
          description: Array of search entries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SearchEntry"
  /evipedia-corpus.jsonl:
    get:
      operationId: getCorpus
      tags: [catalog]
      summary: Full corpus (JSONL)
      description: >
        The entire catalogue in one file - one JSON object per line per review,
        each with metadata (slug, topic, url, category, dates, alternate_names,
        conclusion, citation) and the full public Markdown. Newline-delimited
        JSON (`application/x-ndjson`), ~25 MB.
      responses:
        "200":
          description: Newline-delimited JSON - one CorpusRecord per line.
          content:
            application/x-ndjson:
              schema:
                $ref: "#/components/schemas/CorpusRecord"
  /{slug}.md:
    get:
      operationId: getReviewMarkdown
      tags: [review]
      summary: Raw Markdown of a review
      description: >
        The complete evidence review as raw Markdown (frontmatter + full body),
        byte-for-byte, with no HTML to parse.
      parameters:
        - $ref: "#/components/parameters/Slug"
      responses:
        "200":
          description: The review as Markdown.
          content:
            text/markdown:
              schema:
                type: string
        "404":
          description: No review exists for that slug.
  /{slug}.meta.json:
    get:
      operationId: getReviewMetadata
      tags: [review]
      summary: Structured medical metadata of a review
      description: >
        Flattened medical metadata - publication/modified/last-reviewed dates,
        the typed `about` entity with alternate names, and an ordered
        primary-source citation list (PMIDs for PubMed sources). Derived from the
        same source as the review page's schema.org MedicalWebPage JSON-LD, so
        the two never drift.
      parameters:
        - $ref: "#/components/parameters/Slug"
      responses:
        "200":
          description: The review's medical metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReviewMetadata"
        "404":
          description: No review exists for that slug.
  /feed.xml:
    get:
      operationId: getUpdatesFeed
      tags: [catalog]
      summary: RSS feed of new and refreshed reviews
      responses:
        "200":
          description: RSS 2.0 feed.
          content:
            application/rss+xml:
              schema:
                type: string
  /llms.txt:
    get:
      operationId: getLlmsSignpost
      tags: [catalog]
      summary: Agent signpost (llmstxt.org)
      description: Plain-text signpost to every machine-readable surface, plus the stable review section anchors.
      responses:
        "200":
          description: Plain-text signpost.
          content:
            text/plain:
              schema:
                type: string
components:
  parameters:
    Slug:
      name: slug
      in: path
      required: true
      description: >
        The review's short slug - its `short_topic_lc`, i.e. the last path
        segment of its permalink (e.g. `rapamycin`). Available as the last
        segment of each `permalink` in /reviews.json.
      schema:
        type: string
      example: rapamycin
  schemas:
    ReviewIndexEntry:
      type: object
      description: One entry in /reviews.json.
      properties:
        canonical_name:
          type: string
          example: Rapamycin
        canonical_topic:
          type: string
          example: Rapamycin for Health & Longevity
        alternate_names:
          type: array
          items:
            type: string
          example: [Sirolimus, Rapamune, AY-22989, WY-090217]
        permalink:
          type: string
          format: uri
          example: https://evipedia.ai/rapamycin
        permalink_md:
          type: string
          format: uri
          example: https://evipedia.ai/rapamycin.md
        permalink_meta:
          type: string
          format: uri
          example: https://evipedia.ai/rapamycin.meta.json
        category:
          type: string
          example: medication
        creation_date:
          type: string
          format: date
          example: "2026-07-10"
        dateModified:
          type: string
          format: date
          example: "2026-07-10"
        lastReviewed:
          type: string
          format: date
          example: "2026-07-10"
        er_conclusion:
          type: string
          description: Plain-text conclusion of the evidence review.
    CorpusRecord:
      type: object
      description: One line of /evipedia-corpus.jsonl (a single review).
      properties:
        slug:
          type: string
          example: rapamycin
        topic:
          type: string
          example: Rapamycin for Health & Longevity
        url:
          type: string
          format: uri
          example: https://evipedia.ai/rapamycin
        canonical_name:
          type: string
          example: Rapamycin
        category:
          type: string
          example: medication
        alternate_names:
          type: array
          items:
            type: string
        datePublished:
          type: string
          format: date
        dateModified:
          type: string
          format: date
        lastReviewed:
          type: string
          format: date
        conclusion:
          type: string
        citation:
          type: array
          items:
            $ref: "#/components/schemas/Citation"
        markdown:
          type: string
          description: Full public Markdown of the review, identical to /{slug}.md.
    SearchEntry:
      type: object
      description: One entry in /search.json.
      properties:
        short_topic:
          type: string
          example: Rapamycin
        alternate_names:
          type: string
          description: Comma-separated synonyms (raw string, not an array).
          example: "Sirolimus, Rapamune, AY-22989, WY-090217"
        ep_keywords:
          type: string
          description: Comma-separated keywords / drug-class terms.
        ep_category:
          type: string
          example: medication
        url:
          type: string
          example: /rapamycin
    ReviewMetadata:
      type: object
      description: The response body of /{slug}.meta.json.
      properties:
        slug:
          type: string
          example: rapamycin
        topic:
          type: string
          example: Rapamycin for Health & Longevity
        url:
          type: string
          format: uri
          example: https://evipedia.ai/rapamycin
        datePublished:
          type: string
          format: date
          example: "2026-07-10"
        dateModified:
          type: string
          format: date
          example: "2026-07-10"
        lastReviewed:
          type: string
          format: date
          example: "2026-07-10"
        about:
          type: object
          description: The intervention as a flattened schema.org entity.
          properties:
            type:
              type: string
              description: schema.org MedicalEntity subtype (e.g. Drug, Substance, DietarySupplement, MedicalTherapy).
              example: Drug
            name:
              type: string
              example: Rapamycin
            alternateName:
              type: array
              items:
                type: string
              example: [Sirolimus, Rapamune, AY-22989, WY-090217]
        citation:
          type: array
          description: Ordered primary-source citations, in page order.
          items:
            $ref: "#/components/schemas/Citation"
    Citation:
      type: object
      required: [name, url]
      properties:
        name:
          type: string
          example: "Targeting ageing with rapamycin and its derivatives in humans: a systematic review"
        url:
          type: string
          format: uri
          example: https://pubmed.ncbi.nlm.nih.gov/38310895/
        pmid:
          type: string
          description: PubMed ID; present only when the source is PubMed.
          example: "38310895"