Sections

Papers (website and owner)

Used by the website. These routes don't accept an API key.

GET/papers/

List Papers

Public
Parameters
NameInTypeDescription
pagequeryinteger Default: 1
per_pagequeryinteger Default: 20
Response: PaperList
FieldTypeDescription
papers *PaperResponse[]
abstract *string
arxiv_idstring | null
authors *string
categories *string
citation_countinteger
classic_rankinteger | null
created_at *string
dislikesinteger
doistring | null
hot_score *number
id *integer
is_classicboolean
likesinteger
match_reasonstring | null
match_scorenumber
pdf_urlstring | null
published_datestring | null
relevance_scorenumber | null
source *string
summarystring | null
title *string
viewer_ratinginteger | null
viewer_readboolean | null
curl
curl 'https://api.papervantage.com/papers/'

GET/papers/{paper_id}/citations

Inbound citations -- papers in the library that cite this one. The

Public

complement of /references (outbound). Every inbound edge's from_paper_id is by construction a real in-library Paper, unlike outbound references which may be dangling, so this can return PaperResponse directly with no unresolved-reference handling.

Parameters
NameInTypeDescription
paper_id *pathinteger
Response: PaperResponse[]
FieldTypeDescription
abstract *string
arxiv_idstring | null
authors *string
categories *string
citation_countinteger
classic_rankinteger | null
created_at *string
dislikesinteger
doistring | null
hot_score *number
id *integer
is_classicboolean
likesinteger
match_reasonstring | null
match_scorenumber
pdf_urlstring | null
published_datestring | null
relevance_scorenumber | null
source *string
summarystring | null
title *string
viewer_ratinginteger | null
viewer_readboolean | null
curl
curl 'https://api.papervantage.com/papers/1/citations'

POST/papers/{paper_id}/extract-references

Extract Paper References

Site owners only
Parameters
NameInTypeDescription
paper_id *pathinteger

Response: any

curl
curl -X POST 'https://api.papervantage.com/papers/1/extract-references' \
  -H "Authorization: Bearer $COGNITO_ACCESS_TOKEN"

POST/papers/{paper_id}/fetch-citations

Fetch Citations

Site owners only
Parameters
NameInTypeDescription
paper_id *pathinteger

Response: any

curl
curl -X POST 'https://api.papervantage.com/papers/1/fetch-citations' \
  -H "Authorization: Bearer $COGNITO_ACCESS_TOKEN"

GET/papers/{paper_id}/images/{filename}

Serves one figure extracted from the paper's PDF:

Public

