{"openapi":"3.1.0","info":{"title":"Citation Velocity Agent API","version":"1.0.0","description":"Find breakthrough research papers early via citation acceleration, cross-domain citation spread, and attention signals. Built for AI agents: every paper carries a DOI link and a ready-to-paste citation. Humans sign in with Magic.link; agents use API keys (Bearer) here or the MCP server at /api/mcp.","contact":{"name":"Citation Velocity","url":"https://citationvelocity.nshipyard.com"}},"servers":[{"url":"https://citationvelocity.nshipyard.com"}],"security":[{"bearerKey":[]}],"components":{"securitySchemes":{"bearerKey":{"type":"http","scheme":"bearer","description":"Agent API key: 'cv_live_...' minted in Settings after Magic.link sign-in, or the AGENT_API_KEY environment master key."}},"schemas":{"Paper":{"type":"object","properties":{"doi":{"type":"string","example":"10.1101/2024.01.01.123456"},"doi_url":{"type":"string","format":"uri"},"url":{"type":"string","format":"uri","description":"This paper's page in Citation Velocity"},"cite_as":{"type":"string","description":"Ready-to-paste citation for a bibliography"},"title":{"type":"string"},"authors":{"type":"array","items":{"type":"string"}},"abstract":{"type":"string"},"source":{"type":"string","enum":["bioRxiv","arXiv","PubMed","HuggingFace","OpenReview"]},"domain":{"type":"string"},"published_date":{"type":"string","format":"date"},"total_citations":{"type":"integer"},"citation_velocity_per_week":{"type":"number"},"cross_domain_citations":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"count":{"type":"integer"}}}},"signal_type":{"type":["string","null"],"enum":["velocity","cross-domain","negative-space",null]},"origin":{"type":"string","enum":["corpus","openalex"]}}}}},"paths":{"/api/mcp":{"post":{"summary":"MCP server endpoint (Streamable HTTP, JSON-RPC 2.0)","description":"Model Context Protocol server. Tools: search_papers, get_paper, get_trending_papers, get_paper_citations, get_alerts, get_stats, get_talent_radar, get_founders_trace, ingest_papers. Resources and prompts are listed via the standard MCP methods.","security":[{"bearerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"JSON-RPC response"},"401":{"description":"Missing or invalid API key"}}}},"/api/v1/papers":{"get":{"summary":"List and search papers","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"domain","in":"query","schema":{"type":"string"}},{"name":"source","in":"query","schema":{"type":"string","enum":["bioRxiv","arXiv","PubMed","HuggingFace","OpenReview"]}},{"name":"signal","in":"query","schema":{"type":"string","enum":["velocity","cross-domain","negative-space"]}},{"name":"min_velocity","in":"query","schema":{"type":"number"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["velocity","citations","date"],"default":"velocity"}},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":50}}],"responses":{"200":{"description":"Papers, each with cite_as and doi_url"}}}},"/api/v1/search":{"get":{"summary":"Keyword search (corpus + live OpenAlex)","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":50}}],"responses":{"200":{"description":"Matching papers"}}}},"/api/v1/papers/{doi}":{"get":{"summary":"One paper, full detail (DOI may contain slashes; ?format=md returns markdown)","parameters":[{"name":"doi","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Paper"},"404":{"description":"Not found"}}}},"/api/v1/citations/{doi}":{"get":{"summary":"Papers citing a given paper, plus its cross-domain spread","parameters":[{"name":"doi","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Citing papers and cross-domain counts"}}}},"/api/v1/trending":{"get":{"summary":"Highest citation velocity right now","responses":{"200":{"description":"Papers"}}}},"/api/v1/stats":{"get":{"summary":"Corpus statistics and top movers","responses":{"200":{"description":"Stats"}}}},"/api/v1/alerts":{"get":{"summary":"Breakthrough signal alerts","parameters":[{"name":"unread","in":"query","schema":{"type":"boolean"}},{"name":"type","in":"query","schema":{"type":"string","enum":["velocity","cross-domain","negative-space"]}}],"responses":{"200":{"description":"Alerts"}}}},"/api/v1/talent":{"get":{"summary":"Researchers ranked by Commercial Gravity Score","responses":{"200":{"description":"Researchers"}}}},"/api/v1/traces/{doi}":{"get":{"summary":"Cached founders trace for a paper, if one exists","responses":{"200":{"description":"Trace"},"404":{"description":"No cached trace"}}}},"/api/v1/ingest":{"post":{"summary":"Refresh the corpus from OpenAlex (requires write scope)","responses":{"200":{"description":"Ingestion result"},"403":{"description":"Key lacks write scope"}}}}}}