Sections

Library

Find papers and passages across the library

GET/feed/
GET/papers/{paper_id}/related
GET/papers/graph
POST/papers/research-context
GET/papers/search
GET/papers/search/chunks

GET/feed/

The paper feed

API key, sign-in or anonymousMCP: get_recommended_paper

sort=for_you ranks papers for you from your like/dislike history (interest keyword vector) and citation adjacency to papers you've engaged with; each paper carries match_score and match_reason. Papers you've read or rated are left out unless include_seen. per_page=1 with sort=for_you is the single paper ranked highest for you right now (an empty list: nothing new to recommend). Anonymous visitors get the unpersonalised feed.

Parameters
Name	In	Type	Description
sort	query	"for_you" \| "new" \| "hot" \| "classic"	for_you (ranked for you), new, hot or classic Default: `"for_you"`
category	query	string \| null	Only papers in this arXiv category, e.g. cs.LG
page	query	integer	Page number Default: `1`
per_page	query	integer	Papers per page (1-50) Default: `20`
include_seen	query	boolean	Include papers you've already read or rated Default: `false`

Response: FeedResponse
Field	Type	Description
has_more *	boolean
page *	integer
papers *	PaperResponse[]
abstract *	string
arxiv_id	string \| null
authors *	string
categories *	string
citation_count	integer
classic_rank	integer \| null
created_at *	string
dislikes	integer
doi	string \| null
hot_score *	number
id *	integer
is_classic	boolean
likes	integer
match_reason	string \| null
match_score	number
pdf_url	string \| null
published_date	string \| null
relevance_score	number \| null
source *	string
summary	string \| null
title *	string
viewer_rating	integer \| null
viewer_read	boolean \| null
per_page *	integer
sort *	string
total *	integer

curl

curl 'https://api.papervantage.com/feed/' \
  -H "Authorization: Bearer $PV_API_KEY"

pv papers recommended

GET/papers/{paper_id}/related

Papers linked to this one in the citation graph, ranked by similarity

API key or sign-inMCP: get_related_papers

Cited and citing papers (one hop), ranked by the similarity of their abstracts to this paper's abstract (relevance_score). Neighbours without an embedding yet are counted in unembedded_neighbor_count rather than scored 0, so a short list isn't "nothing related".

Parameters
Name	In	Type	Description
paper_id *	path	integer
relevance_threshold	query	number	Minimum similarity 0-1 (default 0.5) Default: `0.5`
max_results	query	integer	Maximum papers (1-50, default 10) Default: `10`

Response: RelatedPapers
Field	Type	Description
papers *	PaperResponse[]
abstract *	string
arxiv_id	string \| null
authors *	string
categories *	string
citation_count	integer
classic_rank	integer \| null
created_at *	string
dislikes	integer
doi	string \| null
hot_score *	number
id *	integer
is_classic	boolean
likes	integer
match_reason	string \| null
match_score	number
pdf_url	string \| null
published_date	string \| null
relevance_score	number \| null
source *	string
summary	string \| null
title *	string
viewer_rating	integer \| null
viewer_read	boolean \| null
unembedded_neighbor_count *	integer	Neighbours without an embedding yet: counted here rather than scored 0

curl

curl 'https://api.papervantage.com/papers/1/related' \
  -H "Authorization: Bearer $PV_API_KEY"

pv papers related <paper_id>

GET/papers/graph

The citation graph as nodes and edges

API key, sign-in or anonymousMCP: get_citation_graph

With paper_id: that paper's neighbourhood within depth hops (1-2), either direction (is_seed marks the paper). Without it, the library graph (up to max_nodes papers). Nodes get relevance_score (0-1) against `query`, against a project's papers (`project_id`, yours only), or against the seed paper when only paper_id is given. `query` and `project_id` are mutually exclusive. Edges only ever join returned nodes.

Parameters
Name	In	Type	Description
paper_id	query	integer \| null	Seed paper: return its neighbourhood within depth hops
query	query	string \| null	Free-text topic to score nodes against
project_id	query	integer \| null	Score nodes against one of your projects' papers
depth	query	integer	Hops from the seed (1 or 2, default 1) Default: `1`
max_nodes	query	integer \| null	Without paper_id: at most this many papers, by id (1-1000); omitted, the whole library

Response: PaperGraph
Field	Type	Description
edges *	PaperGraphEdge[]
source *	integer
target *	integer
nodes *	PaperGraphNode[]
arxiv_id	string \| null
authors *	string
categories *	string
citation_count	integer
doi	string \| null
id *	integer
is_classic	boolean
is_seed	boolean
published_date	string \| null
relevance_score	number \| null
title *	string

curl

curl 'https://api.papervantage.com/papers/graph' \
  -H "Authorization: Bearer $PV_API_KEY"

pv papers graph

POST/papers/research-context

A condensed briefing on a free-text topic across several papers

API key or sign-inMCP: assemble_research_context

