Sections
Overview

API reference

One API serves the PaperVantage website, the MCP server and pv, the command line. Everything an AI agent can do through MCP is a route here, and an API key reaches exactly those routes.

Getting started

  1. Create an API key on the MCP setup page (choose any client and the API key option). It is shown once.
  2. Call https://api.papervantage.com with the header Authorization: Bearer <key>. (Dev: https://api.dev.papervantage.com.)
curl 'https://api.papervantage.com/auth/session' -H "Authorization: Bearer $PV_API_KEY"
# {"user_id": 42, "member": false, "assistant_turn": false}

The website signs in with Cognito and sends its access token the same way. Routes marked Website sign-in only or Site owners only accept only that token, never an API key, so a leaked key can't reach your account, billing or key management.

Quota

The free plan includes 100 calls per rolling 30 days; members are unlimited. A request with an API key is one call. To count several requests as one (an MCP tool or a pv command that needs more than one), send the same X-PV-Call id on each: it is charged once. Website use is never counted. Over the allowance the API answers 429:

{"detail": "Free plan MCP limit reached (100 tool calls per rolling 30 days). Upgrade for unlimited calls: https://papervantage.com/account"}

Errors

Errors are JSON: {"detail": "message"}.

A write by the in-paper assistant can instead answer 202 with {"status": "pending_confirmation", "pending_action_id": 7, "summary": "..."}: nothing changed until the member confirms it in the app. Other clients never get a 202.

Headers

Limits

Each request has 30 seconds to finish. Long work returns early and is polled: creating an animation waits at most wait_seconds (keep it at 25 or less), then you check it with GET /animations/{animation_id}; imports report progress at GET /papers/imports. Lists are paged with limit and an opaque cursor (pass back next_cursor); search and the feed use page and per_page.

pv, the command line

pv wraps this API: one command per agent route below, JSON output when piped, and documented exit codes. Each command counts as one call.

Not published yet: pv isn't on PyPI, so it can't be installed yet. This is how it will work.

pv auth login                     # paste your API key
pv papers search "diffusion models"
pv projects add-paper 7 123 456
pv schema papers search           # a command's parameters and result, as JSON

MCP

AI clients such as Claude Code, Claude Desktop, opencode and Codex can use these routes as MCP tools. Each route below names its tool. Set-up instructions are on the MCP setup page.

Routes

API key or sign-in

Website routes

Documented for completeness. They need a website sign-in (or are owner-only or public) and don't accept an API key.