`transcripts/{paper_id}/images/{filename}` in S3 (services/pdf_extraction.py's image_s3_key). The transcript markdown references figures as `images/{filename}`, so this is the "frontend route" that key scheme's docstring anticipates -- the paper reader rewrites those relative refs to this URL.

Deliberately no DB lookup and no auth, same as /transcript: the paper id and filename fully determine the S3 key, and only figures already extracted to our bucket are reachable. Missing object -> 404, unsafe filename -> 404.

Parameters
NameInTypeDescription
paper_id *pathinteger
filename *pathstring

Response: any

curl
curl 'https://api.papervantage.com/papers/1/images/%3Cfilename%3E'

GET/papers/{paper_id}/insights

Returns the paper's distilled key claims/methodology/datasets/

Public

results/limitations/prerequisite concepts (services/distillation.py).

404s only if the paper itself doesn't exist. If the paper exists but hasn't been distilled yet (still pending, or its PDF extraction hasn't succeeded yet -- see distill_paper's gating), this returns a 200 with every field null, the same "async-generated content that may not have completed yet renders as a null field, not a 404" convention PaperResponse.summary already uses.

Parameters
NameInTypeDescription
paper_id *pathinteger
Response: PaperInsightResponse
FieldTypeDescription
created_atstring | null
datasetsstring[] | null
key_claimsstring[] | null
limitationsstring | null
methodologystring | null
paper_id *integer
prerequisite_conceptsobject[] | null
results_metricsstring | null
updated_atstring | null
curl
curl 'https://api.papervantage.com/papers/1/insights'

GET/papers/{paper_id}/projects

Get Paper Projects

Website sign-in only
Parameters
NameInTypeDescription
paper_id *pathinteger
Response: ProjectResponse[]
FieldTypeDescription
created_at *string
descriptionstring | null
id *integer
name *string
paper_countinteger
curl
curl 'https://api.papervantage.com/papers/1/projects' \
  -H "Authorization: Bearer $COGNITO_ACCESS_TOKEN"

POST/papers/{paper_id}/read

Mark Read

Website sign-in only
Parameters
NameInTypeDescription
paper_id *pathinteger

Response: any

curl
curl -X POST 'https://api.papervantage.com/papers/1/read' \
  -H "Authorization: Bearer $COGNITO_ACCESS_TOKEN"

POST/papers/{paper_id}/validate-references

Fire-and-forget trigger for services/reference_validation.py's

Site owners only

claim-extraction + citation-resolution + judgment pipeline (Section 3 -- reference validation, on-demand per-draft). Same background_tasks.add_task fan-out ingest_paper uses for distill_paper_task/embed_paper_task, rather than awaiting the full multi-LLM-call pipeline inline on the request.

Returns immediately with a "triggered" status; results land as PaperCitationValidation rows, readable via the validate_references MCP tool (app/mcp_server.py) once the run completes.

Parameters
NameInTypeDescription
paper_id *pathinteger

Response: any

curl
curl -X POST 'https://api.papervantage.com/papers/1/validate-references' \
  -H "Authorization: Bearer $COGNITO_ACCESS_TOKEN"

POST/papers/backfill-chunks

One-off/periodic backfill of PaperChunk rows (services/rag.py) for

Site owners only

papers whose PDF extraction has already succeeded but haven't been chunked+embedded yet -- same rationale/shape as backfill-insights above, for the RAG chunk store instead of PaperInsight.

Response: any

curl
curl -X POST 'https://api.papervantage.com/papers/backfill-chunks' \
  -H "Authorization: Bearer $COGNITO_ACCESS_TOKEN"

POST/papers/backfill-embeddings

One-off backfill of Paper.abstract_embedding for papers ingested

Site owners only

before embedding generation was added to ingest_paper. Same authenticated-but-not-owner-gated pattern as the other bulk admin endpoints on this router (fetch-all-citations, extract-all-references).

Response: any

curl
curl -X POST 'https://api.papervantage.com/papers/backfill-embeddings' \
  -H "Authorization: Bearer $COGNITO_ACCESS_TOKEN"

POST/papers/backfill-insights

One-off/periodic backfill of PaperInsight rows for papers whose PDF

Site owners only

extraction has already succeeded but haven't been distilled yet -- covers both papers ingested before distillation existed, and the ordinary steady-state case where distill_paper_task's ingest-time fan-out call (services/ingest.py) ran before the separately-invoked, asynchronous pdf_extraction Lambda had produced a transcript yet, and so no-oped (see services/distillation.py::distill_paper's docstring). Same authenticated-but-not-owner-gated bounded-concurrency bulk-admin pattern as backfill-embeddings above.

Response: any

curl
curl -X POST 'https://api.papervantage.com/papers/backfill-insights' \
  -H "Authorization: Bearer $COGNITO_ACCESS_TOKEN"

POST/papers/extract-all-references

Extract All References

Site owners only

Response: any

curl
curl -X POST 'https://api.papervantage.com/papers/extract-all-references' \
  -H "Authorization: Bearer $COGNITO_ACCESS_TOKEN"

POST/papers/fetch-all-citations

Fetch All Citations

Site owners only

Response: any

curl
curl -X POST 'https://api.papervantage.com/papers/fetch-all-citations' \
  -H "Authorization: Bearer $COGNITO_ACCESS_TOKEN"

POST/papers/grow-graph

Manual trigger for the same graph-driven growth job the nightly

Site owners only

scheduled Lambda runs (see infra/graph_growth.tf) -- useful for testing without waiting for the schedule.

This runs inside the backend Lambda (120s timeout), unlike the nightly one (900s), so the run is given a budget that ends it well before the Lambda would be killed.

Response: any

curl
curl -X POST 'https://api.papervantage.com/papers/grow-graph' \
  -H "Authorization: Bearer $COGNITO_ACCESS_TOKEN"

POST/papers/ingest/arxiv

Add a paper to the library by arXiv id (the website's search box does this for a pasted arXiv id/URL)

Website sign-in only
Parameters
NameInTypeDescription
arxiv_id *querystring
Response: PaperResponse
FieldTypeDescription
abstract *string
arxiv_idstring | null
authors *string
categories *string
citation_countinteger
classic_rankinteger | null
created_at *string
dislikesinteger
doistring | null
hot_score *number
id *integer
is_classicboolean
likesinteger
match_reasonstring | null
match_scorenumber
pdf_urlstring | null
published_datestring | null
relevance_scorenumber | null
source *string
summarystring | null
title *string
viewer_ratinginteger | null
viewer_readboolean | null
curl
curl -X POST 'https://api.papervantage.com/papers/ingest/arxiv?arxiv_id=1' \
  -H "Authorization: Bearer $COGNITO_ACCESS_TOKEN"

Next: Projects (website)