Sections

Papers (API key)

One paper: metadata, transcript, references, rating. More papers routes that only the website uses are under "Website routes".

GET/papers/{paper_id}
PUT/papers/{paper_id}/rating
GET/papers/{paper_id}/references
GET/papers/{paper_id}/transcript
GET/papers/arxiv/{arxiv_id}

GET/papers/{paper_id}

One paper by id

API key, sign-in or anonymousMCP: get_paper

Full metadata and summary (plain-English LLM summary if generated), citation count and, for a signed-in caller, their own rating (viewer_rating) and read state (viewer_read).

Parameters
Name	In	Type	Description
paper_id *	path	integer

Response: PaperResponse
Field	Type	Description
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

curl

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

pv papers get <paper_id>

PUT/papers/{paper_id}/rating

Like, dislike, or clear your rating on a paper

API key or sign-inMCP: rate_paperwrite

Sets the rating (it doesn't toggle). Ratings feed your interest vector, which drives the "for you" feed and recommendations.

Parameters
Name	In	Type	Description
paper_id *	path	integer

Request body (JSON)
Field	Type	Description
rating *	1 \| -1 \| 0	1 to like, -1 to dislike, 0 to clear any existing rating

Response: RatingResponse
Field	Type	Description
status *	string	liked, disliked, unliked, undisliked or unrated

curl

curl -X PUT 'https://api.papervantage.com/papers/1/rating' \
  -H "Authorization: Bearer $PV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rating":1}'

pv papers rate <paper_id> --rating <rating>

GET/papers/{paper_id}/references

The papers one paper cites (its bibliography), a page at a time

API key, sign-in or anonymousMCP: get_paper_references

Each reference has library_paper_id when the paper is already in PaperVantage's library (null when it isn't: import it by its arxiv_id or doi). index_status is "ok", "not_indexed_yet" (no reference list is known for this paper yet) or "fetch_failed" (the lookup failed: try again later) -- never an unexplained empty list. A signed-in caller's request looks the list up when none is known yet; an anonymous one doesn't.

Parameters
Name	In	Type	Description
paper_id *	path	integer
limit	query	integer	References per page (1-100, default 25) Default: `25`
cursor	query	string \| null	next_cursor from the previous page

Response: ReferencesPage
Field	Type	Description
index_status *	"ok" \| "not_indexed_yet" \| "fetch_failed"
next_cursor	string \| null
references *	ReferenceEntry[]
arxiv_id	string \| null
authors	string \| null
doi	string \| null
key *	string	Stable key for this reference (used by dismiss_papers)
library_paper_id	integer \| null	Set when the paper is in the library
title	string \| null
year	integer \| null
source *	string	Where the reference list came from
total *	integer

curl

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

pv papers references <paper_id>

GET/papers/{paper_id}/transcript

A paper's full PDF-to-markdown transcript text, whole or a window at a time

API key, sign-in or anonymousMCP: get_paper_transcript

The raw extracted full text -- everything the paper's PDF contains, converted to markdown (methodology details, exact wording, results tables, full bibliography). For one fact or passage, GET /papers/search/chunks is much cheaper. status is one of pending / in_progress / succeeded / failed; markdown is null unless status is succeeded. A transcript can run to ~200k characters: with `limit`, markdown holds at most that many characters from `offset`, and next_offset (when not null) is the offset of the next window. 404 only for an unknown paper.

Parameters
Name	In	Type	Description
paper_id *	path	integer
offset	query	integer	Character position to start from (default 0) Default: `0`
limit	query	integer \| null	Maximum characters to return (1000-100000); omitted, the rest of the transcript

Response: PaperTranscriptResponse
Field	Type	Description
markdown	string \| null	The transcript window; null unless status is succeeded
next_offset	integer \| null	Pass as offset for the next window; null at the end
offset	integer	Character position the window starts at
status *	string	Paper.extraction_status: pending, in_progress, succeeded or failed
total_chars	integer \| null	The whole transcript's length in characters

curl

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

pv papers transcript <paper_id>

GET/papers/arxiv/{arxiv_id}

One paper by its arXiv id

API key, sign-in or anonymousMCP: get_paper

Full metadata and summary (plain-English LLM summary if generated), citation count and, for a signed-in caller, their own rating and read state. The version suffix is ignored.

Parameters
Name	In	Type	Description
arxiv_id *	path	string	arXiv identifier, e.g. "2301.07041" or "2301.07041v2" (version ignored)

Response: PaperResponse
Field	Type	Description
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

curl

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

pv papers get-arxiv <arxiv_id>

Next: Projects (API key)