The papers whose abstracts best match the query, plus papers reached from them over citation and supersedes/contradicts/extends edges (up to max_hops). Each paper comes with key claims and methodology from its distillation (or its summary), and `relationships` lists semantic_relation edges between papers in the bundle. Use it for "everything relevant to X".

Request body (JSON)
Field	Type	Description
max_hops	integer	Graph hops from the seed papers (0-4, default 2)
max_papers	integer	Distinct papers in the bundle (1-50, default 8)
query *	string	Free-text research question or topic

Response: ResearchContext
Field	Type	Description
papers *	ContextPaper[]
arxiv_id	string \| null
content_source *	"distillation" \| "abstract_fallback"
hops_from_seed *	integer
id *	integer
is_seed *	boolean
key_claims	string[]
methodology	string \| null
summary	string \| null	Only when the paper isn't distilled yet
title *	string
query *	string
relationships *	ContextRelationship[]
confidence	number \| null
from_paper_id *	integer
from_title	string \| null
rationale	string \| null
relation	string \| null
target_claim	string \| null
to_paper_id *	integer
to_title	string \| null

curl

curl -X POST 'https://api.papervantage.com/papers/research-context' \
  -H "Authorization: Bearer $PV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<query>"}'

pv papers context <query>

GET/papers/search

Search PaperVantage's library for papers

API key or sign-inMCP: search_papers

mode "keyword" (default): every word of the query must appear somewhere in a paper's title, authors or abstract, in any order, most-cited papers first. Only the first 10 words (200 characters) are used; if the query was longer, `truncated` is true.

mode "title": find one specific paper by its title (e.g. a reference from a bibliography). Matching tolerates case, punctuation, a missing subtitle and small differences. Returns the library's matching papers, and under `external` the paper Semantic Scholar matches the title to (with its arxiv_id/doi), or null. A match in `external` with no `papers` means the paper exists but is not in the library yet.

Search never imports: add a paper by arXiv id with POST /papers/ingest/arxiv or POST /papers/imports.

Parameters
Name	In	Type	Description
q *	query	string	Keywords, author names or a partial title (keyword mode), or a full paper title (title mode)
mode	query	string	"keyword" or "title" Default: `"keyword"`
page	query	integer	Page of results (keyword mode) Default: `1`
per_page	query	integer	Results per page (1-50) Default: `20`

Response: PaperSearchResponse
Field	Type	Description
external	ExternalMatch \| null	Title mode only: Semantic Scholar's match for the title, or null
arxiv_id	string \| null
authors	string \| null
doi	string \| null
title	string \| null
year	integer \| null
mode *	"keyword" \| "title"
papers *	PaperResponse[]
abstract *	string
arxiv_id	string \| null
authors *	string
categories *	string
citation_count	integer
classic_rank	integer \| null
created_at *	string
dislikes	integer
doi	string \| null
hot_score *	number
id *	integer
is_classic	boolean
likes	integer
match_reason	string \| null
match_score	number
pdf_url	string \| null
published_date	string \| null
relevance_score	number \| null
source *	string
summary	string \| null
title *	string
viewer_rating	integer \| null
viewer_read	boolean \| null
truncated	boolean	The query was cut to its first 10 terms (200 characters)

curl

curl 'https://api.papervantage.com/papers/search?q=%3Cq%3E' \
  -H "Authorization: Bearer $PV_API_KEY"

pv papers search <q>

GET/papers/search/chunks

Find the passages that answer a question, in one paper or across the library

API key or sign-inMCP: search_paper_chunks

Cheaper and more precise than reading a whole transcript. Ask in natural language; passages are matched by meaning and by words, fused, best first. Judge the results: they are candidates.

Returns {"results": [{paper_id, paper_title, chunk_index, content, score, match}], "legs"}. Only the order of `score` matters. Without paper_id, results also include the caller's OWN private PDFs: those have `private: true`, `paper_id: null` and a `document_id`; nobody else ever sees them.

`legs` = {"semantic": "ok"|"unavailable", "keyword": "ok"}: when semantic is unavailable only exact words match, so rephrase with the paper's own terms. An EMPTY result carries `index_status` -- "not_chunked" (not indexed yet: read the transcript instead), "not_embedded" (exact words only so far) or "no_match" -- so don't retry the same query.

Parameters
Name	In	Type	Description
query *	query	string	Natural-language question or topic
paper_id	query	integer \| null	Search only this paper
max_results	query	integer	Maximum passages (1-30, default 10) Default: `10`

Response: ChunkSearchResponse
Field	Type	Description
index	object \| null	Only on an empty one-paper result: chunk counts
index_status	string \| null	Only on an empty result: not_chunked, not_embedded or no_match
legs *	object	{"semantic": "ok"\|"unavailable", "keyword": "ok"}
results *	object[]	[{paper_id, paper_title, chunk_index, content, score, match}] best first; the caller's own private PDFs have private: true, paper_id: null and a document_id

curl

curl 'https://api.papervantage.com/papers/search/chunks?query=%3Cquery%3E' \
  -H "Authorization: Bearer $PV_API_KEY"

pv papers search-chunks <query>

Next: Animations