{
  "openapi": "3.1.0",
  "info": {
    "title": "CitePulse API",
    "description": "Academic citation analytics for AI research agents, grant offices, and PIs — bibliography verification, retraction detection, paper/author/institution/journal metrics, topic and funder impact scans, and grounded literature briefs. Built on free, open scholarly infrastructure (OpenAlex, Crossref, Semantic Scholar, Unpaywall) as the free-rebuild layer under Web of Science ($212k/yr) and Scopus (~$140k/yr). All endpoints require x402 payment (USDC on Base mainnet) via the PAYMENT-SIGNATURE header.",
    "version": "1.0.0",
    "contact": {
      "url": "https://citepulse.theaslangroupllc.com"
    }
  },
  "servers": [
    {
      "url": "https://citepulse.theaslangroupllc.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 payment signature. Send a request without this header to receive a 402 with payment requirements. Sign the payment and retry with the PAYMENT-SIGNATURE header."
      }
    }
  },
  "security": [
    {
      "x402": []
    }
  ],
  "paths": {
    "/api/ref-check": {
      "get": {
        "summary": "Bibliography verification (flagship)",
        "description": "Verify up to 20 citations (DOIs or free-text references) — existence, retraction/withdrawal status (Crossref + Retraction Watch + OpenAlex), and title/author/year mismatches against the real record. Built for AI agents auditing an LLM-generated bibliography before it ships.",
        "operationId": "refCheckGet",
        "parameters": [
          {
            "name": "citations",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Comma-separated list of DOIs and/or free-text references, up to 20 items."
          }
        ],
        "responses": {
          "200": { "description": "Per-reference verification results" },
          "400": { "description": "No citations supplied, or more than 20 supplied" },
          "402": { "description": "Payment required — x402 USDC on Base." }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand"
      },
      "post": {
        "summary": "Bibliography verification (flagship, structured input)",
        "description": "Same as GET, but accepts a JSON body for richer per-reference input (explicit doi/title/authors/year fields), enabling stricter mismatch detection.",
        "operationId": "refCheckPost",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "citations": {
                    "type": "array",
                    "maxItems": 20,
                    "items": {
                      "oneOf": [
                        { "type": "string", "description": "A DOI or a full free-text reference string" },
                        {
                          "type": "object",
                          "properties": {
                            "doi": { "type": "string" },
                            "title": { "type": "string" },
                            "authors": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] },
                            "year": { "oneOf": [{ "type": "number" }, { "type": "string" }] },
                            "raw": { "type": "string", "description": "Original citation string, used for DOI extraction if doi is omitted" }
                          }
                        }
                      ]
                    }
                  }
                },
                "required": ["citations"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Per-reference verification results" },
          "402": { "description": "Payment required — x402 USDC on Base." }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/paper": {
      "get": {
        "summary": "Single-paper lookup",
        "description": "Paper lookup by DOI or title — citation count, influence, open-access status with a direct legal-OA link (Unpaywall), venue, and TLDR. Deterministic passthrough, no synthesis.",
        "operationId": "paper",
        "parameters": [
          { "name": "doi", "in": "query", "required": false, "schema": { "type": "string" }, "description": "DOI (preferred, exact match)" },
          { "name": "title", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Paper title (used only if doi is omitted)" }
        ],
        "responses": {
          "200": { "description": "Paper metadata" },
          "402": { "description": "Payment required — x402 USDC on Base." }
        },
        "x-price-usd": 0.05,
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/author": {
      "get": {
        "summary": "Author metrics",
        "description": "Works/citations/h-index/i10-index, 10-year output trend, affiliation timeline, and an honest disambiguation-confidence flag when the name search surfaces multiple plausible candidate profiles.",
        "operationId": "author",
        "parameters": [
          { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Author name to search" },
          { "name": "openalex_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "OpenAlex author ID for an exact, disambiguated lookup" }
        ],
        "responses": {
          "200": { "description": "Author metrics" },
          "402": { "description": "Payment required — x402 USDC on Base." }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/institution": {
      "get": {
        "summary": "Institution research-output benchmark",
        "description": "Works count, total citations, h-index/i10-index, 10-year output/citation trend, and topic-strength breakdown. Optional two-way comparison against a second institution.",
        "operationId": "institution",
        "parameters": [
          { "name": "name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Institution name to search" },
          { "name": "compare_to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional second institution name for a side-by-side benchmark" }
        ],
        "responses": {
          "200": { "description": "Institution metrics" },
          "402": { "description": "Payment required — x402 USDC on Base." }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/journal": {
      "get": {
        "summary": "Journal/venue intelligence",
        "description": "OpenAlex metrics (works, citations, DOAJ status, APC) plus Tavily-grounded, cited legitimacy signals. Never renders a bare predatory/legitimate verdict — evidence list + neutral framing only.",
        "operationId": "journal",
        "parameters": [
          { "name": "name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Journal/venue name or ISSN" },
          { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language, default en" }
        ],
        "responses": {
          "200": { "description": "Journal intelligence brief" },
          "402": { "description": "Payment required — x402 USDC on Base." }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/topic-scan": {
      "get": {
        "summary": "Rising-topic research scan",
        "description": "Retrieves top-cited/recent OpenAlex works for a topic and synthesizes what's currently rising, what's foundational, and where coverage is thin.",
        "operationId": "topicScan",
        "parameters": [
          { "name": "topic", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Topic/field name or keyword" },
          { "name": "years", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Lookback window in years, default 3" },
          { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language, default en" }
        ],
        "responses": {
          "200": { "description": "Topic scan brief" },
          "402": { "description": "Payment required — x402 USDC on Base." }
        },
        "x-price-usd": 0.20,
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/funder-impact": {
      "get": {
        "summary": "Funder research-impact brief",
        "description": "What a funder's grants have produced, grounded in OpenAlex's grants.funder-linked works (highest-impact papers, field distribution).",
        "operationId": "funderImpact",
        "parameters": [
          { "name": "funder", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Funder name" },
          { "name": "years", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Lookback window in years, default unlimited" },
          { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language, default en" }
        ],
        "responses": {
          "200": { "description": "Funder impact brief" },
          "402": { "description": "Payment required — x402 USDC on Base." }
        },
        "x-price-usd": 0.20,
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/literature-brief": {
      "get": {
        "summary": "Grounded literature synthesis",
        "description": "State-of-research synthesis for a specific question, grounded in top OpenAlex + Semantic Scholar results with full citations (DOIs). Not a substitute for a full systematic review.",
        "operationId": "literatureBrief",
        "parameters": [
          { "name": "question", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The research question to synthesize" },
          { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Response language, default en" }
        ],
        "responses": {
          "200": { "description": "Literature brief" },
          "402": { "description": "Payment required — x402 USDC on Base." }
        },
        "x-price-usd": 0.25,
        "x-agent-use-case": "on-demand"
      }
    }
  }
}